Create custom property in SharePoint Framework - SPFx web part pane

Create custom property in SharePoint Framework – SPFx web part pane

By Global SharePoint in SharePoint, SharePoint Online, SPFx SharePoint Framework on
3 comments

 11,577 total views,  90 views today

In this article, we will learn about how we can add a custom additional property to the SharePoint Framework -SPFx web part in the web part configuration pane. This is my third article in the SPFx framework learning series – you may refer to my previous articles: First, let’s look at the below screenshot – when we developed the default first hello world web part, we can see only the “Description” property in the web part property configuration pane. However, now we could see some additional configurable properties like Multi-line-Text Field, Checkbox, Dropdown, Toggle control in the web part configuration pane.  Here, in this article, I will explain how these additional controls have been added over here.
Add custom property in SPFx web part - configuration pane
Add a custom property in SPFx web part – configuration pane
I am not describing how to create a new project here – I am taking forward my previous demo project(Hello World), and starting from here.  Step 1: Import the necessary property pane from the ‘@microsoft/sp-property-pane’  Let’s open the HelloWorldWebPart.ts file from the project file structure. At the beginning of this file, we must add the below code otherwise this will not work. 
import {
IPropertyPaneConfiguration,
PropertyPaneTextField,
PropertyPaneCheckbox,
PropertyPaneDropdown,
PropertyPaneToggle
} from '@microsoft/sp-property-pane';
 
@microsoft/sp-property-pane for the custom property in the HelloWorldWebPart.ts file.
 
Import microsoft-sp-property-pane for the custom property
Import microsoft-sp-property-pane for the custom property
Note:
  • In the above import, we can import as many allowed property pane we want – here I am importing Text Field, Checkbox, Dropdown, Toggle.
Step 2:  Add the above fields in the export section. In the below IHelloWorldWebPartProps interface by default when we create default hello world web part, we will just have “description: string” property now we have added the below additional property test: string; test1: boolean; test2: string; test3: boolean; 
export interface IHelloWorldWebPartProps

 {

  description: string;

  test: string;

  test1: boolean;

  test2: string;

  test3: boolean;

}
Step 3:  Handle the page render section Go to the default class HelloWorldWebPart extends BaseClientSideWebPart <IHelloWorldWebPartProps> section. By default, we can see the below line for the rendering of the description field. <p class=”${ styles.description }”>${escape(this.properties.description)}</p>
 
