Blog Sharepoint Framework Extensions – Field Customizer RSS Feed

Sharepoint Framework Extensions – Field Customizer

May 29, 2020

Overview

With SharePoint Framework (SPFx) development, SharePoint developers build and deploy modern SharePoint webparts for Office 365 tenants. SharePoint Framework development helps us to fulfill the custom requirements which can be limited by OOTB features in the SharePoint Online. With SPFx, we can create custom Webparts, Extensions and Library components.

With SPFx Extensions, the SharePoint end-user experience is extended in the modern document libraries and pages. It helps us to modify the site and build a beautiful design. Also, the notification areas, list data views and toolbars can be customized with the SPFx extensions. Three types of extensions are included in the SharePoint Framework.

  • Application Customizer
  • Field Customizer
  • List-view Command Set

In this blog, Our Sharepoint Developer are going to explore in depth about the Field Customizer.

Table of Content

  1. Field Customizer
  2. Create a Field Customizer Extension Project
  3. Debug the Extension
  4. Deploy the Extension
  5. Conclusion

Field Customizer

Field Customizers are useful to provide a view for a column. One can provide the custom look and feel for a column in a list. The customization is carried out in the page DOM elements. We all know that this same behavior can also be achieved by Column Formatting but apart from the custom look and feel, Field Customizer allows you to inject JavaScript and jQuery using which one can achieve JS events as well. This is what makes it different than Column Formatting.

Field Customizers can be used in two ways.

  1. It creates a new site column and applies the custom formatting to it.
  2. It can be attached to the existing list column and don’t add a custom field in the site.

We are going to create a Field Customizer with a new site column being created. Let’s look in detail how to create a Field Customizer Extension step by step.

Create a Field Customizer Extension Project

  • Create a project directory where project is required to be created. Run Windows PowerShell and navigate to the drive where to create the project directory. Run the following command to create the project directory.
    • md field-extension
      md-field-extension
  • Move to this project directory using the below command.
    • cd field-extension
      cd field-extension
  • For creating a new SPFx solution, execute the below yeoman command.
    • yo @microsoft/sharepoint
    • It will prompt for details regarding the project. Provide the information and move forward.
      • Solution Name – This will be the name of the solution of the field customizer extension.
      • Baseline Target – Select SharePoint Online only (latest)
      • Place for files – Select the current folder
      • Select No (N) to require tenant admin for installing extension on each site and press Enter. Elements.xml feature deployment file will not be generated through scaffolding if Yes (y) is chosen.
      • Type of client-side component – Select Extension.
      • Type of client-side extension – Select Field Customizer
      • Field Customizer name – This will be the name for a field customizer extension
      • Field Customizer description – Provide the appropriate description for the field customizer extension
      • Framework – Field customizers can be developed using either ‘No JavaScript framework’ or React. In this blog, No JavaScript framework is used to create SPFx extension.
        SPFx extension
  • Once the enter key is pressed, all the needed dependencies will be installed by yeoman. Along with field-customizer extension, the solution files will be scaffolded by the yeoman. This may take a while.
  • Once the yeoman finishes its process, it will prompt the successful scaffold message.
    scaffold message
  • Now check the project directory, the solution files are created. To open the folder in Visual Studio Code, run below command.
    • code .
      code
  • The entire solution will be opened in the visual studio code. The default solution structure is created. Elements.xml file contains the details of the column that is going to be used as custom field. All the custom code for the extension can be written in FieldCustomizerFieldCustomizer.ts file.
    FieldCustomizerFieldCustomizer-ts
  • Open the FieldCustomizerFieldCustomizer.manifest.json file which is located under src → extensions → fieldCustomizer.
  • This file contains details regarding the extension and its unique id.
    fieldCustomizer
  • The project setup has now been finished. Let’s have a look at the code and try running the extension.
  • The code resides in FieldCustomizerFieldCustomizer.ts file which is located at src → extensions → fieldCustomizer. Open the FieldCustomizerFieldCustomizer.ts file.
  • From the sp-listview-extensibility base package, BaseFieldCustomizer class is imported.
    BaseFieldCustomizer
  • The code file mainly contains 3 methods.
    • onInit()
    • onRenderCell()
    • onDisposeCell()
  • onInit(): This method is called first as soon as the extension is loaded. All the code that needs to be executed above the rest should be added here. When the solution is created, the default code will be present in this method to write the logs. As like SPFx Webpart’s onInit method, this method also returns a promise to handle asynchronous calls and the rest of the methods only be called once this promise is resolved. If there is no custom logic for that just return Promise<void>.
    Promise
  • onRenderCell(): This method is called every time when a field cell is rendered. This method provides a DOM element as event.domElement. All the custom html design can be added into this domElement and it will be displayed in the cell of that field. By default, the below code will be seen in this method.
    onRenderCell
  • onDisposeCell(): This method free up the resources that were allocated in DOM during rendering. Mostly used in extensions which are created in react framework to free up the react elements.

Debug the Extension

