Master Pages Revisited: References to master pages in SharePoint

  • Article

I'm still neck-deep in WCM planning, design, and development on my current project and also get lots of questions on branding topics, so a frequent point of discussion is various design patterns for the use of master pages. One of the topics that's come up a lot recently is "how do I assign master page X to page (or page layout) Y", so I've attempted to summarize my findings and recommendations on this topic in a handy table in this post.

First off, a refresher on key jargon used in the table...

Page Types - these include System Pages (i.e. web pages & web part pages that aren't based on page layouts and list view/display form pages), Page Layouts, and Application Pages.

There are five techniques described in the table for assigning a master page reference:

  • Hardcoded
    This is a relative or absolute path to a master page. Relative locations are based on the page instance's location - i.e. "../_catalogs/masterpage/this.master" will find this.master in the current SPWeb's master page gallery, which may or may not be the top-level site's master page gallery.
  • Token-based References as described in this article 
    • Static Token for Site-Relative Master Page
      Note that the syntax for using this token is incorrect in the article - the correct syntax is ~site/_catalogs/masterpage/yourmasterpage.master.
    • Static Token for Site Collection-Relative Master Page
      Note that the syntax for using this token is incorrect in the article - the correct syntax is ~sitecollection/_catalogs/masterpage/yourmasterpage.master.
    • Dynamic Token for SystemMaster Page
      The ~masterurl/default.master token will use the current site's System Master Page.
    • Dynamic Token for Site Master Page
      The ~masterurl/custom.master token will use the current site's Site Master Page.

 

Approach

Page Type

Result

Comments

Hardcode

../_catalogs/masterpage/XXX.master

(or ../../_catalogs, etc., depending on how deep the page is located in the site hierarchy)

System

Works - desired master page is used

 

~masterurl/default.master

System

Works - System Master Page is used

 

~masterurl/custom.master

System

Works - Site Master Page is used

 

~site/_catalogs/masterpage/XXX.master

System

Works - desired master page is used

 

~sitecollection/_catalogs/masterpage/XXX.master

System

Works - desired master page is used

 

Hardcode

../_catalogs/masterpage/XXX.master

Page Layout

Error

Even if this did work, hardcoding a reference to a master page with this kind of relative path is a bad idea - remember that you may have subsites!

~masterurl/default.master

Page Layout

No effect

Simplest approach is based on information architecture - if a publishing page needs to use a different master page, put it in a different site.

 

If this doesn't cut it, ask yourself why you really need two different looks & feels for a single site. Remember that you can override just about anything from the master page in the page layout. Did you think about designing your master page in such a way that you can override the undesirable  behavior/appearance in the page layout?

~masterurl/custom.master

Page Layout

No effect

Same as above.

~site/_catalogs/masterpage/XXX.master

Page Layout

No effect

Same as above.

~sitecollection/_catalogs/masterpage/XXX.master

Page Layout

No effect

Same as above.

Hardcode

../catalogs/masterpage/XXX.master

Application

Error

Even if this did work, hardcoding a reference to a master page with this kind of relative path is a bad idea - remember that you may have subsites!

~masterurl/default.master

Application

Error

See my first big branding post for techniques applying to adjusting the look & feel of LAYOUTS pages - https://blogs.msdn.com/bgeoffro/archive/2007/11/12/branding-a-moss-corporate-intranet-portal-part-1b-branding-methods-by-scope-and-scenario.aspx .

If you want to use a site or site collection-specific master page, the solution must involve an HttpModule. It'd be a different kind of branding module than I've described in my previous branding posts, as the module would need to read the Site Master Page or (more likely) the System Master Page from the current SPWeb based on the path, and then apply it to the page.

~masterurl/custom.master

Application

Error

Same as above.

~site/_catalogs/masterpage/XXX.master

Application

Error

Same as above.

~sitecollection/_catalogs/masterpage/XXX.master

Application

Error

Same as above.

Note that I didn't mention Site Pages (pages based on page layouts) anywhere in the table. You can't assign a master page to them using any of these techniques since they inherit from a page layout. Your only option in the unusual scenario of assigning a specific master page to a specific Site page would be to use a HttpModule that references the absolute path to that specific page and reassigns the master page. A better approach would be to use a page layout specifically designed for that page instance, and then override the master page as needed in the page layout.