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 which runs inside the context of the SharePoint page. These are similar to delegate controls and script links in 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 header message and footer message
• Display a welcome greeting to currently logged in user on first time login
• Custom Navigation to your site on header area
• Loading some scripts on page load. This can be analytics script that tracks no of visitors to 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 tool chain 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 following command

yo @microsoft/sharepoint

Step 4

It will ask some questions

• What is your solution name? for this I left 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 default which is (HelloWorld).

If you observed from previous SPFx version, no. of questions asked are reduced and now down to 4 only. Rest of the options like isolated permission, and application customizer available to all the sites in 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 yeomen generator, examine the source code using 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 security warning, select ‘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 serve.json file which is present inside ‘config’ folder. Please note that starting the version SPFx 1.13 the local work bench is deprecated. Any SPFx solutions needs to be tested against the SharePoint work bench. For application customizer solutions it needs to be always tested under SharePoint workbench. Update the pageUrl 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.

• serveConfiguration
• helloWorld

and each entry points have properties such as pageUrl and Custom Actions that needs to be loaded. For instance, if you want to test the solution against ‘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 solution 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 helloWorld entry point then you can only change pageUrl property and run the gulp serve --config=helloWorld

Serve

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

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

If there are no errors in 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 value ‘test message with default configuration!!!’.

Select ‘load debug scripts'.

Step 9

If you are running the SPFx version lesser 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 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 solution can be found in serve.json under 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 for getting the solution package file that needs to be deployed in App Catalog. The package file can be deployed in either Tenant Level App Catalog or 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 generates the scripts which provides 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 local server.

gulp bundle –ship

Package

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

gulp package-solution --ship

Deploying the solution

If you observed that now the tenant level app catalog has 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 SharePoint admin center by going to 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 feature and go to ‘Apps’ and click ‘Open’. This opens up 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 ‘sharepoint/solution’ folder where you have configured in 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 app has been enabled. You may click on close.

Activating the app

Now that the app customizer is activated, 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 site, and you should see the alert message. In this case, I have navigated back to 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. May be during the testing phase you have stopped 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 app customizer is and where this extension can be used and how to develop, test and package the application customizer using SPFx and then finally deployed to 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/