Microsoft 365 Community Community Demos, 21 Oct 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: SPFx Design Patterns – Property Panes

Description

In this 16-minute developer-focused demo, Hugo Bernier explains how Property Panes are web parts designed specifically to configure affiliated web parts. Types of property panes and code reviewed in this demo include Single, Accordion (collapsible sections), and Steps (options presented shaped by previous selectins). Ease of use is a primary design criterion. When to use/not use a property panes is predicated on directness. See property pane samples in the SPFx samples repository. This PnP Community demo is taken from the SharePoint Framework and JavaScript Special Interest Group (SIG) – Bi-weekly sync call recorded on October 21, 2021.

Demo Presenter: Hugo Bernier (Microsoft) | @bernierh

Related materials:
• Survey - Next SPFx Design Patterns Topic – November 4, 2021 | https://forms.office.com/pages/responsepage.aspx?id=v4j5cvGGr0GRqy180BHbR8ke1rGfE-VNsUHrnMWCrL5UN1dHRUYxV01CUkJESktKMENBQldURVpRWiQlQCN0PWcu&web=1&wdLOR=cC640D9E0-C403-405A-9EF1-D9F43B6ADF90

Learn more:
• Learn more about the Microsoft 365 Patterns and Practices community at: http://aka.ms/m365pnp
• Visit the Microsoft 365 Patterns and Practices community YouTube channel: https://aka.ms/m365pnp/videos

A

My name is hugo bernier, I'm the world's laziest developer, and uh you know what we. What we've started to do is a series of sessions around design patterns around sharepoint framework, and the ultimate goal is at the end of the season right, we'll actually have kind of establish some best design patterns, both in terms of user experience and coding, but we're also hoping to start going towards. You know creating ace cards as well and make that transition easy for everyone.

A

Last time we spoke, we covered uh performance on asynchronous rendering there was a bit of a of a heavier uh session. The session is going to be a bit lighter, we're going to talk about property pains, so I'm sure everyone knows what a property pain is. But again, these sessions are about making sure that everyone has the same level of knowledge. So the property pain are those things in a web part when you click on the edit properties or edit web part. It pops up this.

A

This property pane that shows the web part name and then gives you some options right. It's pretty straightforward, it's very cool, but let's talk about the proper way of using these property panes and one of the things that we should probably start by pointing out is the the property pane itself. When you start a web part is designed to be 320 pixels wide, and that's not a random number that like visa picked, because you like that number.

A

It's actually because 320 pixels wide is exactly the the ideal resolution or dimension to actually have on a mobile device. So your web part property pane will actually take over the entire uh mobile device screen if you, if you enter in edit mode and it's going to render pretty awesome. Of course, if you have a cool surface duo like I do, then it's it's. You know it's irrelevant, but let's go back to uh the properties, property pain. Let's talk about the first type of property pain, which is the single pane.

A

So let me switch to my other desktop there. You go all right.

A

So if you can see my screen now, uh I have a whole bunch of web parts on the screen and let's talk about some of these web parts. uh The first one is kind of the image web part: the out-of-the-box image web part right and the out-of-the-box image web part.

A

One thing that you'll notice is, if you just drop it in it, gives you a nice placeholder and it says: hey, you need to pick a web part an image, and if you don't have an image selected, uh you kind of get the first stage, property pane, which says hey. You need to select something right once you pick an actual image, uh we'll just pick stock photography. Here there we go, I'm suddenly hungry. It actually gives you a a different property pain, a second stage, property pane which actually asks you to configure this.

A

So if you want to add text- and things like that, so that's one thing to understand is these property. Panes can actually be reactive and understand. What's going on and react accordingly to that, you got some web parts that are super easy to configure like the file viewer right.

A

The one thing they'll say: it'll, give you uh here: instructions at the top of the screen at the top of the property pane to say this is what I'm expecting you to do, and then it makes it super easy for you to configure and that's actually a good pattern to follow is tell your users what you're expecting uh you know, don't just drop them in in the middle of something, and just you know expect them to know exactly what they're supposed to do.

A

