Master Pages in SharePoint 2007

Basic Intro:
Master pages could be classified in three groups as per their usage:

• Application Master
• System Master
• Site Master

There are three kinds of Pages in sharepoint (explains why there are three kinds of master pages):

• Publishing Pages (like the pages saved in Pages document library e.g pages/default.aspx)
• Forms and Views pages (like document library views e.g. Forms/allitems.aspx or Forms/MyCustomView.aspx)
• Application Pages (like all pages that come under _layouts/…. e.g. _layouts/settings.aspx)

 Application master is a type of master page that appears on any page that resides in Layouts folder under 12 hive (or _layouts/…. appears in the URL) for a Sharepoint Site e.g. Site Settings pages (_layouts/settings.aspx).

Site master is a type of master page that appears on publishing pages throughout sharepoint sites, such as those pages stored in the Pages document library.

System Master is a type of master page that specifically relates to Forms and Views pages within sharepoint sites, such as Forms/Allitems.aspx or Forms/MyCustomView.aspx.

We know that we can set a master page as a ‘System Master Page’ from Site Actions -> Site Settings -> Modify All Site Settings -> Master Page:

The page set here as ‘System Master Page’ is essentially (or by default) for Forms and Views pages. Change this master page here and you will see that only the pages under “…Forms/…” will display the new master page. The site home page and all settings pages will still have the same old master page. 

We also know that we can set a master page as a ‘Site Master page’ from Site Actions -> Site Settings -> Modify All Site Settings -> Master Page:

The page set here as ‘Site Master Page’ is essentially (or by default) for Publishing Pages.Change this master page here and you will see that only the pages saved in the Pages library e.g.  Pages/default.aspx will display the new master page. The Forms and Views pages and all settings pages will still have the same old master page.

 

Default and Custom Master Page:
Now we have also heard about ‘Default Master Page’ and ‘Custom Master Page’. What are these. Just to clarify the confusion: ‘custom master page’ and ‘default master page’ are just terms used as a setting for a master page. These terms usually come into play while working with SharePoint Designer. These are not master pages themselves, these are just to set a master page as custom or default. Ofcourse there is a reason to that and I will explain that shortly.

So, why do we set master pages as custom or default? What happens when we do this? whats the gain? This brings us to the discussion of tokens.

Why Tokens?:
In an asp.net page we can specify a master page like this <%@ Page Language=”C#”

MasterPageFile="~/MasterPages/Master1.master".........

Now, if you want to change the master page, we have to modify the page code and specify a new master page. This is not expected in SharePoint. SharePoint is a content management system targeted towards end users, hence it is supposed to provide maximum functionailty out of the box without doing much customizations, let alone changes to the code. So, changing master pages is one of the common requirements by end users, and ofcourse they need it done without changing the code for the page. For end users, they should just select a different master page from a list and it should render for their site.

So, to achieve such an architecture Sharepoint uses tokens. In sharepoint, master pages are specified in Content Pages (in Non Pulishing Sites) and Page Layouts (in Publishing Sites). These pages use tokens to specify a master page in SharePoint. These tokens will be replaced by the actual master page reference.

Types of Tokens:
Now tokens are of two types:

• Static
• Dynamic

It is important to understand the difference first 🙂 (before we dive deep in details). The static tokens will point to a “location” where the content page could be found.

Dynamic tokens will not specify a location, rather they will point to a place from where you will get the location of the master page at run time (a little indirect and dynamic). I will talk about that place below.


*******************************************
Static Tokens:
Static tokens are of two types:

Static Token for Site Collection-Relative Master Page:
~sitecollection/_catalogs/masterpage/MyMasterPage.master

Static Token for Site-Relative Master Page:
~site/_catalogs/masterpage/MyMasterPage.master

Example:
For instance, if our content page is located at
http://MySitecol/MySubSite1/MySubsite2/default.aspx

and we use the token

"~sitecollection/MyMasterPage.master"

our content page would use the master page at
http://MySiteCol/MyMasterPage.master

If you use the token

"~site/MyMasterPage.master"

the content page would use the master page located at http://MySiteCol/MySubSite1/MySubSite2/MyMasterPage.master

These two are valid static tokens:
~sitecollection/_catalogs/masterpage/MyMasterPage.master
~site/_catalogs/masterpage/MyMasterPage.master
************************************


************************************
Dynamic Tokens:
Dynamic Tokens are of two types as well:

Dynamic Token “~masterurl/defualt.master”:
This token is set as the value of MasterPageFile attribute e.g.

<%@ Page MasterPageFile="~masterurl\default.master"%>

which is telling that MasterPageFile is a dyanmic token, so look for the master page reference at a predefined place (its the same place we talked about above), so what is that place, it is a property named as MasterUrl. So, the token “~masterurl\default.master” will be replaced by whatever is in the MasterUrl property. Now, what has this property got in it. It has the server relative full path to the master page including the file name.

Something very important to note here is that “~masterurl/default.master” is a complete token string, default.master is part of the token and not the master page name. You can set MasterUrl property both by SharePoint Designer and Sharepoint Object Model.

page.MasterPageFile = "~masterurl/default.master";
SPContext.Current.Web.MasterUrl = "/_catalogs/masterpage/MyMasterPage.master"; 

Dynamic token “~masterurl/custom.master”:
Same mechanism applies to “~masterurl/custom.master” as well. The only difference is that it refers the property called as CustomMasterUrl. The token “~masterurl/custom.master” is replaced at run time by the value in the CustomMasterUrl property, which contains the server-relative full path to the master page, including file name. You can set CustomMasterUrl property both by SharePoint Designer and Sharepoint Object Model.

