Based on the latest recommendations from Microsoft, User Interface SharePoint 2013 and SharePoint Online should be customized using Client Side Frameworks and not use Traditional Master Page Customization based on 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 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-premises SharePoint Installation but in this case, we push the scripts from outside of the 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 needed in whichever ways.

We must make use of Custom Actions with SharePoint App Model in order to implement Embed JavaScript Pattern by utilizing location identifier ScriptLink that can be accessed through UserCustomActions collection of SPWeb Object.

In this article, we will see how to implement Embed JavaScript Pattern in real time business applications as below.

Lets’ start with a SharePoint App Project by selecting App for SharePoint Project Template

1

Specify the Site URL

Choose Provider-Hosted as hosting model in order to develop High Trust Apps

2

Choose ASP.Net Web Forms Application to create Web Application Project for the Provider Hosted App

3

Provide Certificate details for the High Trust Apps

4

Now once the project is ready we can start with the coding part of Solution as follows:

Steps 1 – In the default.aspx add HTML code to provide UI for the solution

5

In the App.js file add the following code

Steps 2 – Refer the jQuery File from the CDN

Steps 3 – Calling InjectJavaScript Function

6

Steps 4 – Inside InjectJavaScript Function, check if MDS is enabled and if it is Register Custom JavaScript code using the RegisterModuleInit function.

The first parameter to the RegisterModuleInit function is the path to the 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 and disabled sites.

7

Steps 5 – Inside LoadJSInsideHostWeb function, we are calling a  LoadJQuery function to include jQuery file from the CDN and once loaded successfully it is calling ModifyHostWeb which will do the actual job of Injecting JavaScript Code to the Host Web

8

Steps 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

9

Steps 7 – Inside LoadJQuery function we are loading jQuery File from the CDN

10

Steps 8 – Here we are hooking up the button click event for InjectJs and RemoveJS HTML buttons

Inside each event handler, we are calling InjectJavaScript and RemoveJavaScript functions by passing Client Context to the Host Web and Web Object referring the Host Web and setting the notification message on the SharePoint App Page (default.aspx) to show the status of the operation

11

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 following steps:

12.1

Preparing 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.

Then we are retrieving the UserCustomActions collection in the context of the Host Web and adding the new User Custom Action with Location as Script Link and Script Block as dynamic script block created earlier

 

13

Steps 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.

14

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 launched we can see the UI as a Result Panel and two HTML Buttons

  • Inject JavaScript to Host Web – This button will Inject JavaScript to the Host Web using User Custom Action
  • Remove JavaScript to Host Web – This button will Remove JavaScript from the Host Web by removing User Custom Action

15

If we look the Host Web before embedding the script to it, it would look like as follows. Notice we have default Site Icon and Title which was provided at the time of site creation

16

Now on App Page click 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 the JavaScript has been applied to the Host Web

17

If we revisit the Host Web we can see the Site Icon and Title has been changed as per the code we had added to the custom JavaScript File that we have injected into Host Web

And 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:

18

19

20

 

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

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

21

And we can go back to Host Web to ensure that the Site Icon and Original Title are restored back as usual.

22

So we can clearly see the “Embed JavaScript Pattern” is very effective as it gives you a handle on customizing Host Web Elements from outside the SharePoint itself.

Point of Caution

It is the responsibility of the App Developer to handler the smooth removal of the injected code as soon as the app gets uninstalled. There are a couple of issues to point out around this fact as follows:

If the code is injected using SharePoint Hosted App, then it is not possible to get it removed the injected code automatically by any mean. In this case, it is required to provide a User Interface or any other mean to execute the code for removal of injected JavaSscript followed by User Training for the Administrators to run the code first before uninstalling the app.

If the code is injected using Provider Hosted App, then it is possible to get it removed automatically by handling App Uninstalling Event using Remote Event Receivers. You can refer to the following blogs on Remote Event Receivers to get a better understanding on usage:

That’s all for this demo.

Hope you find it helpful.