Discover how to use the PropertyFieldSitePicker from the PnP property controls

Introduction

Proceeding our dive into the PnP reusable property pane controls I want to cover the PropertyFieldSitePicker 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 PropertyFieldSitePicker works.

Visual Appearance

Before switching to the code section I want to cover the resulting user interface. Since the PropertyFieldSitePicker 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 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.

When selecting the textbox, the user can enter a value. A search will be executed against all the sites present in the tenant. The result of the search is displayed as following:

Since this is the minimal configuration the selection is defaulted to a single site. Clicking on an option will select it and shows the selected option under the textbox control:

Moving to a different instance, this one shows how the UI look when allowing a multiple selection:

Of course is possible to disable the control, and the visual result is the following:

At last there’s also the ability to specify a predefined query that will be added to the specified user query using an AND statement:

Ok, enough for the resulting UI, let’s cover what’s the code behind it.

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 PropertyFieldSearch control.

---

To use the control you have to import it in the web part file with the following statement:

import { PropertyFieldSitePicker } from "@pnp/spfx-property-controls";
import { IPropertyFieldSite } from "@pnp/spfx-property-controls";

The IPropertyFieldSite interface is used to define the web part’s properties.

To enable the control to set the properties of the web part I defined the following interface:

export interface IPnPSitePickerSampleWebPartProps {
  minimalSitePicker: IPropertyFieldSite[];
  site: IPropertyFieldSite[];
  sites: IPropertyFieldSite[];
  disabledSite: IPropertyFieldSite[];
  errorSite: IPropertyFieldSite[];
  deferredSite: IPropertyFieldSite[];
  additionalQuerySite: IPropertyFieldSite[];
}

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:

PropertyFieldSitePicker("minimalSitePicker", {
  label: strings.MinimalSelectSiteFieldLabel,
  initialSites: this.properties.minimalSitePicker,
  context: this.context,
  onPropertyChange: this.onPropertyPaneFieldChanged,
  properties: this.properties,
  key: "minimalSitePicker",
})

Now let’s see what are those required properties:

• label: the text that will be displayed as title of the control.
• initialSites: an array of IPropertyFieldSite that represents the select or selected site/s.
• context: the web part context.
• onPropertyChange: the web part onPropertyPaneFieldChanged method.
• properties: the web part properties.
• key: a string that represent a unique identifier for the control instance.

Single or multiple instances

These two instances show how it’s possible to switch from a single to multiple site selection using the multiSelect property.

Setting the multiSelect to false will enable the single site selection:

PropertyFieldSitePicker("site", {
  label: strings.SelectSiteFieldLabel,
  initialSites: this.properties.site,
  context: this.context,
  multiSelect: false,
  onPropertyChange: this.onPropertyPaneFieldChanged,
  properties: this.properties,
  key: "sitePicker",
})

Setting the multiSelect property to true will enable the multiple site selection:

PropertyFieldSitePicker("sites", {
  label: strings.SelectSitesFieldLabel,
  initialSites: this.properties.sites,
  context: this.context,
  multiSelect: true,
  onPropertyChange: this.onPropertyPaneFieldChanged,
  properties: this.properties,
  key: "sitesPicker",
})

Disabled control instance

In some situation you would need to disable the control. This is possible using the disabled property and setting it to true.

PropertyFieldSitePicker("disabledSite", {
  label: strings.DisabledSelectSiteFieldLabel,
  initialSites: [],
  context: this.context,
  onPropertyChange: this.onPropertyPaneFieldChanged,
  properties: this.properties,
  key: "disabledSitesPicker",
  disabled: true,
})

Deferred control instance

Using the propery deferredValidationTime it’s possible to define, in milliseconds, the time to defer the query execution. In this sample the value is 2 seconds, if the deferredValidationTime property is not specified the default value will be 200 milliseconds.

PropertyFieldSitePicker("deferredSite", {
  label: strings.DeferredSelectSiteFieldLabel,
  initialSites: this.properties.deferredSite,
  context: this.context,
  onPropertyChange: this.onPropertyPaneFieldChanged,
  properties: this.properties,
  key: "deferredSitesPicker",
  deferredValidationTime: 2000,
})

Query instance

Other than the user inserted query, it’s possible to specify a default query. That default query will be applied with an AND to the user specified one. In this example the code defined query is to include all the sites that contains, in the title property, the value “site”.

PropertyFieldSitePicker("additionalQuerySite", {
  label: strings.QuerySelectSiteFieldLabel,
  initialSites: this.properties.additionalQuerySite,
  context: this.context,
  onPropertyChange: this.onPropertyPaneFieldChanged,
  properties: this.properties,
  key: "querySitesPicker",
  additionalQuery: `Title:*site*`,
})

Conclusions

The PropertyFieldSitePicker is a very useful control when it comes to enable a target site selection in a web part property pane. This can be handy if you need to select a site on which to perform specific operation or from which to load data.

I didn’t cover all the available properties of the control, if you want to discover more you can visit the official documentation here.

Hope this helps!