Microsoft 365 Community Community Demos, 5 May 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: SPFx Design Patterns – Property pane exception handling

Description

In this 16-minute developer-focused demo, Hugo Bernier suggests how to avoid making your users feel bad through poor information collection design. In this 6th and final installment on property panes, use proven PnP property pane controls and validation methods in your reusable SPFx solutions. Step through installing the propertypane library in your VS code environment, then add and configure a control in a web part. Session wraps with design (error message) etiquette recommendations. Design apps your users will love! This PnP Community demo is taken from the Viva Connections & SharePoint Framework Bi-weekly sync call recorded on May 5, 2022.

Demo Presenter
• Hugo Bernier (Microsoft) | @bernierh

Supporting materials
• PnP Tool - Reusable property pane controls for the SharePoint Framework solutions | https://pnp.github.io/sp-dev-fx-property-controls/
• PnP Tool - PropertyFieldListPicker control | https://pnp.github.io/sp-dev-fx-property-controls/controls/PropertyFieldListPicker/

Learn more
• Microsoft 365 Unified Sample gallery - https://aka.ms/m365/samples
• Microsoft 365 Platform Community in YouTube - https://aka.ms/m365/videos
• Microsoft 365 Platform Community - http://aka.ms/m365pnp

A

All right, so, uh yes, this is part. Six uh we've been talking about custom properties and design patterns, and the one thing we want to talk about here is: we want to make sure that, when we're talking about design patterns here, we're not just showing you how to use code but how to design applications that your users will fall in love with and that your users will find beautiful and easy to use after this session we're going to move away from custom properties.

A

Finally, uh because we're going to have more sequels in the fast and furious at this space and we're going to start talking about content, but today, let's focus on custom properties. My name is hugo bernier. I work at microsoft, I'm a senior cloud solution architect at microsoft, and uh you can see my blog here on my twitter account, but just one thing my blog is currently down under maintenance because we were so busy building the new microsoft 365 community blog that I neglected my own blog, but we'll be fixing that very shortly all right.

A

So, let's recap a little bit so far. We spent most of our time on uh property, panes and again. The reason for that is because we want to make sure that your web parts are configured properly and they're reusable right. We don't want to create single use web parts. We want to create reusable web parts as much as possible. I want to make sure that we bound properties to property, pane controls and how to validate them. Now, let's do a little recap here on how we validate so here on this web part.

A

We have kind of two validations that are built in one is the field is required and two is. If I put like a really long description, uh it'll, say: hey, you shouldn't be longer than 40 characters, so those are two validations right and let's do a little refresher on how we do the code for that.

A

So the first thing that we do is on your web part. So in this case, mywebpart.ts you have a method called getpropertypane configuration and all we need to do is we need to actually pass the individual fields that we want and bind them to the individual properties and how we get. The validation is by passing on get error message where we're going to pass it basically a string and it will return a string and the string if the string is empty. It means there's no error message.

A

If the string has something it means, there's an error and it will be displayed.

A

So the validity description is very simple right and it's probably not the best code here, but again I was trying to make it as simple as possible. The first thing is: if the value is null or if it's been trimmed and it's null, then we say: please provide a description.

A

If the value is greater than 40 or the length of the value is greater than 40, we say: hey, please don't make it too long and then, if else we just return nothing.

A

Now we go back again to that web part, and we look at that validation here. Let's do that.

A

Now we have a list web part and the list web part are sorry, not list property, a list property where we ask people to enter the list. Name and you'll, see here as I'm typing it's starting to scream at me. Saying: hey this list doesn't exist all right. Well, let's, let's actually talk about how we want to handle this, and the best example that I like to use.

A

When I talk about user experience, is those fancy atm machines right or I guess I should just say atm where you can go, get cash right and you can withdraw cash out of the machines now, the typical user interface and this I actually took this from a local bank- and I rebranded it, but typical atms will allow you to enter an amount or allow you to pick from choices and then so I'll start typing right. I'll, take 53.75.

A

And I'll say: oh invalid right, because you can't put decimals in the amount that you want to take up so, okay I'll just change that I'll enter 50 and I'll say: oh, no, sorry, only multiples of 20 are accepted and it'll continue like that kind of screaming at me until I get it right, but the one thing we want to make clear is that when users are being faced with error messages like that, that's really what they see is something like this.

A

It's like, why can't you do anything right and there's a reason why people have a tendency to not to like computers is because they tend to feel stupid when they use computers.

A

So one of the design patterns that we'll talk about today is how to not make our users feel like garbage by using some code and by using some user experience, and the first thing is avoid the air from happening in the first place, and when I was looking for images here, I was actually going to put a picture of bruce lee where he used to say the best way to never lose a fight is to not fight in the first place. But let's just use this one for now.

A

So the first rule is: don't create opportunities for people to uh to have errors right. So if you think about that atm experience, why did it allow me to enter decimals in the first place, when all I can do is then and withdraw increments of 20.?

A

um And let's look back at our example of validating the description just to show a parallel here. So if I go back to my description here- and it says, I can't enter uh anything longer than 40 characters.

A

Well, that's an opportunity right there that for errors that doesn't need to be there, because what I could do is we can actually go to our property pane and right here we can actually say that the length max length is 40..

A

That way I mean I really don't need to have the validation that exceeds uh greater than 40.. But you know, let's remember from our last session, that you should always also validate stored values, not just uh entered values right, so I always try to keep my validation there, even though I'm going to try to prevent the users from making the mistake.

A

Okay, but now, let's go back to our list right where we enter the list names and I'm sure you folks have never had this issue, but I run into this issue all the time. Should I be entering the display name. Should I be entering the you know the the escape name? Am I entering the good you know did I did I do I put a slash in the in the name?

