Sharepoint 2013 : Overview of The Client-Side Object Model and Rest APIs - JAVASCRIPT (part 1) - Setup

Alongside the Managed .NET Client-Side Object Model (Managed CSOM) is the JavaScript Client Object Model (JS CSOM).

The primary purpose of the JS CSOM is to allow JavaScript code running on pages within the context of SharePoint to talk back to SharePoint without requiring a full-page postback. It is not designed or intended for developers to use outside of the context of pages served from SharePoint.

Similar to the Managed CSOM, the JS CSOM also is built to batch requests to ensure performance. However, one of the fundamental differences is that the JS CSOM is designed with asynchronous calls and callbacks in mind. This ensures that transactions that take some time to complete don’t potentially block the calling thread, possibly impacting the UI of your application.

To access the JS CSOM the calling page must reference the following two files:

• SP.Runtime.js
• SP.js

Each of these is located in the /_layouts/15/ directory under each SharePoint site; for example, http://myserver/sitename/_layouts/15/SP.js.

You can also find these files on any SharePoint 2013 server in the following location:

%ProgramFiles%\Common Files\Microsoft Shared\
web server extensions\15\TEMPLATE\LAYOUTS

Setup

By default, pages that run within the context of SharePoint typically have the appropriate JavaScript references already defined in the master page. This means you shouldn’t need to reference them in each page of your application. However, understanding what it means to be within the context of SharePoint is important. It means that the page is served from the same domain as SharePoint, rather than from another location such as in Azure. In cloud-hosted SharePoint apps, this is the default. Pages are loaded and served from SharePoint, which is possible because they can contain only out-of-the-box SharePoint controls, HTML, and JavaScript, so no custom code runs within the SharePoint process itself.

One way to tell whether your page uses the SharePoint master page is to look for the following Page declaration at the top of the page:

<%@ Page Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, 
Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, 
PublicKeyToken=71e9bce111e9429c" 
MasterPageFile="~masterurl/default.master" language="C#" %>

If you have a page that doesn’t inherit the SharePoint master page then you must include references to the appropriate JavaScript CSOM files. An example of this would be in an App Part when you don’t want the full SharePoint master page wrapping your App Part’s user interface.

To add the references manually you must include the following script references:

<script type="text/javascript" 
src="https://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.runtime.debug.js"></script>
<script type="text/javascript" src="/_layouts/15/sp.debug.js"></script>

If your page is served from outside of the SharePoint site, such is the case with Autohosted apps (served from Azure) or Provider-hosted apps, then you must dynamically generate the script includes in JS to ensure they include the fully qualified domain name (FQDN) in the URL. This is because you need to have the JS files served from the SharePoint Server itself to ensure the browser doesn’t block the JS CSOM calls because of cross-site scripting protections.

To do this you can use the SPHostUrl query string parameter passed to your SharePoint app as follows:

<script type="text/javascript">
    var hosturl;
    $(document).ready(function () {
        hosturl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
        var scriptbase = hostweburl + "/_layouts/15/";
 
        $.getScript(scriptbase + "SP.Runtime.js",
            function () {
                $.getScript(scriptbase + "SP.js", scriptLoaded);
            }
        );
    });
 
    function scriptLoaded () {
    // your code goes here
    }
 
    function getQueryStringParameter(paramToRetrieve) {
        var params = document.URL.split("?")[1].split("&");
        var strParams = "";
        for (var i = 0; i < params.length; i = i + 1) {
            var singleParam = params[i].split("=");
            if (singleParam[0] == paramToRetrieve)
                return singleParam[1];
        }
    }
</script>

In the preceding code the JQuery $(document).ready method is called when the page has loaded and it’s safe for the script to continue. The code then uses the getScript method to dynamically load the JavaScript files. It also uses the SPHostUrl query string parameter passed to dynamically ensure it is retrieving the files from the originating SharePoint site. After that call completes, the scriptLoaded method is called. The ScriptLoaded method is the location you can safely place your JS CSOM code.