Sharepoint 2013/ Online - JavaScript Injection Using Embed JavaScript Pattern

Based on the latest recommendations from Microsoft, the user interface of SharePoint 2013 & SharePoint Online should be customized, using Client Side Frameworks and not using Traditional Master Page Customization, based on the branding solutions.

Moving on the same recommendations, we will discuss JavaScript Injection or embed JavaScript pattern, which is one of the newly recommended techniques from Microsoft that enables the developers to write the Applications to push the client scripts into the page from outside SharePoint environment.

This sounds similar to the implementation of the Delegate controls in an On Premise SharePoint installation but in this case, we push the scripts from outside of SharePoint environment.

Using client side frameworks such as jQuery along with this technique, we can perform DOM manipulation (adding, removing, modifying HTML elements) as and when required in whatever ways.

We must make use of custom actions with SharePoint app model in order to implement embed JavaScript pattern by utilizing the location identifier ScriptLink, which can be accessed through UserCustomActions collection of SPWeb Object.

In this in this article, we will see how to implement embed JavaScript pattern in real time business applications, as shown below.

Let's start with a SharePoint app project by selecting an app for SharePoint project template.

Specify the Site URL

Choose Provider-Hosted for hosting the model in order to develop high trust apps.

Choose ASP.NET Web forms Application to create Web Application project for the provider hosted app.

Provide certificate details for the high trust apps.

Now, once the project is ready, we can start with the coding part of the solution, as shown below.

Step 1

In the default.aspx, add HTML code to provide UI for the solution.

In the App.js file, add the code given below.

Step 2

Refer jQuery file from CDN.

Step 3

Calling InjectJavaScript function.

Step 4

Inside InjectJavaScript function, check if MDS is enabled, and if it is Register Custom JavaScript code, using RegisterModuleInit function.

The first parameter to the RegisterModuleInit function is the path to JavaScript file relative to the _layouts folder. Since this solution deploys the JavaScript file into a folder under the _layouts virtual directory, you have provided that relative path. The second parameter is the entry point function, which is LoadJSInsideHostWeb.

This approach will ensure that this JavaScript will work both with MDS enabled & disabled sites.

Steps 5

Inside LoadJSInsideHostWeb function, we are calling LoadJQuery function to include jQuery file from CDN and once loaded successfully, it is calling ModifyHostWeb, which will do the actual job of injecting JavaScript code to the host Web.

Step 6

Inside ModifyHostWeb function

We are manipulating the site title of the host Web by using jQuery element identifier.
We are replacing the Site Icon of the Host Web by using jQuery element identifier.

Step 7

Inside LoadJQuery function, we are loading jQuery file from CDN

Step 8

Here, we are hooking up the button click event for InjectJs & RemoveJS HTML buttons.

Inside each event handler, we are calling InjectJavaScript & RemoveJavaScript functions by passing the client context to the host Web & Web object referring the host Web and setting the notification message on SharePoint app page (default.aspx) to show the status of the operation.

Steps 9

Inside InjectJavaScript function, we are making use of custom actions framework for SharePoint to inject JavaScript based customization inside the host Web in the steps given below.
12.1

Prepare the path of the script file that we are going to inject into the host Web and embedding it by creating the dynamic script block with SRC attribute set to the script file path.

Now, we are retrieving the UserCustomActions collection in context of the Host Web and add the new User Custom Action with the location as the script link and script block as dynamic script block created earlier.

Step 10

Inside RemoveJavaScript function, we are removing the user custom action from the UserCustomActionscollection in context of the Host Web based on the description & location property of the user custom action.

With this, we are done with the code.

Now, let's run the app and see it in action by pressing F5 in Visual Studio.

Once the app is launched, we can see the UI with a Result panel & two HTML buttons.

Inject JavaScript to Host Web
This button will inject JavaScript to the host the Web, using user custom action.
Remove JavaScript to Host Web
This button will remove JavaScript from the host Web by removing the user custom action.

If we look at the host Web before embedding the script into it, it will look as shown below. Notice, we have default site icon and the title, which was provided at the time of the site creation.

Now, on the app page, click on Inject JavaScript to Host Web button to push custom JavaScript into the host Web.

On clicking the button, we can see the success message in the Result panel confirming that JavaScript has been applied to the host Web.

If we revisit the host Web, we can see the site icon and the title has been changed, as per the code, we had added to the custom JavaScript file that we have injected into the host Web.

Since this change takes place at the master page level, we can see the effect of the change all across the site on every screen, as shown below.

Now in order to unplug JavaScript based customizations out of the host Web, we can click on Remove JavaScript to Host Web.

Once the Remove operation has been completed successfully, we can see the result panel, which confirms the success of the operation.

We can go back to host Web to ensure that the site icon and original title are restored back as usual.

Thus, we can clearly see the “Embed JavaScript Pattern” is very effective, as it enables you to handle on customizing host Web elements from outside SharePoint itself.

Point of Caution

It is the responsibility of the app developer to handle the smooth removal of the injected code, as soon as the app gets uninstalled. There are a couple of issues that I would like to point out around this fact, as shown below.

If the code is injected, using SharePoint hosted app, then it is not possible to remove the injected code automatically by any means. In this case, it is required to provide a user interface or any other means to execute the code for the removal of the injected JavaScript followed by the user training for the administrators to run the code first before uninstalling the app.

If the code is injected, using a provider hosted app, it is possible to get it removed automatically by handling an app uninstalling event, using remote event receivers. You can refer to my earlier blogs on remote event receivers to get a better understanding on the usage

That’s all for this demo.

I hope you found it helpful.