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.

Master pages

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

feature

Publishing feature at Site Level

feature

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.

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.

seattle

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

  1. var metadata =
  2. {
  3. __metadata: {
  4. 'type': 'SP.Web'
  5. },
  6. 'CustomMasterUrl': '/sites/HOL/_catalogs/masterpage/oslo.master',
  7. MasterUrl ': ' / sites / HOL / _catalogs / masterpage / oslo.master '
  8. };
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:
  1. headers:
  2. (
  3. "accept": "application/json;odata=verbose",
  4. "X-RequestDigest": $("#__REQUESTDIGEST").val(),
  5. "content-Type": "application/json;odata=verbose"
  6. },
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.

Output

Full Code

The full code for changing the site and system master page, using REST API, is as shown below,
  1. <script language="javascript" type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.8.1/jquery.min.js"></script>
  2. <script language="javascript" type="text/javascript">
  3. $(document).ready(function() {
  4. var newMasterPageUrl = "/_api/web";
  5. var metadata = {
  6. __metadata: {
  7. 'type': 'SP.Web'
  8. },
  9. 'CustomMasterUrl': /sites/HOL / _catalogs / masterpage / oslo.master ',
  10. 'MasterUrl': '/sites/HOL/_catalogs/masterpage/oslo.master'
  11. };
  12. changeMasterPage(newMasterPageUrl, metadata)
  13. });
  15. function changeMasterPage(newMasterPageUrl, metadata) {
  16. $.ajax({
  17. url: _spPageContextInfo.webAbsoluteUrl + newMasterPageUrl,
  18. type: "MERGE",
  19. headers: {
  20. "accept": "application/json;odata=verbose",
  21. "X-RequestDigest": $("#__REQUESTDIGEST").val(),
  22. "content-Type": "application/json;odata=verbose"
  23. },
  24. data: JSON.stringify(metadata),
  25. success: function(data) {
  26. console.log(data);
  27. console.log("Site and System Master Pages Changed successfully.");
  28. },
  29. error: function(error) {
  30. alert(JSON.stringify(error));
  31. }
  32. });
  33. }
  34. </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

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.

Site Settings

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