Customizing SharePoint Framework Web Part Properties - Part One

Introduction

 

In this article you will learn about custom web part properties. The custom web part properties can be added to the SharePoint framework (SPFx) web part.

 

In my previous articles, you have seen about SPFx introduction, prerequisites, steps for setting up the environment, and developing and testing the web parts using the local environments.

• Developing Web Parts Using SharePoint Framework - Part One
• Developing Web Parts Using SharePoint Framework - Part Two 
• Developing Web Parts Using SharePoint Framework - Part Three  

Web Part Properties 

 

The web part properties pane can contains multiple pages. Each page in turn can contain multiple properties. The properties can be grouped using group names.

 

The basic hello world web part project contains a page along with the description property. The following snippet shows the basic structure of the web part properties. This method will be defined in the class of web part file.

protected get propertyPaneSettings(): IPropertyPaneSettings {
  return {
    pages: [
      {
        header: {
          description: strings.PropertyPaneDescription
        },
        groups: [
          {
            groupName: strings.BasicGroupName,
            groupFields: [
              PropertyPaneTextField('description', {
                label: strings.DescriptionFieldLabel
              })
            ]
          },
          {
            groupName: "Check Box",
            groupFields: [
              PropertyPaneCheckbox('checkboxProperty1',{
                isChecked:false,
                text: this.checkboxProperty1
              })
            ]
          }
        ]
      }
    ]
  };
}

Note

Above snippet includes text field and check box properties. Each group has one property declared.

 

The basic structure is defined using the method called propertyPaneSettings, which inherits IPropertyPaneSettings function. It returns the collections of pages. Here only one page is defined. Each page has a header and groups. The group is a collection of properties. So multiple properties can be combined under one group. Each group has a group name and group fields which contain the properties.

 

The list of properties (property fields) that can be added to a web part are,

• Label
• Text box
• Multi line text box
• Check box
• Drop down
• Link
• Slider
• Toggle
• Custom

Note

You will learn about all the above properties in my future articles.

 

Importing Properties

 

The properties are available as functions under the platform modules. They need to be imported into the web part file before use. The same can be imported using '@microsoft/sp-client-preview'.

 

For example to use the text field property, PropertyPaneTextField property function should be imported from the library into the web part file. Similarly, to use the check box properties, PropertyPaneCheckbox property function should be imported from the library. For other properties, respective functions should be imported into the web part file.

 

The following snippet shows the components imported, which includes the above mentioned web part properties.

import {
  BaseClientSideWebPart,
  IPropertyPaneSettings,
  IWebPartContext,
  PropertyPaneTextField,
  PropertyPaneCheckbox
} from '@microsoft/sp-client-preview';

Declare Properties

 

The properties needs to define the variables, variable types, group names, description, etc. The same can be defined directly or by using the standard definition files.

 

The standard files available are mystrings.d.ts, en-us.js, IListItemsFormWebPartProps.ts, etc. These files will be available already as part of SPFx web part project.

• Static variables are stored in mystrings.d.ts file and the corresponding values are available in en-us.js file.
• The web part properties are defined in the IListItemsFormWebPartProps.ts file using interface. 

mystrings.d.ts File

declare interface IListItemsFormStrings {
  PropertyPaneDescription: string;
  BasicGroupName: string;
  DescriptionFieldLabel: string;
}

declare module 'listItemsFormStrings' {
  const strings: IListItemsFormStrings;
  export = strings;
}

en-us.js file

define([], function() {
  return {
    "PropertyPaneDescription": "Description",
    "BasicGroupName": "Group Name",
    "DescriptionFieldLabel": "Description Field"
  }
});

IListItemsFormWebPartProps.ts File

export interface IListItemsFormWebPartProps {
  description: string;
  checkboxProperty1: string;
}

Note

In the above basic structure properties sample, group name of text box property is referred from the definition file whereas the group name of check box is defined on the spot.

 

Later the above components are imported to the web part file (ListItemsFormWebPart.ts) for implementation. The following code snippet shows the same.

import * as strings from 'listItemsFormStrings';
import { IListItemsFormWebPartProps } from './IListItemsFormWebPartProps';

Note

The web part class file sample is available in my previous article. 

 

Summary

 

In the next articles you will learn more about adding the different type of available custom properties to the SPFx web parts.