SharePoint Framework Extensions - Getting Started With Application Customizer

Introduction

This is a type of extension using SPFx development, which lets a custom javascript load to every page during the page load. These are client-side components that run inside the context of the SharePoint page. These are similar to delegate controls and script links in the full trust development model. Consider a scenario, where you want to have a banner that has some message. In the initial SharePoint versions, this was primarily achieved using full trust code (which has access to SharePoint system pages and application pages). In modern SharePoint online sites, MSFT allows customization to specific areas

• Top of the page
• Bottom of the page

As you have seen there are very limited options to customize the pages using App Customizer using SharePoint online.

But wait, what can you build using application customizer?

• You can add a header message and a footer message
• Display a welcome greeting to currently logged-in users on first-time login
• Custom Navigation to your site on the header area
• Loading some scripts on page load. This can be an analytics script that tracks the visitors to the site, displaying a disclaimer on page load that forces users to agree to some terms and conditions before accessing the content.

And many more,

In this article, we will simply use the default app customizer has to provide. Let’s see this in action now.

Steps

Step 1. Check the version of SPFx and the toolchain version that is installed on your machine. For this open the command prompt and run the following command.

npm ls -g --depth=0

As seen in the screen capture, for this demo I am running SPFx version 1.14 and node version 14.15.0

Step 2. Have the folder set up where your source code and package are generated. For this demo, I have created under C:\My\SPFx\AppCustomizerDemo

Step 3. Run the Yo SharePoint generator by running the following command.

yo @microsoft/sharepoint

Step 4. It will ask some questions.

• What is your solution name? For this, I left the default.
• What type of client-side component to create? ‘Extension’.
• What type of client-side extension to create? ‘Application Customizer’.
• What is your Application Customizer Name? for this I left the default which is (HelloWorld).

If you observed from the previous SPFx version, no. of questions asked is reduced and now down to 4 only. The rest of the options like isolated permission, and application customizer available to all the sites in the tenant can be configured in application package files (config.json) which will be discussed in upcoming articles.

Step 5. After the project scaffolding is finished by the yeomen generator, examine the source code using the Visual Studio code editor. To open in Visual Studio code just enter code. (observe the space between code and period)

You might be prompted for a security warning, select the ‘Yes I trust the authors’ option, as there are some scripts that are generated from Open-source communities.

Step 6. The main method is present in the src folder (src-extensions-SolutionNameApplicationCustomizer.ts)

Below is the default source code. At first, the main method onInit() gets called.

Step 7. Now go to the serve.json file which is present inside the ‘config’ folder. Please note that starting the version SPFx 1.13 the local workbench is deprecated. Any SPFx solutions need to be tested against the SharePoint workbench. For application customizer solutions it needs to be always tested under SharePoint workbench. Update the page URL in both serveConfiguration and helloWorld entry points. In this case, I am testing against the communication site.

In the serve.json file observe that there are two sections.

• server configuration
• HelloWorld

and each entry points have properties such as page URL and Custom Actions that need to be loaded. For instance, if you want to test the solution against the ‘helloWorld’ entry point use the below command

gulp serve --config = <nameOfEntryPoint>

There could be some instances, where you want to have some test data to be loaded or you want to test solutions with specific URLs, during that time you can create an entry point for testing and update the properties accordingly.

If you want to test against only the helloWorld entry point then you can only change the pageUrl property and run the gulp serve --config=helloWorld.

Serve

The gulp serve command starts the local node server hosting at endpoint http://localhost:4321 and http://localhost:5432. It creates the temporary files in the 'temp and 'dist' folders which are needed for SharePoint workbench to preview the solution during the testing.

Now you will get a pop-up asking to allow debug scripts. Select ‘Load debugs scripts'.

If there are no errors in the solution you should be getting an alert message.

Note the ‘test message for Vinay Comm Site’ is declared inside the ‘helloWorld’ entry point in serve.json.

Step 8. If you just ran gulp serve then the values under the serveConfigurations gets executed. Let’s check it by updating the default properties in serve.json. In this case, I have updated the testMessage property with the value ‘test message with default configuration!!!’.

Select ‘load debugs scripts'.

Step 9. If you are running the SPFx version less than 1.1.3 and you are testing your customization against the modern page, then in order to test the solution you need to construct the URL manually. For serving gulp you need to provide with parameter –nobrowser.

gulp serve --nobrowser

below is the template of the gulp serve URL that needs to be built manually. You may hardly run into this scenario as most of the solutions could have been updated to the latest SPFx versions.

https://domainname.sharepoint.com/sites/SiteName/sitepages/news.aspx
    ?loadSPFX=true
    &debugManifestsFile=https://localhost:4321/temp/manifests.js
    &customActions={
        "GUIDOFAPPCUSTOMIZER": {
            "location": "ClientSideExtension.ApplicationCustomizer",
            "properties": {
                "testMessage": "Hello as property!"
            }
        }
    }

