SharePoint Dynamic JavaScript Loading

Two weeks ago we published a blog post written by kalmstrom.com Lead Developer Jayant Rimza, where he described several solutions to the JavaScript problem that occurs with SharePoint 2013 Minimal Download Strategy.

That post has been so popular that we decided to create a SharePoint development entry in the kalmstrom.com Tips section. We hope our developers will contribute with more tips in the future. There you can find the SharePoint MDS and JavaScript article now, and the post below is also published in the Tips section. Once again Jayant "holds the pen", this time to explain how to best load JavaScript files in SharePoint:

When you are coding SharePoint using JavaScript, you need to load JavaScript files, and SharePoint offers multiple ways to do that. The major methods are to register the file on a page, to always load the file by using the SharePoint CustomAction in Module and to load the file on demand by using the Script on Demand function. This is valid for all SharePoint versions.

When a JavaScript file is registered on a page it is only available for that page, and this normally works good.
The problem comes when you are modifying the SharePoint ribbon using CustomAction and your CustomAction requires multiple JavaScript files. Then there are two loading methods available, to always load the files or to load them on demand.

 It is not good to always load JavaScript files. It will slow down the entire SharePoint performance, because it loads the JavaScript files on every SharePoint page and most often you do not need them all. You might only need them when a page is loaded or custom actions are executed.

JavaScript Always Loaded
Here I will first explain how to always load JavaScript or JavaScript code blocks. By using this method you can write check or condition when you want to load other JavaScript files.

From SharePoint CustomAction in Module you can register a JavaScript file and the file will be loaded in the entire SharePoint site. Only use this method when you really need to use the file all over SharePoint.

You can use this code to check condition and load other JavaScript files. You can use below code to register JavaScript in entire site:

<CustomAction

    Location="ScriptLink"

    ScriptSrc="/mymodule/js/myjavascriptfile.js" Sequence="100">

ScriptSrc is the Path of the JavaScript file.

You can directly write a block of JavaScript using CustomAction of the SharePoint module.

<CustomAction

    Location="ScriptLink"

    ScriptBlock="alert('script block loaded');"

    Sequence="100"> 
 

 Script on Demand 
SharePoint provides a function to load JavaScript on Demand (“SP.SOD”). By Script on Demand you can load a JavaScript file by a SharePoint function, and it will provide a callback to execute code when the JavaScript file is loaded. This is a good approach to load JavaScript files and improve overall SharePoint performance. 

There are three steps to load a script on demand: first add “notify script” at the end of the dynamic load JavaScript file, then register the file and finally execute the load function.

1. SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs
   At the end of the file that is going to load dynamically you need to add this line of code:
   
    SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs("myjavascriptfile.js");
   
   The Argument in the function "myjavascriptfile.js" is the key for that file. It does not have to be a file name, I only used the filename to avoid confusion. This key should be the same when you register the dynamic loading file and execute the load function.
   
   The key should be different for different JavaScript files, because internally SharePoint stores them in associate array with this key and value as path.
2.  SP.SOD.registerSod
   This function is used to register the file for the Script on Demand that you want to load later.
   
   
   var thisUrl = "";
   
   
           if (_spPageContextInfo.webServerRelativeUrl !== "/") {
               thisUrl = _spPageContextInfo.webServerRelativeUrl;
           }
   SP.SOD.registerSod("myjavascriptfile.js", thisUrl + "/mymodule/js/ myjavascriptfile.js");
   
   SP.SOD.registerSod accepts two arguments, the key for the file and its SharePoint path. This function registers the file in the SharePoint memory so that it will be loaded dynamically.
3.  SP.SOD.executeFunc
   Use this function when you want to load the JavaScript file and execute the method.
   
   

   SP.SOD.executeFunc(“myjavascriptfile.js”, functionName, fn);

   function fn(){

           alert(“my JavaScript file loaded dynamically”);       

   }

   
   This SharePoint function accepts three arguments: the key, the name of the function and the callback function that is executed after the file has been loaded. The key should be the same that you used in the method “SP.SOD.registerSOD”. (You can pass null into the second argument, because it is not mandatory. I always pass null in SP.SOD.executeFunc(“myjavascriptfile.js”, null, fn)
   
   Note that the callback function “fn” should not be in the file that is going to load. Instead it should be in the file or block that is loading the JavaScript file. After this callback function you can use all functions and variables of the dynamic loaded JavaScript File.

Summary

• Do not always load all your files in SharePoint using CustomAction. It will slow down SharePoint performance.
• You can load files when they are needed by SOD at event, button click, page load etc.
• First add a line at the end of the JavaScript file that will notify SharePoint that the file is loaded completely: SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs("key");
• Register the file using the function SP.SOD.registerSod("key", “jspath");
• Use executeFunc to load the file when needed. This method executes a callback function once the loading is done by SharePoint: SP.SOD.executeFunc(“key”, null, callback);
• In all three steps to load the files dynamically, the key must be the same as for the JavaScript file.

Jayant Rimza
Lead Developer
kalmstrom.com Business Solutions