Microsoft 365 Community Community Demos, 30 Dec 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: SPFx Design Patterns – Custom Web Part properties (Part 2)

Description

In this 17-minute developer-focused demo, Hugo Bernier centers on Property Pane Field types and defining those types. Look at Property Pane fields, helpers, binding, property interface, attributes, indexing attributes, preconfigured/default values and dynamic values. Ways a user can edit a web part – rich text or through properties. Adding methods to first party web parts and defining attributes that enable people to browse, search, subscribe to your web part content. This PnP Community demo is taken from the Viva Connections & SharePoint Framework Bi-weekly sync call recorded on December 30, 2021.

Demo Presenter: Hugo Bernier (Microsoft) | @bernierh

Supporting materials:
• Demo - SPFx Design Patterns – Custom Properties (Part 1) | Hugo Bernier (Microsoft) | @bernierh, November 4 | https://youtu.be/8QrZOw4UmL0
• 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

My name is hugo bernier, I'm a cloud solution architect at microsoft, and today I'm going to be talking to you about custom properties, part two, because a few weeks ago, or maybe a few months ago now we actually started with part one and we kind of ran out of time. But uh you know these presentations are part of a series of presentation around sharepoint framework design patterns. This is about how to not only you know, get started with using some of the technology like spfx, but also how to best use these things.

A

So what are some of the human interface design, user experience, principles and things like that, as well as teaching you some tips that you might not know about, even though you may have been using spfx for a while. So, let's get started when we last met our heroes. We were talking about property panes and, if you don't remember, property panes, it's that thing that when you click on configure a web part or an adaptive card extension or teams up it, pops up that thing that allows you to configure it.

A

And when we last presented, uh we talked about all the various property field types- and this is just a an example of some of the property field types that are available. But if you remember how we defined those property fields and ejazz just showed an example of this. But in your web part itself in the webpart.ts, you usually have a method called getpropertypin configuration and getpropertypen configuration returns.

A

An I property, pane configuration interface.

A

So it's a class that or it's not a class, but it's a structure that needs to have these attributes and it needs to return a bunch of pages, a bunch of headers or a header and a bunch of groups and inside of each group you have something called group field and it's an array. So you know we'll open the array with uh square bracket and then we'll pass the individual fields that we want to display with a comma.

A

So here I have boolean field and then we go through all the fields, all the fields that I showed you and we end the array and that's really what we have to do to actually render some some property fields and property pane. Now, unfortunately, you know it would be cool to be able to just uh drop some actual fields in the code, but we can't so in the code.

A

What we end up having to do is we have some helpers for each of the first party property pain controls, as well as some of the third-party property paying controls, there's usually a helper that, for example, here if I want to create a new property pane check box, I can just call property pane checkbox. Now you may have noticed that ejaz used the new property pane async drop-down, that's actually how normally you would do you know anytime. You want to create a new component, a new, a new object.

A

You would create new something something, but each one of these controls have a helper that will automatically create a new and it will use the parameters that are passed to actually understand how to create that. So here I have a property, pane choice, group and so on and so forth. We have my drop down. I have all of them right.

A

I won't walk you through every single one of them, but those are all very handy helpers that will create those fields for you now how I bind to those properties, you'll notice, that for my checkbox I have a property in my web part that I called from choice and from choice uh or from checkbox from choice and so on and so forth. Right now, I probably didn't use the best naming convention for my properties here, but again it was for the demo purposes.

A

I was trying to show that this is binding to a check box or a choice or drop down. But where do these properties come from? Well, in your web part, you have the ability to create a property interface, our web part property interface or what we call props here I called mine. I my webpart props and I have an attribute for each one of those values.

A

So, for example, I want to show my checkbox and because we're using typescript well, we want our very values to be strongly typed, so I will specify that this is a boolean. My choice is going to be a string and so on and so forth.

A

So now we have used the method to actually render the list of property pane controls, we've defined our properties and we've told sharepoint basically how to store this. Now. What if I wanted to set up some default values right so pre-configured values well in your web park, manifest so see here at the top I say, mywebpart.manifest.json.

A

On my manifest, I actually have pre-configured entries, and I have properties, and here, for example, I've actually defined. You know my checkbox. I want it to be true, my choice I wanted to be spring and so on and so forth. You can absolutely do that, and the great thing about that is every web part can have more than one manifest and those values can also be localized as well.

A

So we'll we'll talk about that in a in a different session where we talk about localization so, but what, if I wanted to create default values that are maybe dynamic right? So what if I wanted to create the default value is today's date or I wanted to calculate some values or maybe I wanted to pick some values conditional values based on another value. That's been selected.

A

Well, you can't really do that in your manifest, because the manifest is intended to be static, but you can do it in your web parts on init method.

A

So the method, as you can imagine, gets called when the web part gets initialized and it returns a promise so that, in other words, it's basically says, look I'm not going to wait for this web part to to render the on edit or to to return the on in it. I'm just going to create a promise and when you're done just let me know, and that way your web parts are a bit more responsive, you're able to actually uh the system is able to go to every web part and say hey just so.

A

You know we're about to render you we're about to so please go initialize yourself and I'll come back later to render you so when we do that, one of things that we can do is we can just return a new promise and in this case I'll I'll, actually return the promise I'll create an arrow function so that I don't have to create a whole. You know, name function somewhere else and then I'll initialize, the data. So in this case I'll just say the date.

A

If the date is undefined, then I want to set the date to today's date. Now for the purpose of the demo, I pretended I already.

B

A

A variable called today's date, which had today's date. Now you probably want to make sure that you verify that your properties are are undefined or they're valid. So right here you probably want to make sure that before you override the the setting that you always make sure that it's undefined, but you could also do this. Let's say a new selection has been made and you want to invalidate another option because it's no longer a possible choice or sometimes you have connected values.