Then below to that, we can add the custom additional fields like added below(see the high lighted lines).
export default class HelloWorldWebPart extends BaseClientSideWebPart <IHelloWorldWebPartProps>

 {

  public render(): void {

    this.domElement.innerHTML = `

      <div class="${ styles.helloWorld }">

    <div class="${ styles.container }">

      <div class="${ styles.row }">

        <div class="${ styles.column }">

          <span class="${ styles.title }">Welcome to SharePoint!</span>

  <p class="${ styles.subTitle }">Customize SharePoint experiences using Web Parts.</p>

    <p class="${ styles.description }">${escape(this.properties.description)}</p>

    <p class="${ styles.description }">${escape(this.properties.test)}</p>    

    <p class="${ styles.description }">${escape(this.properties.test2)}</p>    

      <a href="https://aka.ms/spfx" class="${ styles.button }">

        <span class="${ styles.label }">Learn more</span>

          </a>

          </div>

          </div>

          </div>

          </div>`;

  }
 
Step 4: Grouping the custom columns
 
Now, in the same file – let’s go to the getPropertyPaneConfiguration() method which has been inherited from IPropertyPaneConfiguration. We can see all the below additional properties have been added in the “Groups” section just below the default property description.
  • PropertyPaneTextField
  • PropertyPaneCheckbox
  • PropertyPaneDropdown
  • PropertyPaneToggle
protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration 
{

  return 

  {

    pages: [

      {

        header:

         {

          description: strings.PropertyPaneDescription

        },

        groups: [

          {

            groupName: strings.BasicGroupName,

            groupFields: [

            PropertyPaneTextField('description', {

              label: 'Description'

            }),

            PropertyPaneTextField('test', {

              label: 'Multi-line Text Field',

              multiline: true

            }),

            PropertyPaneCheckbox('test1', {

              text: 'Checkbox'

            }),

            PropertyPaneDropdown('test2', {

              label: 'Dropdown',

              options: [

                { key: '1', text: 'One' },

                { key: '2', text: 'Two' },

                { key: '3', text: 'Three' },

                { key: '4', text: 'Four' }

              ]}),

              PropertyPaneToggle('test3', {

                label: 'Toggle',

                onText: 'On',

                offText: 'Off'

            })            

          ]

          }

        ]

      }

    ]

  };

}
All the below property functions have been defined in “index-internal.d.ts” file.
  • PropertyPaneTextField
  • PropertyPaneCheckbox
  • PropertyPaneDropdown
  • PropertyPaneToggle
So if we go the definition of all the above each property function we will land into the below : PropertyPaneTextField 
export declare function PropertyPaneTextField(targetProperty: string, properties: IPropertyPaneTextFieldProps): IPropertyPaneField<IPropertyPaneTextFieldProps>;
PropertyPaneCheckbox 
export declare function PropertyPaneCheckbox(targetProperty: string, properties: IPropertyPaneCheckboxProps): IPropertyPaneField<IPropertyPaneCheckboxProps>;
PropertyPaneDropdown 
export declare function PropertyPaneDropdown(targetProperty: string, properties: IPropertyPaneDropdownProps): IPropertyPaneField<IPropertyPaneDropdownProps>;
PropertyPaneToggle 
export declare function PropertyPaneToggle(targetProperty: string, properties: IPropertyPaneToggleProps): IPropertyPaneField<IPropertyPaneToggleProps>;
index-internal.d.ts – This file is automatically created which looks like below:
 
index-internal.d.ts - SPFx Property Pane
index-internal.d.ts – SPFx Property Pane
 
HelloWorldWebPart.manifest.json
 
Now let’s go to the HelloWorldWebPart.manifest.json file. Down to this file, we can see 
preconfiguredEntries JSON – here we can set all default value to property pane controls.
 
 
"preconfiguredEntries": [{

    "groupId": "5c03119e-3074-46fd-976b-c60198311f70", // Other

    "group": { "default": "Other" },

    "title": { "default": "HelloWorld" },

    "description": { "default": "HelloWorld description" },

    "officeFabricIconFontName": "Page",

    "properties": {

      "description": "HelloWorld",

      "test": "Multi-line text field",

      "test1": true,

      "test2": "2",

      "test3": true

    }

  }]
As we have set the default value for the above – highlighted properties, at run time we can see the below default value in the web part property pane:
 
Description text box has HelloWorld
 
Multi-lineText Field has Multi-line text field
 
Checkbox by default is selected (true).
 
The dropdown has default two
 
Toggle by default is on (true).
 
 
 
Add custom property in SPFx web part - configuration pane
Add a custom property in SPFx web part – configuration pane
Note:
 
In the above example, for the dropdown in the JSON, it is set as 2 but while rendering the web part it displays as “Two“, you may ask why?
 
This is because of the key-value parameter mapping in the PropertyPaneDropdown function which is located at the HelloWorldWebPart.ts file where “2” is mapped with the “Two” text.
 
 PropertyPaneDropdown('test2', {

              label: 'Dropdown',

              options: [

                { key: '1', text: 'One' },

                { key: '2', text: 'Two' },

                { key: '3', text: 'Three' },

                { key: '4', text: 'Four' }

              ]}),
 
HelloWorldWebPart.manifest.json file in the actual project(solution):
 
HelloWorldWebPart.manifest.json file SPFx Property Pane Configuration
HelloWorldWebPart.manifest.json file SPFx Property Pane Configuration
 
What are the field types are supported in the web part property pane?
 
The following field types are supported in the web part property pane configuration:
 
  1. Button
  2. Checkbox
  3. Choice group
  4. Dropdown
  5. Horizontal rule
  6. Label
  7. Link
  8. Slider
  9. Textbox
  10. Multi-line Textbox
  11. Toggle
  12. Custom
 
Download
 
The above project can be downloaded from here.
 
 
Summary
 
Thus, in this article – we have learned the below with respect to adding the custom property in the SPFx web part property pane:
 
  • How to create create a custom property pane field?
  • What is the SharePoint framework custom property pane?
  • What are the field types are supported in the web part property pane?
 

See Also

Free download SharePoint Online & Office 365 Administration eBook(238 Pages)

Get the PDF eBook from here:


[purchase_link id="0" style="button" color="blue" text="Free Download SharePoint Online & Office 365 Administration"]

 

 
FREE DOWNLOAD

Send download link to:

Subscribe to get exclusive content and recommendations every month. You can unsubscribe anytime.

 
 
 
 
 
 
 
 
Tags: , , , , , , , ,