uh The uh the text web part has kind of some advanced property pane here notice that it doesn't really tell you what you're expected to do. It just shows you for some formatting options, and things like that. We'll come back to that, because that's actually another cool design pattern that we can talk about and the stream video I've noticed it's. I always have to click a few times before I get it stream. Video again gives you some nice instructions at the top.

A

This is what we're expected to do, because it might not be as intuitive for people how to use the stream video and then it gives you some options right. So the single property pane is actually very easy to to do by the way all these sample web parts that I've created are going to be made available in the spfx repository in case you're wondering so the single pane web part.

A

Here again, I just created a simple description and I know I have my gigantic mouse gets in the way here, but I got a description and then I've just got kind of a simple label, and that's what I'm going to show you the code for but you'll notice that I have another flavor here, which is just no description uh with just a simple text and we'll show you how to do that right now, cool. um So let's talk about uh some of the code that we're doing right.

A

So the first thing that you do when you have a property pane in your web part, is you kind of need to define a method called get property pane configuration when people click on that button to edit the web part, this function will get called and what the function is supposed to do is it's supposed to return a I property, pane configuration, and so really what we're doing is we're just doing a return here of stuff.

A

I property pain. Configuration has a bunch of pages now in a single property. Pane you'll actually have uh one page, but that page can actually have a few things. One of the things is the header right, so the the header is basically that text that that helpful text at the top. That tells you what to do and then it'll also give you the option to give some uh some groups.

A

So you have some groups, you return some groups and uh those groups. What I've done for this sample is I've actually returned a series of group fields in this case, I'm only returning a single field and that's what you saw where it says this is the field label.

A

Please enter some text right, that's kind of simple, but let's look at what we got out of that right. So there was a single pane web part with the description, a field label and the text. But if I wanted to have no description, you know I know it's going to sound like a really weird concept, but all you need to do is to hide the description by just not providing it or passing a null value.

A

Why am I saying this is as you'll see as we explore some of the out of the box web parts and their property panes? Some of them are actually using kind of weird variations of this, and you know some of you may have uh kind of navigated uh through a lot of documentation, to try to figure out how to make these configurations all right.

A

Now, let's talk about what, if I have a web part like this right that has- and this is actually an out of the box web part- that I've rewritten um to show highlighted content, but look at all the options are available on this web part lots of options. There's got to be a better way to do this. Well, thankfully, there's a law right. The law is called hyman law.

A

Those may or may not be the actual people that but they're, basically a british psychologist. His name is william edmund, hick and ray hyman, and in 1952 they already knew how to write web parts and what they did is.

A

Actually they found a relationship between the number of stimuli or choices that were available and a person's reaction time, given that that that stimulus, so specifically, what they found is the more choices I have to choose from the longer it takes for me to make a decision, and so when you bombard your users with too many choices, they have to take the time to interpret all those options and you're giving them work that they don't want.

A

um I like to call that if you live in the united states, uh you know I um I like to call that the cheesecake factory law, because the cheesesteak factory is a restaurant that has a menu, that's probably 72 pages long, and it makes it it takes forever for you to make a choice because everything looks good and you want to order everything.

A

So, let's talk about a new type of uh web part property pane that is called the accordion web part and with the accordion web part, what you can do is you can actually just create the same webpart, but you can create sections here and these sections are designed to actually make the choices a lot easier.

A

uh And yes, I, like uh louise, calls it uh choice, paralysis. So now the question is well how many? How many categories? Do I create how many choices within each category? Is there a rule? Well, it turns out. There is another law right, miller's law and again this may or may not be the right picture for george miller. I just googled it but george miller in 1956.

A

He came up with again. He was really cool. He was writing web parts back then, but he figured out that the number of objects that a person in average can hold in their mind and their working memory is about seven and it's often been called as the magical number of seven plus or minus two.

A

Now a lot of people actually say uh he meant it as a joke and it's not really the number, but it's actually a good rule of thumb. So in average, if you have seven choices, what will happen is most people will be able to deal with all those choices, but there's going to be a few people that are not going to be able to make sense of the last two choices they just won't. Remember those last two choices are available.

A

Of course, they'll read it, but they'll have to work harder to know that those choices are there so giving you a list of like you know, 17 fields on one on one property. Pane is not going to cut it for you.

A