A

So, for example, if I selected option a, I want option b and e to be available, but if I selection option b, I don't want d and e right.

A

One of the things that people tend to forget about is they tend to forget to uh override those values and set them to null so that behind the scenes you might not be making the the in your code, you might not be making provision for the fact that you know oh d and e are populated, even though the the user has selected option b.

A

I'm just going to render you know as if d and e were selected so use this. This approach to actually kind of invalidate and verify that the the properties are configured properly. Now you might say well why? Wouldn't I just do this in the rendering code right? What why wouldn't I? Just when I render the the the control the web part? Why don't I just make sure that all the values are are proper.

A

You should definitely always validate all the inputs that are coming in, but one of the things that we're trying to do here is one of the principles. Is you should make sure that all the inputs that are coming in from the webpart properties, the web part data itself- is always valid so that moving forward we're able to work with that assumption right. So that way, you always know that your code is is clean and has all the right attributes all right.

A

So your web part uh onit method then needs to resolve just otherwise your web parts gonna be waiting for you to resolve forever.

A

So that's good! So far, we've defined some properties, we've defined some uh web parts uh web part properties, some attributes and default values and fancy default values.

A

But what about an out of box web part like uh like this one here, which is uh what we call a first party web part right, a web part that was built by microsoft. Here's the quick links web part. Now the quick links web part has a few interesting things to it.

A

The first thing is: it's got a title property, but you may notice that the title property is not actually displayed in the property pane uh and that's because we we've talked about this before you want as much directness as possible. So if it's possible for me to directly edit a property in the edit window or in the canvas or whatever you call that that window there, you should be able to do that.

A

That's why the rich text webpart allows you to edit the rich text directly in the page itself, not through the property pane. But what about this thing here we have a whole bunch of links. Is that a property is that content?

A

And is it something you should be able to search? Well, here's a problem right. uh We probably don't want our users to be like confused. You know I thought I found a web part that had this word in it or this title in it, how come I can't find it well, we have to remember that when people discover content, we tend to discover content in three ways. One is we browse and browsing is kind of clicking around going to a page and finding content through discovery process now.

A

The other way is, if I know exactly what keywords I'm looking for, I should be able to search and searching, allows you to use a keyword and find the results you want usually but here's the problem. What, if that web parts content, which is maybe stored as a property?

A

What if that content is not searchable, so I have an example of a web part that I built that is called uh office hours right, which allows you to if you have, if you have a department or something like that, you can actually drop the web part on a page and you can specify what hours uh business hours whatever right. So what?

A

If someone's looking for office hours and you've dropped a web part on a page and that's the only thing in the entire sharepoint site, that has the words office hours and your users are like, I could have sworn. I saw a web part somewhere. I saw something, they don't know it's a web part right. I saw something on a page that said office hours and I just can't find it.

A

So that's the problem and that's one of the things we have to solve. The other thing we have to consider is the third way that we discover content is through subscribing and subscribing we're not talking about like the alert me thing it's more about either the system determining by your previous actions or you by indicating I'm interested in this you're telling the system that, if something happens, that's new related to this. I want to know, because I'm too busy to actually look for more content.

A

Let me know when there's new content show it to me on. You know my my summary show me issue it to me in an adaptive card or something like that.

A

Now, let's look at another web part, so this is the markdown web part, which is another great first party web part, and it allows you to actually create markdown content using the same principles we've talked about. You can actually go into the web part you can edit the web part, but what? If I had a whole article here or a whole, I know company policy is written as a markdown entry. In a page again, your users don't know that it's a web part.

A

They just think it's content, so how I can make that content searchable subscribeable and, of course, it's going to be browsable, because I can click to it and I can find it well in your web part. You have a method called get properties metadata.

A

That method is probably not in your default web part, but you can actually add that method and what it does is. It returns an I web properties metadata and it gives you the opportunity to return basically a key value pair of for every property that you want to define.

A

You can actually say that this property can be searchable, can be an image. It can be a a link or something like that. Here's that work so, for example, here my title property, which I didn't show through the property pane, but it's still something that I've exposed through my web part. I probably want people to find my web part through through the title.

A

So if I have a web part called office hours, I should be able to find it and to do that, I'm going to say is searchable plain text equals true and that basically says that the title attribute when I store it will be searchable and it's going to be plain text.

A

I could also store html values in my web part, and you can absolutely do that. You can actually say, is html string equals true?

A

If you have an image and your web part stores an image, you can actually say that it's an image source now the cool thing about image sources is, it will know also if you move images around and things that it will understand that it will try to update the properties or at least that's the theory. I've never actually tested that and same thing with urls.

A

Now. Why would you do that? Well, one of the things that I've done in the past is I've created the web part that creates a markdown charts and one of the things that I do is when I get the markdown I parse the markdown.

A

I extract only the text so that people can actually- and I make the text a searchable plain text or I could convert it as a html and make it the html string, but the great thing about that is when you do that now, your users are actually even though you're rendering a chart, something that is visual and that's usually not searchable, because I have a hidden property that is stored as a plain text or as html string.

A

Now my users are able to find that chart, no matter where it is placed in my in my sharepoint environment, because the attributes are indexed all right. So let's wrap this up next we're going to be talking about extending property pane, so adding new types of controls, like we've seen earlier today, we're going to use the property, pane controls and we're going to show how to validate properties.

A

These are some of the articles that I've used to describe some of the principles today, but that's it for me. Thank you. Everyone have a good day.

B

Awesome hugo, thank you so much. These are really fantastic sessions on setting the the guidance for the design patterns and development patterns, excellent job, great feedback in the chat as well.