Edit

Master pages in the SharePoint Add-in model

  • Article

The approach you take to implement custom master pages in SharePoint sites is different in the new SharePoint Add-in model than it was with Full Trust Code / Farm Solutions. In a typical Full Trust Code (FTC) / Farm Solution branding scenario, custom master pages are created to implement a custom brand. The master pages are typically packaged in a feature that uses declarative code and a FTC / Farm Solution to deploy the master pages and register them with the SharePoint site.

In a SharePoint Add-in model branding scenario, custom master pages may be also be used. You can deploy and register your custom master pages on SharePoint sites via the remote-provisioning pattern.

High-level guidelines for custom master pages

As a rule of a thumb, we would like to provide the following high-level guidelines for custom master pages.

  • You can customize SharePoint sites using custom master pages, but keep in mind this will cause you additional long-term costs and challenges with future updates.

    • In most cases, you can achieve all common branding scenarios with themes, composed looks and alternate CSS.

      See the Branding SharePoint Sites (SharePoint Add-in Recipe) to learn all about the different branding options you have for SharePoint sites with the SharePoint Add-in model. The recipe will help you consider the short and long-term impact of customization from an operational and a maintenance perspective. You may discover that a custom master page is not required to implement your specific branding requirements.

    • If you chose to use custom master pages, be prepared to apply changes to the custom master pages when major functional updates are applied to Office 365.

  • Use remote provisioning to deploy and register custom master pages with SharePoint sites.
  • Do not use declarative code or sandbox code to deploy and register master pages with SharePoint sites.

Team sites vs. publishing sites

When is a custom master page needed?

When applying custom branding to SharePoint sites, you will encounter the need to brand both team sites and publishing sites. Generally speaking, intranets built on SharePoint in both on-premises and Office 365 scenarios use a combination of team sites and publishing sites.

Custom branding requirements often times require specific layout changes that themes and JavaScript embedding techniques cannot accomplish.

In such a scenario, team sites usually do not require the amount of custom branding that publishing sites do and the out-of-the-box SharePoint Contemporary View for mobile devices is usually sufficient to support mobile devices for team sites. Since this is the case, it is best to only use custom master pages for publishing sites and to use AlternativeCSS and custom SharePoint themes (*.spcolor files), font schemes (*.spfont files) and background images defined as composed looks to brand team sites.

Deployment considerations

Custom master pages are typically applied when a site is provisioned. The remote provisioning process fits very well with this approach. Usually the only time you will use the web browser to manually apply SharePoint branding customization is when you are prototyping or modifying a single SharePoint site that is not planned to grow to include other site collections or sub sites.

More details about custom master pages and page layouts for SharePoint sites

In scenarios where a custom master page is the only way to implement your custom branding requirements you can create a custom master page and page layouts. Keep in mind the points made at the beginning of this article with regard to the long-term maintenance costs associated with this approach.

  • Using custom master pages for SharePoint sites provides the ultimate level of customization (unlimited).
  • Using custom master pages for SharePoint sites requires the largest amount of time to implement and maintain in the short and long term.
  • Any changes to out-of-the-box master pages that come with service updates will not be reflected in custom master pages.
  • You can apply custom master pages at a per-site level.
  • When using a custom master page it is recommended to start with one of the out-of-the-box master pages and modify it to meet your needs.
    • Try to minimize the amount of customization you make with custom master pages; this will make it easier to update them when Office 365 service changes to out-of-the-box master pages must be replicated to custom master pages.
  • There are many required content placeholders in SharePoint master pages that must not be removed or they will cause the pages to error. You will know when you have removed a required content placeholder because the minute you deploy it and assign the master page to your site, errors will appear.

When are custom master pages and page layouts for a SharePoint site a good fit?

This option works well when your branding needs are very specific or you are using publishing sites.

PnP samples

Applies to

  • Office 365 Multi Tenant (MT)
  • Office 365 Dedicated (D) partly
  • SharePoint 2013 on-premises – partly

Patterns for dedicated and on-premises are identical with SharePoint Add-in model techniques, but there are differences on the possible technologies that can be used.