A

You know, there's all sorts of things that I don't know what to do and again it makes me feel uh inappropriate inappropriate as a as a user right. It's like. Why can't I get this done right and then we'll give a message like this right. The list test doesn't exist on the current site.

A

Now this is where it's a good idea to use some help, and one of the things that you should look at is the pnp spsx property controls, library, which has tons of reusable property, pane controls for your sharepoint framework solutions that you can use to do some really cool stuff, and so, let's just look around. We've got some controls here. uh Tons of controls, as you can see, you know, for editing code for picking colors uh dates and things like that and we'll review those a bit later.

A

But the one I want to use is the list picker and the list picker allows me to actually list lists on my site so that I can you know, validate the list properly, and so it's got. Every single control has the full instructions on how to use the control and it's mostly copy and paste. So the first step is to go back to my library and to add a dependency right and we'll do that by saying npm install.

A

And then we'll copy the add pnp and it's spfx.

A

I usually type way faster property controls, all right, okay and we'll hit enter, and then, if everything goes well, we'll get a the library installed. Now we go back to our web part and we'll actually just need to add a new import just so that this web part knows how to use the property field list. Picker and we'll also add a property, because we need to store our list now. The sample actually allows you to store both a multi-select list or a single list.

A

In my case, I want a single list, but if I made this an array of strings, I could have multiple lists or here and then, if we go back to how we add a property pane control, it's the same thing that we've done before, uh except now I'm using a different control that comes from this library and if you're wondering where did I get the code, I just copied and pasted the code right from the instructions so copy this paste it here and then I'll just do a little bit of customization right, so I'll uh update the label I'll, actually tell it what property I want to bind to.

A

If I want to, I can actually have it include the hidden list versus the non-hidden list, and you know how we sort and things like that. uh But then what we want to do here is there's a few other things like you know. Do I wanna I wanna bind when the property field is changed and some elements that the control is going to need to be able to to actually execute, and then this is where my error message.

A

Validation comes in where I can decide whether I picked a list or not, and then in my validation, I'll. Just do something like this. If I didn't get a value or if I got- and this is probably a little ugly, but it's a hard-coded value that is no list selected, then I'll say please select a list.

A

Otherwise I'll just return, no error message, and so now we're going to get something like this, where I can pick the list now, let's just be clear that the list that I see here is the list that I have permissions to see right. So we want to make sure that if you're doing things on behalf, the user users also have access to the list, um and that's really how the validation is done.

A

Now we could do the same thing if you are entering of colors or entering dates or things like that uh or even fancy things like uh you know, selecting people or even entering json or html, or things like that right. If you've ever tried to type json uh in notepad without syntax, highlighting it can get out of hand a little bit. So anything like this helps reducing the number of errors, but now, let's just do some rapid fire here on some design patterns. We want to use the first thing we want to do.

A

Is we want to make sure that we are polite, always polite when we give error messages right? So if I go to that web part again or a sample web part- and we have uh let's say a description field- and you know we don't want to scream at users and say: hey, you didn't enter a description, that's just not cool right. We want to make sure that we're polite and we say something like hey. Please enter a description.

A

That's way better, but we also want to be as precise as possible. We don't want to give generic error messages if we can, if we know what's wrong, let's actually tell our users. So, for example, if we say enter an email address, um can't just say invalid email, that's just not cool right. So maybe what's better is to say something like this hey. Please enter an email address with the format name at example.com right.

A

That is better because it makes sorry it tells our users exactly what we're expecting, but maybe I have another type of message which is like hey: please, don't use a work or school email address or something like. Maybe it's an error message, that's going from the backend and maybe we can say oops. I can't verify the email right now.

A

Please try again, so you see here I'm trying to be as precise as possible with my error message, because I'm telling the user exactly what is wrong and how to correct the behavior or in some cases you know please come back later well, we'll try to validate it.

A

The other ux rule that we always want to make sure is that you want to reduce the work. That's required to fix the problem. So an example of this is if it's asking you to enter a username.

A

Let's just go. Do that quickly and I enter user.

A

uh I don't want it to just like invalidate the error and like the field and then say invalid user right, a better user experience from this is maybe I mistyped it or maybe I copied and pasted there was a space or something like that. So instead you know keep that user there and say please. You know I can't recognize that username or uh that you know you can be fun with it. You can say: hey this user exists, that's really scary!

A

All right! uh We also want to make sure that we show where the errors happen, and you know where that's important I'll just go quickly here, because I want to make sure that you see this. But if you've got like multiple steps in your web part, property, pane and you've got validation across the panes.

A

Your users are not going to know hey, I could have sworn I entered uh or something that's valid here right and so please don't do cross pane validation. Try to validate in this spot. You want to validate as soon as we can. Obviously, but probably the one thing that we want to make sure that we do here. Is we want to make sure that we're flexible?

A

So, for example, if we enter a phone number, don't scream at people because they have a space or they have something like this, like you know, you're expecting a phone number, you can probably trim all the spaces all the invalid characters and validate from that try to be as flexible as possible, because remember that your users will remember the pecan rule, which is will will pay close attention to the most intense point in our user's journey and users will remember negative experiences more vividly than the positive ones, so don't give them the opportunity to feel bad because they're just going to remember that way more than the cool web part you built and, more importantly, be careful with your error messages, because this is a real site.

A

You don't want error messages like this, where you reveal bad information all right, that's it for me! Thank you! Everyone! Next time, we'll talk about web part content all right! Thank you, hugo, for that.