Microsoft 365 Community Community Demos, 4 Nov 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: SPFx Design Patterns - Custom Properties (Part 1)

Description

In this 11-minute developer-focused demo, Hugo Bernier delivers a refresher on Out-of-Box (OOB) Property Field Types – Boolean, Choice, Slider… with practical tips for deciding which types to use to deliver concise and predictable options to user. This demo was cut short due to technical issues, so Part 2 to be delivered in a future call, will focus on custom - not out-of-the-box Property Field Types you may want to add to your solution. This PnP Community demo is taken from the SharePoint Framework and JavaScript Special Interest Group (SIG) – Bi-weekly sync call recorded on November 4, 2021.

Demo Presenter: Hugo Bernier (Microsoft) | @bernierh

Supporting materials:
• Documentation - Make your SharePoint client-side web part configurable | https://docs.microsoft.com/sharepoint/dev/spfx/web-parts/basics/integrate-with-property-pane
• Documentation - Integrate web part properties with SharePoint | https://docs.microsoft.com/sharepoint/dev/spfx/web-parts/guidance/integrate-web-part-properties-with-sharepoint

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

These sessions are called spfx design patterns and what we're trying to do is we're trying to level up everyone, so you might say: hey you know what these are. Some boring topic entry-level topics, but we're always trying to cover some kind of easy stuff to learn as well, some more complicated stuff, and today we're going to be talking about custom properties and by custom properties.

A

We mean uh you know the properties that are not out of the box in uh spfx web part or via connections or any of these things, um and that where you want to add them to your solution and you want to expose them either through the property pane or through the body of your web part and again, you might say, hey hugo, you know I know how to do custom properties.

A

I would say well, first of all, I can't hear you, but second of all, um you know we're gonna, I'm gonna try to show you a few things that you may not already know about, and if you already knew about it, then it's a good refresher, all right so out of the box and we'll talk about some ways that you can extend this. But out of the box there there are a few property field types that are available to you. You've got some check boxes, some radio buttons or choice groups.

A

You've got some drop downs, you've got some sliders, a single text, multiple text and toggle and we'll go through them in detail. But the the process is all the same.

A

And if you remember our last session, we talked about how the property pane configuration is done through exposing or kind of responding to this event, which is a get property pane configuration and it expects you to pass an interface of I property, pane configuration objects and ultimately, what you're going to be doing is you're going to be passing a bunch of group fields or a bunch of fields that are going to expose the properties. This is a standard one.

A

You know the regular text field and we always point to the property that we want to bind to. But let's look at some of those additional property types that we have available.

A

The first thing that we do and if you're doing by the way, spfx kind of older version of spfx, because you need support for 2019 or 2016. You know these objects are actually still found. I believe in the base web part library, but in the newer versions of spfx. All these objects are found in the sp property pane which we'll cover shortly.

A

So we have a few things that we want to import here and in this case I'm importing kind of every single thing that I want to use. You probably don't need to import as many controls when you do it for yourself, but it's all coming from the sp property pane uh library all right. So let's look at. Let's start with the first one. Oh I don't know where that microsoft logo showed up. um Let's look at the boolean field right.

A

The boolean field is actually implement through implemented through a checkbox, and so the control is uh rightly named uh property pane checkbox again I created a property in my web part that I called the from check box. You could call it whatever you want and then I have a label associated to it, and then I say, is it checked? Yes or no, and one things that you'll notice here is that you know you could just say: is a check and just buy into the? Is it check?

A

Boolean control, but one thing you have to remember is your web part may not have been initialized when you first drop it, so it might not either be true or false, or you might not be getting the behavior that you're looking for right that you're expecting so one little trick here. Is you know I always do this? You can you can choose not to do it if you want, but I always make sure that I do. Is it checked and is it equal to true right that way?

A

I know that if it's, uh you know a falsie value, it's going to be evaluated properly, and I know the truthy values are going to be evaluated properly. It's just a little trick.

A

All right, let's go quickly because we have a lot of stuff to cover. We also have choice, fields and choice. Fields, allows you to put a bunch of radio buttons and allows you to do kind of a mutually exclusive set of choices.

