Introduction
Proceeding our dive into the PnP reusable property pane controls I want to cover the PropertyFieldListPicker control.
The PnP reusable property pane controls is a package that contains a lot of useful controls that can be used in any SharePoint Framework web part’s property pane, if you want to know more about this you can check out the official site here.
To demonstrate the various capabilities of the control I’ve created a sample solution which you can find here. The sample solution contains a simple web part that shows how the PropertyFieldListPicker works.
Visual Appearance
Before switching to the code section I want to cover the resulting user interface. Since the PropertyFieldListPicker control is used in the web part property pane I will cover only the property pane interface.
The web part with it’s properties displays as follow:
In the sample solution I’ve prepared there are different control instances:
Let’s have a closer look at the principal control instances.The minimal instance shows how the control displays with the minimal configuration and the default values.
The control is composed by a drop down control that displays all the lists accordingly to the properties set:
Since this is the minimal configuration the selection is defaulted to a single list selection. Clicking on an option will select it:
It’s possible to choose not to display the hidden lists, keep in mind that by default those are always shown. To choose if the hidden lists have to be displayed you can use the includeHidden property, in my test environment this is the result:
As usual with these kind of controls there’s the ability to enable multiple selection and this is displayed as following:
When allowing multiple selection it’s also possible to add an option at the beginning that allow the user to select all the sites displayed:
Of course is possible to disable the control, and the result is the following:
The control supports also the possibility to order the retrieved sites by id or title, in the sample I’ve ordered the options by title:
It’s possible to perform a validation on an option when it’s selected, for example you can choose not to allow an empty selection. In this case, when a user select an empty option, the result would be the following:
I won’t cover all the remaining controls here because it’s better to see the code since the UI will be the same for those. Let’s have a look at the code to better understand every control instance.
Show me the code
Prerequisites
To use the PnP property controls first you need to install the package:
npm install @pnp/spfx-property-controls --save --save-exact
After the installation of the package you can proceed with the following explanations for the PropertyFieldListPicker control.
To use the control you have to import it in the web part file with the following statement:
import {
ISPList,
PropertyFieldListPicker,
PropertyFieldListPickerOrderBy,
} from "@pnp/spfx-property-controls";
The ISPList interface is used to define the onListsRetrieved function. The PropertyFieldListPickerOrderBy is used to enable the ordering of the resulting options.
I’ve defined some properties to display the values set in the property pane into the web part. Just as reference these are the web part properties:
export interface IPnPListPickerSampleWebPartProps {
minimal: string;
list: string;
lists: string[];
selectAllInList: string[];
orderByList: string;
hiddenList: string;
onErrorList: string;
excludedList: string;
filterList: string;
filterByContentTypeList: string;
onListRetrieved: string;
extendedList: any;
}
Inside the web part getPropertyPaneConfiguration function I defined the various control instances, let’s cover those!
Minimal configuration instance
This instance shows what is the minimal configuration required for the control to work. As you can see from the code there are some required properties, let’s have a look at the control instance and then at each single property:
PropertyFieldListPicker("minimal", {
label: strings.MinimalListPickerFieldLabel,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
key: "minimalPicker",
})
Now let’s see what are those required properties:
-
label: the text that will be displayed as title of the control. -
onPropertyChange: the web part’sonPropertyPaneFieldChangedmethod. -
properties: the web part properties. -
context: the web part context. -
key: a string that represent a unique identifier for the control instance.
List selected instance
These instance shows how it’s possible to define a selected list. This is achieved specifying the GUID of the list to be selected. To specify the value set the id in the selectedList property.
PropertyFieldSitePicker("site", {
label: strings.SelectSiteFieldLabel,
initialSites: this.properties.site,
context: this.context,
multiSelect: false,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
key: "sitePicker",
})
NB: The selectedList property can also be used to select multiple lists using an array.
Hidden instance
The control, by default, shows all the lists available on the site, also the hidden ones. If the default behavior is not what you’re looking for it’s possible to disable it. To block the hidden lists from showing in the available list options you can set the includeHidden property to false.
PropertyFieldListPicker("hiddenList", {
label: strings.HiddenListPickerFieldLabel,
selectedList: this.properties.hiddenList,
includeHidden: false,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
key: "hiddenListPicker",
})
Multi selection instance
It’s possible to allow the users to select multiple options. To enable this it’s enough to set the multiSelect property to true. The control will then display a list of options with a checkbox to select each single option.
PropertyFieldListPicker("lists", {
label: strings.ListsPickerFieldLabel,
selectedList: this.properties.lists,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
includeHidden: false,
multiSelect: true,
key: "listsPicker",
})
Allow select all with multiple selection enabled
When the multi selection is enabled it’s also possible to enable a “select all” button.
To display the “select all” is enough to set the showSelectAll property to true.
It’s also possible to set a different appearance for the “select all” button. By default it uses the label of the control to enable the selection. If the selectAllInList property is set to true a “select all” option will be added on top of the options list.
Using the selectAllInListLabel property is also possible to specify a custom text that will be displayed for the “select all” option.
PropertyFieldListPicker("selectAllInList", {
label: strings.SelectAllInListPickerFieldLabel,
selectedList: this.properties.selectAllInList,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
includeHidden: false,
multiSelect: true,
showSelectAll: true,
selectAllInList: true,
selectAllInListLabel: strings.SelectAllInListLabel,
key: "selectAllInList",
})
Disabled instance
In some situation you would need to disable the control. This is possible using the disabled property and setting it to true.
PropertyFieldListPicker("list", {
label: strings.DisabledListPickerFieldLabel,
selectedList: this.properties.list,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
disabled: true,
key: "disabledPicker",
})
Ordered control instance
Using the propery orderBy it’s possible to define, using the PropertyFieldListPickerOrderBy enumerator, the field with which to order the options.
Actually the supported values for the enumerator are:
- Id
- Title
PropertyFieldListPicker("orderByList", {
label: strings.OrderByListPickerFieldLabel,
selectedList: this.properties.orderByList,
orderBy: PropertyFieldListPickerOrderBy.Title,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
key: "orderByListPicker",
})
On error instance
The control offers the ability to perform some custom validation using the onGetErrorMessage property.
This property accepts a function where you can perform your validation and return a string that can be:
- A string containing the validation error that you want to show
- An empty string when there are no validation errors
The code for this instance is the following:
PropertyFieldListPicker("onErrorList", {
label: strings.OnErrorListPickerFieldLabel,
selectedList: this.properties.onErrorList,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
onGetErrorMessage: (value: string) => {
return value === "NO_LIST_SELECTED"
? strings.ListSelectionRequired: "";
},
key: "onErrorlistPicker",
})
As you can see if the value is equals to NO_LIST_SELECTED (which is the default value for the first empty option) the error to be shown is a custom string. If there are no validation errors it returns an empty string.
Excluded list instance
Aside of not showing the hidden lists it’s possible to define a custom set of lists that you don’t want to display. This can be achieved using the listsToExclude property. The property accepts an array of strings which contains the title of the lists that you want to exclude from the available options.
PropertyFieldListPicker("excludedList", {
label: strings.ExcludeListPickerFieldLabel,
selectedList: this.properties.excludedList,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
listsToExclude: ["appdata", "appfiles"],
key: "excludedListPicker",
})
In this piece of code the control won’t show the appdata and appfiles lists.
Filtered list instance
In some scenarios it might be that you want to filter the displayed lists based on some specific list property. In this case the filter property is your best friend. Using this property you can specify a custom query to filter the retrieved lists.
PropertyFieldListPicker("filterList", {
label: strings.FilterListPickerFieldLabel,
selectedList: this.properties.filterList,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
filter: "BaseTemplate eq 100",
key: "filterListPicker",
})
In this example the control filters the list by the BaseTemplate property. More precisely it will only show the lists that has, as a base template, the custom list template, which has the id of 100.
Filter by content type instance
When you need an additional filtering you can use the contentTypeId property. This property lets you filter the resulting list options by the list content type. The control will show only the lists that have a content type that starts with the specified string.
PropertyFieldListPicker("filterByContentTypeList", {
label: strings.FilterByContentTypeListPickerFieldLabel,
selectedList: this.properties.filterByContentTypeList,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
contentTypeId: "0x0101",
key: "filterByContentTypeListPicker",
})
In this sample only the lists that have a content type starting with 0x0101 (this means Document) will be shown.
On list retrieved instance
Another useful property of the control is the onListsRetrieved one. This property let’s you define a function to perform custom operations on the retrieved lists.
Just to demonstrate how it works, I’ve filtered only the lists that have a base template of 101, which is the Document Library one.
PropertyFieldListPicker("onListRetrieved", {
label: strings.OnListRetrievedListPickerFieldLabel,
selectedList: this.properties.onListRetrieved,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
onListsRetrieved: (lists: ISPList[]) => {
if (lists.length > 0) {
lists = lists.filter((list) => {
const baseTemplate = Number(list.BaseTemplate);
return baseTemplate === 101;
});
}
return lists;
},
key: "onListRetrievedListPicker",
})
Extended list instance
The last property that I want to cover is the includeListTitleAndUrl one. By default only the id of the list is loaded. This means that if you retrieve the selected value, by default, you will receive the list’s GUID. If you set the includeListTitleAndUrl property to true, as the name suggests, it will load a complex object containing the list’s title and url aside of the list’s id.
PropertyFieldListPicker("extendedList", {
label: strings.ExtendedListPickerFieldLabel,
selectedList: this.properties.extendedList,
onPropertyChange: this.onPropertyPaneFieldChanged,
properties: this.properties,
context: this.context,
includeListTitleAndUrl: true,
key: "extendedListPicker",
})
In the situation where you’ve enabled the use of a complex object, when retrieving the selected value you will have three different properties available:
idtitleurl
In the sample I’ve displayed, in the web part, the selected value using an ul tag. The variable extendedList is the selected value from the property pane and can be displayed as follows:
<ul>
<li>{extendedList.id}</li>
<li>{extendedList.title}</li>
<li>{extendedList.url}</li>
</ul>
Conclusions
This post is a little bit longer than I’ve expected it to be, but this control has many useful properties that I wanted to demonstrate. I think that all the different filters are awesome and pretty handy.
I didn’t cover all the available properties of the control in this post (yes, there are more), if you want to discover more you can visit the official documentation here.
Just a final hint: it’s also possible to load lists from another site!
Hope this helps!
Top comments (0)