How to Implement Custom UI Changes in SharePoint Online Using SPFx Extension

Introduction

 

Before we get started, if you are new to SharePoint Framework, please take a look at below articles about building SharePoint Framework webparts and extensions using the below links:

• Creating SharePoint Framework Webparts
• Creating SharePoint Framework Extensions

SharePoint Framework are extensions of the type Application.Customizer, which helps to perform JavaScript actions. By default, we have placeholders to render Headers and Footers in the SharePoint modern page.

 

SPFx Breadcrumb Workaround

 

Here we are going to use the same concept to implement BreadCrumb as well. But we don’t have default placeholder to get this done. We are going to see a workaround to implement breadcrumb in the SharePoint modern page under the Site Title. In short, we are going to do the below steps:

• Identify the Site Title element using any of the JavaScript element selectors like ID, ClassName, TagName, AttributeName.
• Create a new element for BreadCrumb in the DOM.
• Append the new element next to the Site Title element.

Risks Involved

 

Since we are using our own workaround, there are risks involved in this approach. If Microsoft updated the Site Title section and removed/renamed any of the selectors that we use to identify the Site Title element, our approach will fail here.

 

But Site Title is an area that is stable for years, so it won’t be updated often. When you choose to do these types of customizations, you need to be clever and find the element to handle worst-case scenarios.

 

Implementation

 

Step 1

 

Create a new application as SPFx Extension Application.Customizer.

 

Step 2

 

Create a React Component for BreadCrumb using the OfficeUI Fabric component.

 

In Office UI Fabric, we have a component for breadcrumb. Let’s use that by importing the reference, like below:

import { Breadcrumb, IBreadcrumbItem } from 'office-ui-fabric-react/lib/Breadcrumb';

Check out the available properties of the component in the official documentation for Office UI Fabric breadcrumb and generate your breadcrumb.

 

Below is how the render method of this component will look:

public render() {
    return (
      <Breadcrumb items={this.props.items} />);
  }

Step 3

 

Go to the typescript file generated in the name of your extension. Below is the location of the typescript file:

src/extensions/{YourExtensionName}/{YourExtensionName} ApplicationCustomizer.ts

Step 4

 

Look for the onInit() method in the typescript file and replace the code in that with the following:

this.context.placeholderProvider.changedEvent.add(thisPage, this.processBreadCrumb.bind(this));
this.context.application.navigatedEvent.add(thisPage, this.processBreadCrumb.bind(this));

Here, we are adding our event handler method to the PlaceholderChangedEvent and ApplicationNavigated Event

 

PlaceholderChangedEvent – It will be triggered when the list of currently available placeholders is changed.

ApplicationNavigatedEvent – It will be triggered when the application's top-level page context navigates to a new page. In SharePoint online, redirection between pages sometimes happen with a soft refresh. In that case, we need to make sure that our breadcrumb is processed and displayed, so we need to register our handler method to this event also.

 

Step 5

 

Let’s implement our event handler method like below. Please take a look at the comments for each section in the code which helps you to understand the implementation better:

private processBreadCrumb() {
        //Find if any existing element with same name and remvoe it, this will help if events triggered multiple times
        let breadCrumbDiv = document.getElementById("siteBreadCrumb");
        if (!this.isObjNull(breadCrumbDiv)) {
            breadCrumbDiv.remove();
            breadCrumbDiv = null;
        }
        //creating a div to inject breadcrumb
        breadCrumbDiv = document.createElement("div");
        breadCrumbDiv.setAttribute("id", "siteBreadCrumb");

        //Identify the SiteTitle using the query selector
        let titleElement = document.querySelector('[data-automationid="SiteHeaderTitle"]');

        if (!this.isObjNull(titleElement)){
            //This helps to place our custom breadcrumb div element right below the Site Title
            let siteTitleParentParent = titleElement.parentElement.parentElement;
            siteTitleParentParent.insertBefore(breadCrumbDiv, titleElement.parentElement.nextSibling);

            //Create a ReactElement using the BreadCrumbComponent which we create and render it inside the custom breadcrumbdiv
            const element: React.ReactElement<IBreadCrumdProps> = React.createElement(BreadCrumbComponent,
                {
                    items: this.items
                });

            ReactDOM.render(element, breadCrumbDiv);
        }
    }

Conclusion

 

I hope this article helps you to get an understanding of how to customize the SharePoint Online site to implement Breadcrumbs. If you have any questions/issues about this article, please let me know in the comments.