SPFx extensions: discover the field customizer

Introduction

SharePoint Framework offers different extension project types, for example the Application customizer (more here), those extensions allow customization of the standard SharePoint Online UI/UX. With this article I will cover the field customizer extension.

This extension allows customizing the appearance of a specific field of a SharePoint Online list.

To demonstrate the use of a simple field customizer I’ve created a sample solution that you can find here.

Visual appearance

First thing first, let’s see how the sample solution displays!

Following, the list without the field customizer, pay attention to the Done column which displays a percentage of completion:

And here with the field customizer in action:

As you can see, the numeric value is displayed as a a progress bar with a different color for different value ranges.

Note: This is just a simple sample to demonstrate how to use this SPFx extension. The possible customizations can be way more complex than this.

Now, let’s cover how to achieve this!

Show me the code

Creating the solution

To create the solution, there are a couple of different methods, I will not cover those in detail here because it’s not the topic of this article, but those are:

• using the VSCode extension SharePoint Framework Toolkit. This extension offers a very nice UI to allow the creation of the solution. You can find it here.
• using Yeoman generator. This is a CLI tool, if you prefer using command line tools. I wrote an introductory article about it a while ago, you can find it here.

Now, let’s see the code in detail.

Field customizer highlights

When the solution is created, the field customizer extension’s class extends the SPFx BaseFieldCustomizer. The class signature will be like the following:

export default class BasicFieldCustomizerFieldCustomizer
  extends BaseFieldCustomizer<IBasicFieldCustomizerFieldCustomizerProperties> {

Inside the class, the method used to define how the render of the field appears is the onRenderCell:

public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  // Retrieve the field value
  const percentage: unknown = event.fieldValue;

  const basicFieldCustomizer: React.ReactElement<IBasicFieldCustomizerProps> = React.createElement(BasicFieldCustomizer, 
{
  percentage
} as IBasicFieldCustomizerProps);

  ReactDOM.render(basicFieldCustomizer,
    event.domElement);
}

The method will render the React component that will actually define how the field value will be rendered.

I will not cover the whole implementation of the BasicFieldCustomizer here, let’s just say that it creates a div element with a specific color based on the field value. If you’re interested in knowing more about the component you can check the code here.

After updating the code as you need, the next thing to configure is the serve.json file. This file is used for testing purposes and allows to define where to execute the tests.

You can specify a custom configuration, if there is no need of a specific one you can configure the default one. For example, in the sample solution, I’m using the default configuration as following:

"serveConfigurations": {
  "default": {
    "pageUrl":
      "https://{tenantDomain}/SitePages/myPage.aspx",
    "fieldCustomizers": {
      "Done": {
        "id": "c6305766-23e2-4fac-9bd2-fe9b80eb82de",
    "properties": {}
      }
    }
  },

The important configurations here are:

• pageUrl: the URL of the page where you want to test your field customizer. The {tenantDomain} placeholder is automatically overridden if you have specified the environment variable (more on that here), otherwise you can just copy and paste the full URL for the target page in the SharePoint Online site.
• Inside the fieldCustomizers object, you need to create an object with the internal name of the field you’re customizing and this object, inside the id property, contains the id of the field customizer (which can be found in the field customizer manifest JSON file).

After configuring the serve.json file, executing the following command will open a browser window that points to the pageUrl specified in the configuration:

gulp serve

After the browser window opens, you will be asked to load or not the debug scripts:

Clicking on the “Load debug scripts” button, the needed files are loaded and you should already see your field customizer in action!

Hint: if the field customizer is not loading, try adding the following parameter to the query string:

&allowSpfxDevFallback=true

If the field customizer is still not loading, check that:

• The pageURL inside the serve.json file is pointing to the correct page.
• The column internal name used in the serve.json file is the same of the target SharePoint Online column and that the column is visible in the current view.
• The id property of the field customizer object used in the serve.json file is the same as the manifest JSON file of the field customizer.

Conclusions

The field customizer is another useful extension of the SharePoint Framework. It will enable developers to easily customize SharePoint Online and create useful and unique UI/UX.

If you’re interested in discovering plenty of examples regarding the field customizer, have a look here, filter by “field customizer”, and enjoy the community work!

Hope this helps!