As it is known that one cannot debug the SPFx Extensions on the local workbench. To debug the extensions, it is required to specify the landing URL in serve.json file. Follow the below steps to debug the field customizer.

  • Open the serve.json file which resides under the config folder.
    serve-json
  • The serve.json file contains the default settings for the project. In this file, specify the debugging related settings, and provide the port to be used for debugging, default settings and specify other nodes of project settings.
  • In serveconfigurations, there is “default” node which is used to provide the List URL “AllItems.aspx” page where the created field customizer is required to debug.
    • pageUrl – In this field, provide the List URL.
      • e.g. https://domain-name/sites/DeveloperSite/Lists/Test/AllItems.aspx
    • InternalFieldName – In this field, provide the internal name of the column in which the field customizer is needed to add.
  • Create a custom list named “Test” in the site and it has one number column named “Progress”. Let’s insert some entries into it.
    Test
  • Now as per the above instruction, modify the serve.json file. The below image shows the updated serve.json file.
    updated serve-json file
  • Open the console and make sure that the same directory of the project is there. Now, run the below command.
    • gulp trust-dev-cert
  • The above command will install a developer certificate in the environment. If this command is already executed, then skip this step.
  • Run the below command which will compile the code. Once the compilation is done, it loads the required manifest files from the https://localhost:4321 and loads it into the browser with required query parameters.
    • gulp serve
  • If the code is compiled without any errors, then it will open the URL which is provided in serve.json file in the browser. In the browser page, it will prompt to allow debug scripts. Click on “Load debug scripts” to load the scripts on the page.
    Load debug scripts
  • If it shows the below error, then please stop the compilation by pressing ctrl + c in the console. Install the dev-certificate from the console and run the below command to compile the code again.
    • gulp serve –nobrowser
      Error loading debug manifests
  • Once the scripts are loaded successfully then it is noted that the values in the column has been changed. Here, the default code which was generated within the solution is executed.
    Test 1
  • Once the above output is generated for the list then replace the default solution code by the custom code as per the requirement. The below code shows the progress bar in three different colors based on the values in the column instead of simple values.
    progress bar
    FieldCustomizerFieldCustomizer.ts
    FieldCustomizer-module-scss
    FieldCustomizerFieldCustomizer.module.scss
  • The above code will generate the following output in the List.
    output
  • That’s it. Now a Field Customizer extension is created successfully. Let’s see the steps to deploy this extension on the site.

Deploy the Extension

  • To deploy the app on the site, prepare the package of the app and specify column details to be created for field customizer.
  • Open the elements.xml file located at sharepoint → assets → elements.xml in the solution folder. The below image shows the default content of element.xml. Specify the details for the column. The field customizer will create a new site column as per the details provided in this file and will apply the customization on it.
    customizer
  • The below image shows the updated element.xml file.
    element-xml
  • Before deploying the solution, it is important to verify that the element.xml file is being taken into account in package-solution.json file. Observe the below image, the element.xml is having entry in “elementManifests”. Also, the “includeClientSideAssets” is set to true that means the asset files will be included into the package file and we don’t need to specify the CDN path for the asset files.
    includeClientSideAssets
  • Let’s create a solution package. From the console, execute the below command to create a structure for packaging.
    • gulp bundle –ship
      gulp bundle -ship
  • Run the below command to create a package file (.sppkg).
    • gulp package-solution –ship
      gulp packagesolution ship
  • In the solution, the above process has created a .sppkg file which is located at sharepoint → solution. This folder also contains the assets and the debug scripts
    field extension sppkg
  • To deploy the app, open the app catalog of the tenant and navigate to Apps for SharePoint library.
  • Either upload or drag and drop the field-extension.sppkg file to Apps for SharePoint library inside App Catalog.
    Apps for Sharepoint
  • To deploy the solution, a dialog will be displayed to trust the client-side solution by clicking on Deploy button.
    Deploy
  • Navigate to the site collection where the extension is deployed.
  • From the top right corner of the site, click on the gear icon and select “Add an app”.
  • Now find the app by entering the name in the search box.
    Site contents
  • Select the field-extension app to install it. Refresh the page when the installation is done.
  • Once the application is installed successfully, it is displayed in the Site Contents.
  • Now navigate to the List where the custom column of field customizer extension is to create.
  • Click on the gear icon at the top right corner and navigate to List Settings.
    List settings
  • Click on “Add from existing site columns” under Columns section.
    Add from existing site columns
  • Find a group name SPFx Columns in “Select site columns from” dropdown. This group name is specified earlier in element.xml file.
    Select site columns from
  • Find and select the field name which has been specified in element.xml and put it on the right-hand side.
    Select Columns
  • The column is added in the List and will be visible in the default view. Let’s make some entries in the List.
  • Once entries are inserted in the List, the custom formatting is rendered without the debug query parameters.
    Project Status

Conclusion

The SFPx works like a charm in the SharePoint Online to carry out any customization. The various components of the SPFx helps in the customization in the modern site. This blog is a part of our SharePoint Framework series and it helps in customizing a column as per the requirement in the modern list/library. Stay tune with us for our next blog related to List View Command Set.

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

About Tatvasoft

TatvaSoft is a CMMi Level 3 and Microsoft Gold Certified Software Development Company offering custom software development services on diverse technology platforms, like Microsoft, SharePoint, Biztalk, Java, PHP, Open Source, BI, Big Data and Mobile.

Follow Us