The GUID of the solution can be found in serve.json under the customActions property.

In this case, the value of the URL would be,

https: //cts229051.sharepoint.com/teams/VinayCommSite
    ? loadSPFX = true & debugManifestsFile = https : //localhost:4321/temp/manifests.js&customActions={
    " 535464c4-5dea-4607-a471-9c341f0c309e": {
        "location": "ClientSideExtension.ApplicationCustomizer",
        "properties": {
            "testMessage": "test message with serve parameter nobrowser!!!"
        }
    }
}

Now paste the URL that you have manually built

load debug scripts

Note the alert message with the message that you have defined while building up the URL manually.

Packaging the solution

Now that the solution is tested, you can run the following commands in sequence to get the solution package file that needs to be deployed in the App Catalog. The package file can be deployed in either the Tenant Level App Catalog or the Site Collection App Catalog. For this demo, I will be deploying at Tenant level App Catalog.

Build command precompiles the code and checks for errors and if there are no errors it generates the required files and folders for bundling and packaging the solution.

gulp build

Bundle

Bundle tasks generate the scripts that provide run time for your solution. Note that --ship will tell the node engine to host the scripts from M365 CDN. If there is no --ship parameter then all the required files needed to run the solution will be hosted from the local server.

gulp bundle –ship

Package

Package task generates the app package (. sppkg) file inside the SharePoint /Solution folder which needs to be deployed to the app catalog.

gulp package-solution --ship

Deploying the solution

If you observed that now the tenant-level app catalog has a modern look and feel. Please note that below steps require either a SharePoint admin or Global Admin privileges to your tenant.

Step 1. Login to the SharePoint admin center by going to the tenant admin URL. The format of the admin URL is https://<COMPANYDOMAIN>-admin.sharepoint.com. In this case, it is

https://cts229051-admin.sharepoint.com

Step 2. In the left navigation click on more features and go to ‘Apps’ and click ‘Open’. This opens up the tenant app catalog.

This opens up the home page where you can manage the apps for all your site collections at the Tenant level.

Step 3. Locate the package file (.sppkg file), this is available in the ‘SharePoint/solution’ folder where you have configured in the above steps. Either you can drag and drop or click on upload and then navigate to the directory and upload the file. In this case, I did drag and drop.

Step 4. Once you have uploaded the file, you will have 2 options.

• only enable app: this means the app is available to all the site collections but not activated. Only the site collection admins will be able to activate this app.
• Enable this app and it to all sites: choosing this option will make this app activated and there is no action needed to be taken by site collection admins.

Also, observe the section ‘This app gets data from: SharePoint’. What does that mean? This means all the runtime for your project and the static assets such as scripts, icons and images for your application is being hosted from Microsoft 365 CDN (Content Delivery Network) and you don’t have to do any additional configuration. More about CDNs can be found in references section. I will discuss more about CDN in my upcoming articles.

In this case, I have chosen default which is ‘Only enable this app’.

Step 5. Now you will get confirmation that the app has been enabled. You may click on Close.

Activating the app

Now that the app customizer is activated, the next step is to activate the application.

Step 1. Navigate to the required site collection and click on add an app, and search for app-customizer-demo.

Step 2. Select the app, and click on Add

Step 3. On success, it will give you the message “Added Successfully” and the add button is greyed out for the app that you have just added.

Step 4. Navigate back to any page on the site, and you should see the alert message. In this case, I have navigated back to the home page and it displays the message.

Possible errors

Error loading debug manifests.

Fix: This could be due to the gulp serve is not running and the manifest.js is not available. Maybe during the testing phase, you have stopped the gulp server or the gulp server did not run locally. Check if the gulp serve is running correctly if not initiate gulp serve from the application path.

Conclusion

Thus, in this article, we have seen what an app customizer is where this extension can be used, and how to develop, test, and package the application customizer using SPFx and then finally deploy it to the tenant-level application catalog. You can refer to the attached source code for reference.

References

• https://docs.microsoft.com/en-us/sharepoint/dev/spfx/debug-modern-pages
• https://www.c-sharpcorner.com/article/understanding-gulp-tasks-in-sharepoint-framework-solutions/
• https://www.sharepointnutsandbolts.com/2017/06/SPFx-Application-Customizer-Global-JS-Page-Header.html
• https://www.voitanos.io/blog/spfx-5w1h-what-is-the-sharepoint-framework/
• https://docs.microsoft.com/en-us/sharepoint/dev/spfx/extensions/get-started/build-a-hello-world-extension
• https://docs.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-developer-tenant
• https://blog.mastykarz.nl/how-to-check-sharepoint-framework-version/