A

So, for example, I can only pick one season here, but there's also other ways that you can use it. You may have already have seen this control in use in the out of the box web parts. You know, for example, the layout grid is actually or layout attribute of some of the web. Part is done using this type of control and I did a custom one below where I'm using kind of custom shapes and custom icons.

A

Let me show you how we do that. The first thing we do is we'll import, the property, pane choice, group and obviously we'll bind to the choice, free property that we want and then we're going to pass the options. Now, if all I'm doing is I'm showing text like I showed for the seasons you just put the key and value or the key in the display text that you want. That's pretty easy, but if you want to show ooh that was funky.

A

If you want to show some icons or images, one of the things that you can do is you can actually pass up to two images, one which is the selected image and one which is the image source. That is when the item is not selected. So if you want to have a fun image, that's different when you select the item and it's the current active one, you can absolutely do that in my case. What I'm using is I'm using the exact same image for when it's selected and unselected, and how do I answer these images?

A

Well, one of the ways you can do that is. You can just use something like this, where you're using require. I happen to like defining a variable for my requires, so that I can reuse that object multiple times in in my class.

A

In this case, I could have just put the required directly in the thing, but if you remember, I used a layout break object twice in that in that code, so I kind of wanted to do one require and use the object twice, but it's really creating a string that points to the the in this case an svg file I like to use svg, because I always want these icons to look nice and crisp, and I know you can't tell through the screen share but they're, nice and crisp all right.

A

Let's move forward, we also have a choice. Field and choice. Field is really a a property pane drop down control and that control is actually what it will do is we'll list a whole bunch of options. So in this case I listed a list of months right now. One thing that I want to point out for from a user experience perspective, because we see this all the time. You know if you see a drop down and you see the word january or you know alabama or uh I don't know something like that.

A

You can probably guess what's behind that drop down, and you know you got a good idea, but what if you know, I put something- I picked a picked a random word here, but what, if there's a word like this and that's the medical term for ice cream headache? But so what? If I have this word right? What does it mean to the users?

A

It might not mean anything and using a drop down box for terms that people are not familiar with is usually not a good idea, because they won't know what other choices are behind the drop down box. So if you have situations like this, it might be better for you to show them the previous control right, which will list all the options.

A

The other thing that's important is that when you show them a list of drop down, options may sound obvious, but you want to make sure that it is a predictable order right. It's either alphabetically or in this case, by order of month, just so that people don't have to read through every single choice in order to find the right one. Because remember last time we talked about miller's law and higgs law and how people feel stupid when they can't find things and it slows them down.

A

This is one choice. One one opportunity to make people feel better right that they're not they're, not silly, when they're reading through this list and they're not using all their energy.

A

We also have the slider field right, which is just for numbers and things like that. But let's move on to the the fun stuff. I don't want to show you this boring stuff. Let's move quickly to this uh this control here, so we have the toggle field in the toggle field. Remember I showed you the checkbox field area. Now we have a toggle field and it seems to be doing the same thing it's pointing to.

A

um It seems to be pointing to the boolean control and we do the same thing as we did before right. We except we now have an on and off text, and we also do the. Is it equal to true thing trick that I showed you before, but why would you use a checkbox versus toggle?

A

Well, if you've ever used an iphone, I'm not lucky enough to use an iphone, but if you ever use an iphone or our android phone, you know that there's toggle buttons that are used, and one of the trick is that the toggle button should always have an instant reaction, and it should be reflected immediately. So, for example, when I toggle the airplane mode on my phone, you can see that I go from having connection to you know when it's turned on.

A

I don't have connection it's reflected immediately and if those actions are not immediate, one of the things that we want to make sure is that maybe we don't want to use a a toggle. Maybe we want to use a check box right and again, it's just a part of being consistent in your behavior.

A

The other thing we want to do is make sure that your labels are concise and non-neutral right, so avoid super long text here, where you should be able to say something like instead of saying I know, do you want to receive email, notifications from us just say: email, notifications or text notifications, and in most cases you shouldn't even have to use the on or off label, because it should be painfully obvious.

A

Thank you. Hugo great work, as always,.