Integrating Property Pane

The SharePoint Framework is currently in Preview, and is subject to change based on customer feedback. While we’re in preview, SharePoint Framework web parts are not supported for use in production environments.

Overview

The property pane allows end users to configure the web part with a bunch of properties. In Tutorial 1, you saw the property pane defined in the HelloWorldWebPart class. propertyPaneSettings property is where we defined the property pane properties.

Below is an example of a property pane in SharePoint:

Property pane has three key metadata:

• Pages
• Header
• Groups

Pages provides you the flexibility to separate complex interactions and put them into one or more pages. Pages then contain Header and Groups.

Header allows you to define the title of the property pane and Groups let you define the various sections for the property pane through which you want to group your field sets.

A property pane should contain a page, an optional header and atleast one group.

Property fields are then defined inside a group.

Using property pane

Here is a sample code to initialize and configure property pane in your web part. We create a method of type IPropertyPaneSettings and return a collection of property pane page(s).

protected get propertyPaneSettings(): IPropertyPaneSettings {
  return {
    pages: [
      {
        header: {
          description: strings.PropertyPaneDescription
        },
        groups: [
          {
            groupName: strings.BasicGroupName,
            groupFields: [
              PropertyPaneTextField('description', {
                label: strings.DescriptionFieldLabel
              })
            ]
          }
        ]
      }
    ]
  };
}

Property pane fields

The following field types are supported:

• Label
• Textbox
• Multi-line Textbox
• Checkbox
• Dropdown
• Link
• Slider
• Toggle
• Custom

The field types are available as modules in sp-client-platform and hence requires an import before you can use them in your code:

import {
  PropertyPaneTextField,
  PropertyPaneCheckbox,
  PropertyPaneLabel,
  PropertyPaneLink,
  PropertyPaneSlider,
  PropertyPaneToggle,
  PropertyPaneDropdown
} from '@microsoft/sp-client-preview';

Every field type constructor is defined as follows, taking PropertyPaneTextField as an example:

PropertyPaneTextField('targetProperty',{
  //field properties are defined here
})

targetProperty defines the associated object for that field type and is also defined in the props interface in your web part.

To assign types to these properties, we define an interface in our web part class that includes one or more target properties.

export interface IHelloWorldWebPartProps {
    targetProperty: string
}

This is then available in your web part using this.properties.targetProperty.

<p class="ms-font-l ms-fontColor-white">${this.properties.description}</p>

Once the properties are defined, you can then access them in your web part using the this.properties.<property-value>, as we do in the render method of the HelloWorldWebPart:

Handling field changes

Property Pane has two interaction modes:

• Reactive
• Non-reactive

In reactive mode, on every change, a change event is triggered. Reactive behavior automatically updates the web part with the new values.

While reactive mode suffices many scenarios, at times you will need non-reactive behavior. Non-reactive does not update the web part automatically unless the user confirms the changes.

Custom field example

Note - this is still fairly rudimentary

Add the following type to the @microsoft/sp-client-preview imports

PropertyPaneCustomField

Add the following field definiton in a groupFields array.

                PropertyPaneCustomField(undefined, {
                  onRender: this._onPanelCustomControlRender
                })

Add the following private method to render the custom control

private _onPanelCustomControlRender(customDomElement : HTMLDivElement): void {
    customDomElement.innerHTML = '<input id="password" type="password" name="password" class="ms-TextField-field">';
}

For now, it is up to you to know what fields your control is representing, and read/write the properties back to the webpart properties when they are changed.