SPFx Series: Extensions

The main difference between an SPFx web part and an extension is that a web part is a component that allows the content of a page to be viewed or edited, while an extension customizes or extends the user interface of SharePoint or Microsoft Teams.

An SPFx webpart is a custom-built component that can be added to a SharePoint page to provide additional functionality. For example, it can be used to display a chart, a calendar, or a list of items. Web parts are usually used to modify or expand the content of the page.

An SPFx extension, on the other hand, is a custom-built piece of code that runs in the context of SharePoint or Microsoft Teams and can be used to customize or extend the SharePoint or Teams user interface. For example, it can be used to add a custom command to the command bars, add a custom header or footer, or customize the colours of the user interface. Extensions are used to customize the user interface of SharePoint or Teams and extend functionality.

There are three types of SPFx extensions:

• Application Customizers: These are small pieces of code that run when a page is loaded in SharePoint or Teams. They offer the possibility to add a header or footer, for example, or to customize the colours of the user interface.
• Field Customizers: These are custom fields that can be added to SharePoint lists and libraries. They provide additional functionality for viewing and editing list items and documents.
• Command Sets: These are commands that can be added to the command bars in SharePoint lists and libraries. They offer the ability to add customized actions, such as adding a button to convert a document to another format.

Deployment Type

Implementing an extension involves an XML, a clientSideInstance.xml or a elements.xml. You can find this XML in the SharePoint/assets folder of your solution in Visual Studio Code. These xml files are included in the feature of your solution (see features in the package-solution.json file)

The difference between the 2 xml files lies in the fact that the clientSideInstance.xml is used to implement your extension Tenant wide. This is done when your app is deployed in the app catalogue. If a clientSideInstance.xml file is found during the deployment of your app, your extension will be implemented in the hidden Tenant Wide Extensions list. This means that every time your extension is loaded somewhere within SharePoint, the configuration for this extension is read from this Tenant Wide Extensions list.

If we look at the different properties in such an xml of a clientSideInstance, we can distinguish the following:

• Title: This is the title of your custom action
• Location: This determines the location where the client-side component is displayed. Here it specifies that the component is a ListViewCommandSet that is shown in the Command Bar of a SharePoint list.
• ListTemplateId: This value specifies which list template the client-side component should be applied to. List template ID 100 refers to a Custom List.
• Location: This indicates where the action will be shown. In this case, it indicates that the action is a ClientSideExtension and that it is a ListViewCommandSet that should appear in the CommandBar of a SharePoint list.
• properties: This parameter contains a JSON object with its own properties that are passed to the SPFx component when it is executed. In this case, two properties, sampleTextOne and sampleTextTwo, are passed with the values “One item is selected in the list.” and “This command is always visible, respectively”.
• ComponentId: This is the unique ID of the Client-Side component associated with this custom action. This GUID refers to the SPFx component (for example, a web part or extension) that is loaded when the action is performed.

<?xml version="1.0" encoding="utf-8"?>
    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
        <ClientSideComponentInstance
            Title="ListItemDetailsDialog"
            Location="ClientSideExtension.ListViewCommandSet.CommandBar"
            ListTemplateId="100"
            Properties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}"
            ComponentId="acddd824-662e-47a5-a80e-6586b25c810a" 
        />
    </Elements>

When a elements.xml is found, this xml will be used in the implementation at site collection level. With this implementation, your extension will only be configured at site collection level. If we look at the xml of the elements.xml file, we can distinguish the following properties:

• Title: This is the title of your custom action
• RegistrationId: This specifies which list(s) or content types are affected by this customization. The value “100” corresponds to the ID of the list definition. List Definition 100 refers to a standard Custom List.
• RegistrationType: This parameter specifies the type of SharePoint object on which the action is logged. The value “List” means that the action for a list applies.
• Location: This indicates where the action will be shown. In this case, it indicates that the action is a ClientSideExtension and that it is a ListViewCommandSet that should appear in the CommandBar of a SharePoint list.
• ClientSideComponentId: This is the unique ID of the Client-Side component associated with this custom action. This GUID refers to the SPFx component (for example, a web part or extension) that is loaded when the action is performed.
• ClientSideComponentProperties: This parameter contains a JSON object with its own properties that are passed to the SPFx component when it is executed. In this case, two properties, sampleTextOne and sampleTextTwo, are passed with the values “One item is selected in the list.” and “This command is always visible, respectively”.

<?xml version="1.0" encoding="utf-8"?>
    <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
        <CustomAction
            Title="ListItemDetailsDialog"
            RegistrationId="100"
            RegistrationType="List"
            Location="ClientSideExtension.ListViewCommandSet.CommandBar"
            ClientSideComponentId="acddd824-662e-47a5-a80e-6586b25c810a"
            ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
        />
    </Elements>

These 2 files are greased in your app, but when is it decided which xml to use? This happens when your app is implemented in the app catalogue. When we are going to implement this, we see the following screen appear:

If you check “Make this solution available to all sites in the organization”, the clientSideInstance.xml file will be used and the extension will be implemented in the Tenant Wide Extensions list. If you don’t find this option, the elements.xml file will be used when you specifically add an app to a site collection.