Master Pages Revisited: References to master pages in SharePoint

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.