Master Page Url Tokens in SharePoint

Master Page Url Tokens in SharePoint

 

In SharePoint you reference master page in pages by url as


<%@ Page language="C#" MasterPageFile="...."

You can have as many master pages you want and reference them using static tokens "~site/.../master1.master" and "~sitecollection/.../master2.master"


SharePoint also supports two dynamic tokens to reference master pages.

~masterurl/default.master
~masterurl/custom.master

How to use these dynamic token can be confusing.

Basically when you start designing a portal site, you first make a decision if you want to use the static token or dynamic token. If you can use static token, you don't need worry about the dynamic tokens.

However in many situations this is not the case.

1. All OOTB application/setting pages use dynamic token. If you care about customizing the OOTB application pages, you need to use dynamic tokens.

2. All publishing portal pages which use page payout uses dynamic token. The only way to change them is to leverage dynamic tokens.

To leverage dynamic tokens, you can set SPWeb's property in code as

sysMasterUrl = SPUrlUtility.CombineUrl(siteCollection.ServerRelativeUrl, "_catalogs/masterpage/" + sysMasterUrl);
siteMasterUrl = SPUrlUtility.CombineUrl(siteCollection.ServerRelativeUrl, "_catalogs/masterpage/" + siteMasterUrl);
foreach (SPWeb site in siteCollection.AllWebs)
    {
            site.MasterUrl = sysMasterUrl;
            site.CustomMasterUrl = siteMasterUrl;
            site.Update();
    }

Dynamic tokens:

• ~masterurl/default.master – The page references the master page file that is stored in the MasterUrl property.
• ~masterurl/custom.master – The page references the master page file that is stored in the CustomMasterUrl property. 

 
The code will change the url of the dynmaic tokens.

The publishing portal site also provides UI to let user to change two master pages "Site Master Page" and "System Master Page". At first sight, you may think that "Site Master Page" is referring token "~masterurl/default.master " and "System Master Page" is referring token "~masterurl/custom.master".

Actually it is the opposite,

"Site Master Page" is referring token ~masterurl/custom.master
"System Master Page" is referring token "~masterurl/default.master


So in a publishing portal, if you changed the "custom.master (CustomMasterUrl)" by code or by UI, you changed all publishing pages's master page (pages under Pages library and built using page layout)

If you changed the "default.master (MasterUrl)" by code or by UI, you changed all OOTB application pages's master page.

Use Master Page on Application Page

Refer to this MSDN article 
http://msdn.microsoft.com/en-us/library/ee537530(v=office.14).aspx

SharePoint 2010 supports using DynamicMasterPageFile with the dynamic tokens

~masterurl/default.master
~masterurl/custom.master

However there are situations that you want to reference static master page from custom application page. The only way to do this is to use the old "MasterPageFile" and reference a master page in the same location as the application page.

For example, if the application is at /_layouts/myCompany/myapplication.aspx, then the master page must be at /_layouts/myCompany/mymasterpage.master

and reference it as

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="myapp1.aspx.cs" Inherits="...." MasterPageFile="mymasterpage.master" %>

If the master page is at any other location such as in the master page gallary, any attempt to try something like

MasterPageFile="~sitecollection/_catalogs/masterpage/mymasterpage.master"

or just

MasterPageFile="/_catalogs/masterpage/mymasterpage.master"

will result in errors like

System.Web.HttpException: The file '/_layouts/mycompany.Portal/~sitecollection/_catalogs/masterpage/mymasterpage.master' does not exist.    at System.Web.UI.Util.CheckVirtualFileExists(VirtualPath virtualPath)     at System.Web.Compilation.BuildManager.GetVPathBuildResultInternal(VirtualPath virtualPath, Boolean noBuild, Boolean allowCrossApp, Boolean allowBuildInPrecompile)     at System.Web.Compilation.BuildManager.GetVPathBuildResultWithNoAssert(HttpContext context, VirtualPath virtualPath, Boolean noBuild, Boolean allowCrossApp, Boolean allowBuildInPrecompile)     at System.Web.UI.BaseTemplateParser.GetReferencedType(VirtualPath virtualPath, Boolean allowNoCompile)     at System.Web.UI.PageParser.ProcessMainDirectiveAttribute(String deviceName, String name, String value, I... 9a0f3bd4-6f73-4d3d-a25d-987cec6180e1

or

System.Web.HttpException: The referenced file '/_catalogs/masterpage/mymasterpage.master' is not allowed on this page. at System.Web.UI.TemplateParser.ProcessError(String message) at System.Web.UI.BaseTemplateParser.GetReferencedType(VirtualPath virtualPath, Boolean allowNoCompile) at System.Web.UI.PageParser.ProcessMainDirectiveAttribute(String deviceName, String name, String value, IDictionary parseData) at System.Web.UI.TemplateParser.ProcessMainDirective(IDictionary mainDirective) 3146ae16-c20e-442f-9aac-90fd9cdd0597

Reference:
http://msdn.microsoft.com/en-us/library/ms476046(v=office.12).aspx