page.MasterPageFile = "~masterurl/custom.master";
SPContext.Current.Web.CustomMasterUrl= "/_catalogs/masterpage/MyCustomMaster.master";
**********************************


Usage of two Dynamic Tokens in Non Publishing sites:
By default, all SharePoint Content pages use “~masterurl/default.master” dynamic token. And the Master Url property is set to default.master master page. A Content page could be a Team Site home page e.g. default.aspx. Master pages in Content pages are set in the Content pages themselves. So, if you open a default.aspx page of a Team Site in SharePoint Designer, you will find something like this:

Page language="C#" MasterPageFile="~masterurl/default.master"

Now, if you open …/Forms/…. pages of a Team site e.g. …/Forms/AllItems.aspx page in SharePoint Designer (_catalogs/masterpage/Forms/AllItem.aspx), you will see the following:

Page language="C#" MasterPageFile="~masterurl/default.master"

So, they have only one master page i.e. default.master, publishing is not there at all, they do not have custom master pages like publishing site has e.g. BlueBand.master, BlackBand.master etc. So, if there is only one master page, one token should be enough to refer it, thats why only “~masterurl/default.master” is used in both kinds of pages i.e. Content pages and Forms/Views pages.

In a team site you cannot change master page from the UI (assuming that it is not created under any publishing site). you can only do it from designer, that also if you have added some other new master page in the site collection in master page gallery (yeah, a team site has a Master Page gallery), otherwise team site has only one master page by default and that is used for all kinds of pages i.e. content pages, Forms and Views pages and Application pages.

Usage of two Dynamic Tokens in Publishing sites:
“~masterurl/custom.master” is not used by any SharePoint Content page by default. Then why is it there at all? This token is used in all Publishing pages in SharePoint and is provided as a way to have a second shared master page. A Publishing page could be a Publishing site home page e.g. default.aspx page. Master pages are specified in Page Layouts in Publishing pages. So, if you open DefaultLayout.aspx of a Publishing site in SharePoint Designer (default layout page for all Publishing pages), you will see something like this:

Page language="C#" MasterPageFile="~masterurl/custom.master"

Now, if you open …/Forms/…. pages of a Publishing site e.g. …/Forms/AllItems.aspx page in SharePoint Designer (_catalogs/masterpage/Forms/AllItem.aspx), you will see the following:

Page language="C#" MasterPageFile="~masterurl/default.master"

Now, you can clearly see that in Publishing scenario, we are using two different tokens to fulfill the need for two different types of master pages applied to the site at one time. One token would not have fulfilled this requirement as we need different look for a Publishing page and a different look for Forms/Views page.

How to set Dynamic Tokens from SharePoint Designer?
Now there is an option in SharePoint Designer through which you can set a master page as Default or Custom. Open your site in Designer and go to “_catalogs/masterpage” folder, right click any master page to see the context menu and you will see two options as “Set as Default Master Page” and “Set as Custom Master Page”. Make sure to Check Out the page before you set it as Default or Custom. Save your site in Designer and move to SharePoint to view the changes made. You must see the new master page applied to the site or …/Forms/….pages as per the selection of Custom or Default respectively:

Relationship between UI, SharePoint Designer and Page Code:
I want to show a relationship among so many cofusing things here, have a look:

[~masterurl/default.master](the token)----->[/_catalogs/masterpage/default.master](the URL usually)---->[System Master Page](as specified in Site Actions -> Site Settings -> Modify All Site Settings -> Master Page)----->[Set as default masterpage] (as specified in SharePoint Designer)

So which ever master page you select from the User Interface in the System Master Page section, that will be picked up by the “~masterurl/default.master” token in the content page, in default sharepoint settings it will resolve to .../_catalogs/masterpage/default.master master page, and now you may want any other of your master pages to be picked up by “~masterurl/default.master” token, and you may want to do it from sharepoint desinger, in that case you will use “set as default masterpage” option. And if you want to do it from UI, simply go to the System Master Page section and select the desired master page from the available list.

So, I hope now you understand the mapping between these somewhat confusing terms.

System Master Page setting from the UI corresponds to “Set as Default Master Page” setting in SharePoint Desinger. When we set a master page as “Set as default master page”, we actually mean to say that set MasterUrl property to point to this master page. Similarly, when we set a master page as a System Master Page, we actually mean to say that set MasterUrl property to point to this master page.

Similarly, here is the second obvious combination:

[~masterurl/custom.master](the token)----->[/_catalogs/masterpage/custom.master](the URL usually)---->[Site Master Page](as specified in Site Actions -> Site Settings -> Modify All Site Settings -> Master Page)----->[Set as custom masterpage] (as specified in SharePoint Designer)

Site Master Page setting from the UI corresponds to “Set as Custom Master Page” setting in SharePoint Desinger.When we set a master page as “Set as custom master page”, we actually mean to say that set CustomMasterUrl property to point to this master page. Similarly, when we set a master page as a Site Master Page, we actually mean to say that set CustomMasterUrl property to point to this master page.

Conclusion:
The two tokens works exactly the same. The purpose of having two tokens is that it provides a way to have a second shared master page as per a SharePoint Publishing site needs i.e. one for Publishing pages and one for Forms/Views pages.

Note that MasterUrl and CustomMasterUrl properties are set at SPWeb level:

SPContext.Current.Web.CustomMasterUrl = "/_catalogs/masterpage/MyCustomMaster.master";
SPContext.Current.Web.MasterUrl = "/_catalogs/masterpage/MyMasterPage.master";

So, these properties are available from anywhere within the web.

Hope this helps–