Change Site And System Master Pages In SharePoint 2016, Using REST API

Master Pages provide a consistent look and feel throughout the site. They provide consistent elements, like global navigation, search box, branding, and other controls, that are expected to appear across the site collection. When Master Page displays a persistent layout, content pages display page specific content. Master pages and content pages are combined at run-time and are displayed as a single page.



In order to apply custom master pages, we have to enable the publishing feature in the site collection as well as the site. Unless these features are activated, we cannot use custom master pages or change the existing master pages.

Publishing feature at site collection level



Publishing feature at Site Level



Once the features are activated, we get the option to change the master page out of the box. Even with SharePoint 2016, the master pages are those that were introduced with SharePoint 2013. Microsoft has not created a new master page, as is the tradition, but has built upon the exiting SharePoint 2013 master page. Out of the box, we can change the master page by going to the Site Settings -> Look and feel -> Master Page.



As you can see, the drop down for site master pages shows ‘seattle’ and ‘oslo’ as the available choices. Similarly, for system master pages, we have the same option.



In this article, we will see how to change the default ‘seattle.master’ to ‘oslo.master’ programmatically, using REST API.

SharePoint provides two types of master pages

• Site Master Page
• System Master Page

Site Master Pages are used to provide a consistent look and feel throughout the SharePoint publishing pages. While the System Master Pages provide unique customization to the Forms, like ‘Newform.aspx’ and administrative pages, like site settings.

Change Master Page

In order to change the master page, we will be making use of the REST Endpoint URL:

"/_api/web";

We will be issuing a MERGE AJAX request, using the REST URL. In addition to that,  we will be creating a key value pair of the information which will be used to update the master page. The master page updating property is shown below. It will be sent as JSON in the ‘data’ attribute of the AJAX REST call.

var metadata =
    {
    __metadata: {
        'type': 'SP.Web'
    },
    'CustomMasterUrl': '/sites/HOL/_catalogs/masterpage/oslo.master',
    MasterUrl ': ' / sites / HOL / _catalogs / masterpage / oslo.master '
};

Within the _metadata attribute, we have to specify the value for ‘type’ which will specify what object is being updated during the MERGE AJAX call. In our case, it is a web. Hence, we will be specifying ‘SP.Web’. The custom site master page will be set using the ‘CustomMasterUrl’ property while the system master page will be updated using the ‘MasterUrl’ property. The header section will look like:

headers:
(
    "accept": "application/json;odata=verbose",
    "X-RequestDigest": $("#__REQUESTDIGEST").val(),
    "content-Type": "application/json;odata=verbose"
},

Here, accept attribute specifies the data type for the return value and content-type defines the data type for the data sent to the server. In POST request, we have to send the X-RequestDigest value along with the request for form validation without which we will get a validation error. To fulfill this, we will be assigning the $("#__REQUESTDIGEST").val() which sets the value of the form digest control present within the page to X-RequestDigest key.

Output

On running the script, we will get the message for successful update of site and system master pages.



Full Code

The full code for changing the site and system master page, using REST API, is as shown below,

<script language="javascript" type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.8.1/jquery.min.js"></script>
<script language="javascript" type="text/javascript">
    $(document).ready(function() {
        var newMasterPageUrl = "/_api/web";
        var metadata = {
            __metadata: {
                'type': 'SP.Web'
            },
            'CustomMasterUrl': /sites/HOL / _catalogs / masterpage / oslo.master ',
            'MasterUrl': '/sites/HOL/_catalogs/masterpage/oslo.master'
        };
        changeMasterPage(newMasterPageUrl, metadata)
    });

    function changeMasterPage(newMasterPageUrl, metadata) {
        $.ajax({
            url: _spPageContextInfo.webAbsoluteUrl + newMasterPageUrl,
            type: "MERGE",
            headers: {
                "accept": "application/json;odata=verbose",
                "X-RequestDigest": $("#__REQUESTDIGEST").val(),
                "content-Type": "application/json;odata=verbose"
            },
            data: JSON.stringify(metadata),
            success: function(data) {
                console.log(data);
                console.log("Site and System Master Pages Changed successfully.");
            },
            error: function(error) {
                alert(JSON.stringify(error));
            }
        });
    }
</script>

Let’s see how we can implement it in SharePoint. Save the script as a text file and upload it to the Site Assets library.

SharePoint Implementation 

• Go to the edit settings of the SharePoint page and click on Web part from the Insert tab.
  
  
  
  
• Add Content Editor Web part.
  
  
  
  
• Click on Edit Web part from Content Edit Web part. Assign the URL of the script text file and click on Apply.
  
  
  
  
• Click on Apply and we can see the successful master page update message in the console.

Going to the Site Settings -> Look and Feel -> Master page location, we can see that the site master page and system master page has been changed from ‘seattle’ to ‘ oslo’ as part of running the script.



Summary: Thus, we have seen how to update the site and system master pages in SharePoint 2016, using REST API.