Adding Custom Properties To SPFx Web Part Properties Pane - Part One

Introduction

 

In this article, you will learn the basics of creating a custom pane property definition. This helps with adding pane properties to the web part property panes using web part files.

 

In my previous articles, you can learn about adding existing properties to SPFx web part properties pane.

• Customizing SharePoint Framework Web Part Properties - Part One
• Customizing SharePoint Framework Web Part Properties - Part Two
• Customizing SharePoint Framework Web Part Properties - Part Three
• Customizing SharePoint Framework Web Part Properties - Part Four
• Customizing SharePoint Framework Web Part Properties - Part Five 

So far, you have seen only adding/using property templates available on open source. Now, you will learn developing and inserting custom pane properties to the properties pane.

 

The custom field property declared in the web part file (under getPropertyPaneConfiguration method) contains target property name and other custom properties.

PropertyFieldMessageBar('targetpropname', customprops)

In the below sections, you will see in detail about the pane property definition for the custom pane property declared above.

 

Interfaces Available

 

Microsoft provides two interfaces for creating custom property.

• IPropertyPaneCustomFieldProps
  
  This interface provides key properties and methods that help in developing the pane property. Properties and methods available are the following.
  
  
• context
• key
• onDispose() and 
• onRender()
  
  
• IPropertyPaneField
  
  This interface provides a few properties that can be inherited for defining the custom pane property (fields).
  
  
• properties
• shouldFocus
• targetProperty - Property name
• type - Type of property (custom, text, dropdown, etc.)

Developing the Property Definition File

 

The property definition is written as a function which inherits data from class and interface components. Here, a custom interface is introduced to input the user defined custom properties. The properties like label, on property change method and other internal properties are defined here.

 

The following code snippet shows the sample custom interface defined to input from the user. Likewise, any other properties can be defined.

interface IPropertyFieldMessageBarProps {
  label: string;
  onPropertyChange(propertyPath: string, oldValue: any, newValue: any): void;
  properties: any;
  key?: string;
}

Note - The values are declared and passed when the property is declared in the getPropertyPaneConfiguration method of the web part file.

 

Then another interface is defined which inherits properties from IPropertyPaneCustomFieldProps. This is an internal interface that contains all the properties and methods, which will not be exposed to users or the web part file. This can, in turn, hold the properties collection (created using previous interface IPropertyFieldMessageBarProps) as one property.

 

The following snapshot shows the sample internal interface, which is not exposed to users or web part file.

interface IPropertyFieldMessageBarPropsInternal extends IPropertyPaneCustomFieldProps {
  label: string;
  targetProperty: string;
  onRender(elem: HTMLElement): void; // Method to render data (in this case reactjs is used)
  onDispose(elem: HTMLElement): void; // Method to delete the object
  onPropertyChange(propertyPath: string, oldValue: any, newValue: any): void;
  properties: any; // set of properties (holds values of property collection defined using IPropertyFieldMessageBarProps)
  key: string;
}

Then, the class is defined, which contains the variables, constructor, and render method. The class inherits properties from other interfaces, like IPropertyPaneField and IPropertyFieldMessageBarPropsInternal (custom). 

• The constructor is used to initialize the variables.
• The render method will display the data. The custom function or the react components are used for rendering the data.

The following code snippet shows the property definition class file.

export class PropertyFieldMessageBarBuilder implements IPropertyPaneField<IPropertyFieldMessageBarPropsInternal> {

  //Properties defined by IPropertyPaneField
  public properties: IPropertyFieldMessageBarPropsInternal;
  public targetProperty: string;
  public type: PropertyPaneFieldType = PropertyPaneFieldType.Custom;

  //Custom properties
  private label: string;
  private onPropertyChange: (propertyPath: string, oldValue: any, newValue: any) => void;
  private customProperties: any;
  private key: string;

  // Initializes the varialbes or methods
  public constructor(usertargetProperty: string, userproperties: IPropertyFieldMessageBarPropsInternal) {
    this.render = this.render.bind(this);
    this.targetProperty = userproperties.targetProperty;
    this.properties = userproperties;
    this.label = userproperties.label;
    this.properties.onDispose = this.dispose;
    this.properties.onRender = this.render;
    this.onPropertyChange = userproperties.onPropertyChange;
    this.customProperties = userproperties.properties;
    this.key = userproperties.key;
  }

  // Renders the data
  private render(elem: HTMLElement): void {

  }

}

Then, the custom function is defined, which can then be declared in the web part files. From the web part file, the required properties are passed as input. 

export function PropertyPaneMessageBar(targetProperty: string, properties: IPropertyFieldMessageBarProps): IPropertyPaneField<IPropertyFieldMessageBarPropsInternal> {

    // Builds the property based on the custom data
    var newProperties: IPropertyFieldMessageBarPropsInternal = {
      label: properties.label,
      targetProperty: targetProperty,
      onPropertyChange: properties.onPropertyChange,
      properties: properties.properties,
      onDispose: null,
      onRender: null,
      key: properties.key
    };

    // Initialize and render the properties
    return new PropertyFieldMessageBarBuilder(targetProperty, newProperties);
}

Reference

 

More such custom pane properties are developed and available directly for use under github site. These properties templates are available, which can be readily declared in the web part files (getPropertyPaneConfiguration method). 

 

Summary

 

Thus you have learned the basic understanding of developing custom pane property which can be added to property panes. The interfaces, class, and functions are used for defining the data. The rendering can be done on the same file or using react components.

 

What Next

 

In the next article, you will see the full sample which defines the pane property, renders the property using react components, and invokes the pane property from the web part file.