You can go as high as 9, but keep in mind again that some people are not going to be able to see all the options and you can go as low as 5 choices and that's not a hard and fast rule, but it's just kind of a best practice in terms of how to render your your information to make sure that people can see.

A

So if you look at the two property panes side by side here, you'll see that it's really easy to configure the one on the right, because we made the choices easy does it have to do with content? Does it have to do with filtering and sorting or how I'm going to lay out the information?

A

So how do I do that? Well, the only thing that I really need to do is it: when I'm defining my property pane, I say display groups as accordion equals true and then, instead of having a single group like I had before, I can add uh more than one group and then in that group I can actually say whether I want that group to be collapsed from the start or expanded and so see.

A

Here I have one group, I have another group and I have a third group I like to start them as collapsed, uh but you don't have to now one thing that we have to make clear, though, if you give choices to people, just remember that those choices should make sense, don't put cryptic choices behind property pains that are collapsed because people are not going to know. um You know how to make sense and how to pick the which one is the right door right.

A

It's going to be more a game of uh guacamole, uh yes display group as an accordion is an out of box parameter unless I misspelled it right. Okay, so really quickly, because we're trying to cover a lot uh today, um we also have another type of property pane, which is steps and the steps. Property. Panes are kind of a specific thing, because one thing that we want to do is we always want to avoid the types of things where you know.

A

I have options in one group and they're related to another option in another group, and then, if you put the wrong value in one group, then we're telling you oh you know this. Other group has an issue with the choice you made and stuff like it. Just becomes a nightmare from a user experience perspective, so you can actually use steps right where you can say hey. You know uh we're gonna start with step, one where we're gonna pick and we're gonna pick a data source step. Two we're gonna. Do this step three we're gonna!

A

Do this, so we're gonna make these choices based on on what you've done. So this is where you can guide your users through it to make I'll skip the demo for the the steps here, but I'm going to show you uh the one thing that you do again is we continue using. uh You know before we had groups, but we defined only one page that we return in this case, we're actually going to return a whole bunch of pages. This is going to be the first page.

A

That's going to have a couple groups we're going to have a second page, that's going to have a whole bunch of other groups, and now we're going to have the third page and the great thing about that is when you're using pages again, it will render this in a nice flow-through wizard that you're able to guide your user through now. The question is: when, should I use a property pane, because you know I've seen a lot of people that will actually use property panes, sometimes where it's not?

A

Ideally, uh the best choice, and one of the things that we want to consider is the concept and user experience of directness.

A

So the more users can directly interact with something the better it is for them, and here's an example we're going to go to the web parts again and we're going to look at the uh text web part right there text web part. Imagine if I wanted to actually enter text here and the only way that I could do it would be through the the property pane right. It would be kind of unnatural for me to actually go in here to edit the text.

A

I want to be able to type the text here and I want to be able to. If I have advanced functions, then I want to be able to go the property pane and make those changes so wherever possible, you want to make sure that the the stuff that people will edit will be as direct as possible. Here's another example here: the sites web part right.

A

We have a title for the web part a lot of people like to put the title in the property pane, but if you can just do it here right, these are the cool things right that I want to show right whatever. I can't spell today: that's the most natural experience: don't force people to go the property pain because, especially in a property pain like this, where you have a lot more choices to offer, it might just overwhelm the user all right.

A

I got one more minute, so we're gonna skip some stuff today, but let's talk about what we want to do next, I don't know if you're old enough to remember these choose your own adventure books, but we've decided to start leaving it up to the audience to vote on what they want to talk about. Next choose your own spfx adventure. There's three choices.

A

We want to talk at our next session about how to handle custom properties, including saving things, but also making properties that can be searched uh by sharepoint, uh how to extend property pains and how to improve performance. Now, don't worry we're going to cover every one of those. We've got lots of content to to cover these, but what we want to know is which one do you would you like to see next, which one is the most urgent for you, so we have a form that's available here. I think david's going to be pasted.

A

The link he's already done it and we have a qr code because we are cool like that. uh So we're going to open the poll for the next week until next thursday's committee call and then we'll be presenting what people voted for. That's it for me. Thank you back to you, patrick all, right. Thank you. Hugo.