Understanding Master Pages

With master pages, you can easily change the look and feel for all the pages in a SharePoint site. Master pages provide a simple way to create a site template. They work by allowing you to design an HTML page with editable regions. These editable regions are called content placeholders and represent the parts of the template that will be customized on each page individually. The area outside the confines of content placeholders is identical for all the pages that are using the master page and is not editable on a page-by-page basis. By default, all pages in a SharePoint site use only one master page. The actual content of a content placeholder is defined by pages that use the master page: individual content pages, form pages, and application pages. The content in a content placeholder is also known as a content placeholder definition.

When rendered, the layout of a master page is automatically combined with the content of a page referring to such a master page to output a single HTML page. The way master pages work in Windows SharePoint Services 3.0 is identical to the way master pages work in ASP.NET 2.0.

The introduction of the concept of master pages into SharePoint technologies is a great new feature for ensuring uniformity between SharePoint sites. Master pages offer the following benefits:

• An improved editing experience for Windows SharePoint Services pages It is easier to make design changes in one place and propagate those changes to all the pages that use this master page.

• Web-level editing There is only one place to edit and change the master page elements.

• User interface reuse It is easy to create a page with a custom look and feel, and it is even easier to have all your pages adopt this look and feel.

• Consistency This includes consistency between pages and an improved end-user experience because of this consistent look and feel.

Content Pages

Content pages contain the definitions of content placeholders. All content pages share the same page structure: navigation, logos, search box, login controls, editing controls, CSS references, and the global breadcrumb. In Windows SharePoint Services 3.0, this shared page structure is placed in a master page called the default.master. The following SharePoint content pages use this default.master page:

•  default.aspx

• The list pages

  q	AllItems.aspx
  q	DispForm.aspx
  q	NewForm.aspx
  q	EditForm.aspx

• The document libraries

  q	Upload.aspx
  q	Webfldr.aspx

• Newly created content pages in a SharePoint site

The standard set of content pages is initially located on the file system, in the same directory area as the rest of the template pages. For example, in the case of a SharePoint site,  default.aspx is stored at [drive letter]:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\SiteTemplates\sts. Form pages such as editform.aspx are stored in the [drive letter]:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\Features folder.

SharePoint Hive

The location %SystemDrive%\Program Files\Common Files\Microsoft Shared\Web server extensions\12\ is also known as the SharePoint hive or SharePoint 12 hive. This is the starting place where all the files related to SharePoint are installed. For more details on the SharePoint hive, see Chapter 5, "Installing Microsoft Office SharePoint Server 2007."

A content page can have two states: customized or uncustomized. Once a content page is customized, it is stored in the content database. Uncustomized pages are stored on the file system. This is not a new concept; in SharePoint 2003, this was called unghosting (customized) and ghosting (uncustomized). One of the great new features in SharePoint Designer 2007 is the built-in ability to recognize customized pages and the option you have within the user interface to revert them to a template-in other words, to make them uncustomized again.

Content Placeholders

A master page consists of static text, controls, and one or more ContentPlaceHolders controls that define regions where customizable content can appear. Figure 27-15 shows a part of the default.master page containing ContentPlaceHolders controls.

Figure 27-15: Default.master page with ContentPlaceHolders controls

Table 27-2 provides an overview of all content placeholders used by Windows SharePoint Services 3.0 pages.

Table 27-2: Overview of Content Placeholders
Open table as spreadsheet

Name	Description
PlaceHolderBodyAreaClass	Additional body styles in the page header.
PlaceHolderBodyLeftBorder	Border element for the main page body.
PlaceHolderBodyRightMargin	Right margin of the main page body.
PlaceHolderCalendarNavigator	Shows a date picker for navigating in a calendar when a calendar is visible on the page.
PlaceHolderFormDigest	The "form digest" security control. The FormDigest control inserts security validation within a page, and its presence is required if you want to change data in the SharePoint content database.
PlaceHolderGlobalNavigation	The global navigation breadcrumb.
PlaceHolderHorizontalNav	The horizontal navigation area.
PlaceHolderLeftActions	Bottom of the left navigation area.
PlaceHolderLeftNavBar	Left navigation area.
PlaceHolderLeftNavBarBorder	Border element on the left navigation bar.
PlaceHolderLeftNavBarDataSource	DataSource element in the left navigation bar.
PlaceHolderLeftNavBarTop	Top element in the left navigation bar.
PlaceHolderMain	Page's main content.
PlaceHolderMiniConsole	A place to show page-level commands-for example, WIKI commands such as Edit Page, History, and Incoming Links.
PlaceHolderNavSpacer	The width of the left navigation area.
PlaceHolderPageDescription	Description of the contents of the page.
PlaceHolderImage	Image.
PlaceHolderTitleInTitleArea	Page title shown immediately below the breadcrumb.
PlaceHolderSearchArea	Search box area.
PlaceHolderSiteName	Site name.
PlaceHolderTitleAreaClass	Additional styles in the page header.
PlaceHolderTitleAreaSeparator	Separator in the page header.
PlaceHolderTitleBreadcrumb	Main content breadcrumb area.
PlaceHolderTitleLeftBorder	Left navigation area.
PlaceHolderTitleRightMargin	Right margin of the title area.
PlaceHolderTopNavBar	Top navigation area.
PlaceHolderUtilityContent	Extra content at the bottom of the page.
SPNavigation	Empty by default in Windows SharePoint Services. SPNavigation can be used for additional page-editing controls.
WSSDesignConsole	The page editing controls when the page is in Edit Page mode (after clicking Site Actions, and then clicking Edit Page).

Master Page Tokens

When using master pages and content pages, you have to add an attribute to the Page directive of the content page. Windows SharePoint Services provides two kinds of tokens to reference the master page: dynamic and static tokens. These tokens apply only to Windows SharePoint Services master pages; they do not apply to ASP .NET 2.0 master pages.

• Dynamic tokens The value of a dynamic token is calculated at runtime, depending on the current instance of the SPWeb class. There are two types of dynamic tokens:

  q

  ~masterurl/default.master This token is used by a Page Directive that is placed in a content page. The Page Directive looks like this: <%@ Page MasterPageFile="~masterurl\default.master"%> The token is replaced at runtime with the value of the MasterUrl property of the SPWeb class. This property contains the relative path to the master page. At installation time, all SharePoint content pages use this token and the MasterUrl property of the SPWeb class is set to the Windows SharePoint Services default.master. This value can be changed to point to a different master page.

  q

  ~masterurl/[custom].master This token is used by a Page Directive that is placed in a content page. Replace [custom] with the name of your custom master page. The Page Directive looks like this: <%@ Page MasterPageFile="~masterurl\[custom].master"%>. The complete token is replaced at runtime by the value of the CustomMaster-Url property of the SPWeb class that contains the relative path to the master page. This token provides a way to define other custom master pages for a page.

• Static tokens You can use static tokens to link to a site-relative or site collection-relative master page. There are two types of static tokens:

  q	~site/default.master If your content page is located at http://mySiteCollection/mySubSite/default.aspx and you use the token "~site/mypage.master", the content page uses the master page located at http://mySiteCollection/mySubSite/mypage.master.
  q	~sitecollection/default.master If your content page is located at http://mySiteCollection/mySubSite/default.aspx and you use the token "~sitecollection/mypage.master", your content page uses the master page at http://mySiteCollection/mypage.master.

Instead of making use of dynamic or static tokens, you can change which master page a content page uses by directly changing the URL for the MasterPageFile attribute specified in the Page directive. Changing this attribute will influence which master page a specific content page uses. You can also use the MasterUrl property of the SPWeb class, which represents the entire SharePoint site, to change a master page. If you use the MasterUrl property of the current SharePoint site to change a master page, you will change the master page for all content pages in the SharePoint site.

When working with master pages in Windows SharePoint Services, you need to have a basic understanding of the meaning of page compilation mode and nested master pages. The compilation mode specifies how the ASP.NET engine compiles ASP.NET (.aspx) pages. The compilation mode for master pages is identical to the compilation mode for any other ASP.NET page. You can change the compilation mode whenever you want, and you can combine different compilation modes for master and content pages. There are three compilation modes: Always, Auto, and Never. The default compilation mode is Always, which means that a page will be compiled whenever a request to it is made. The Auto compilation mode means that the ASP.NET engine will not compile the page, if possible. The Never compilation mode means that the page will never be compiled dynamically. If the page contains a script block or code that requires compilation, ASP.NET will return an error and the page will not be run.

By default, master pages are uncustomized and are compiled when requested. Such master pages can contain inline script. However, you should be aware that once a master page is customized in SharePoint Designer 2007, the SharePoint SafeMode parser that prevents the execution of inline script parses the page.

By default, Windows SharePoint Services does not use nested master pages, but that does not block users from using them. You can create master pages at any level and have a master page that refers to another master page. For example, you can reference one master page from another master page using the following directive:

 <%@ Master master=parent.master %> 

You can add static Web Parts to a master page, but you cannot add dynamic Web Parts to master pages. Static Web Parts are Web Parts that are placed outside of a Web Part zone. A user cannot interact with a static Web Part or modify it within a browser. A dynamic Web Part is placed inside a Web Part zone, and a user can modify its properties. You can add zones to master pages and later add (dynamic) Web Parts to these zones in the browser. However, those Web Parts are associated to the content page, not to the master page.

The Difference Between Application, Content, and Form Pages

There are several types of pages in a portal site: application, content, and form pages. Customization of the site master page influences only the content pages for that specific site.

Application and form pages are pages that are used by Windows SharePoint Services itself and are shared across sites. Examples of such pages include the native SharePoint pages used to create new lists, document libraries, edit views, and so on. Application and form pages are stored at [drive letter]:\Program Files\Common Files\Microsoft Shared\Web server extensions\12\TEMPLATE\LAYOUTS. These pages run in direct mode, meaning that SharePoint does not intercept these pages but allows the pages to be executed normally by the ASP.NET engine. The contents of the layouts directory are considered to fall outside the scope of control of the Web site, and its pages are supplied directly by IIS as requested. Arbitrary code can be used within custom ASP.NET pages that are placed in this directory.

The master page applied to application and form pages is called application.master. If you want to use this master page, you must add an attribute to the Page directive of the application or form page. The token used to reference this master page is /_layouts /application.master. You can edit the application.master page and application and form pages in SharePoint Designer 2007.

Customize Master Pages

Windows SharePoint Services has one single master page built into it that applies to all content pages in a site. You can create your own master pages for a site and make them available for that site and the sites beneath it. There are two supported scenarios for customizing master pages:

• Make a copy of the default.master page, and remove the markup around placeholders.

• Start with a blank master page, and build it from the ground up. You can copy placeholders from the default.master page.

When creating custom master pages, developers must use the same set of content placeholders or a superset of these placeholders; otherwise, pages using the custom master page might fail to render. For custom applications, it is better to make your own custom master and to leave the default.master page alone.

SharePoint Designer 2007 has a safety net when you start customizing master pages. You can use the Version History command to roll back a page to a previous version. Alternatively, you could use the Revert To Template command to get the original master back from the site definition. The original master page is located at [drive letter]:\Program Files\Common Files\Microsoft Shared\Web server extensions\12.

Each page in a SharePoint site depends on a master page, and each SharePoint site has a Master Page Gallery. This Master Page Gallery contains all the master pages for all the pages in a SharePoint site. You can open a master page with SharePoint Designer 2007 via the browser. To open a SharePoint site in a browser, click Site Actions, click Site Settings, and in the Galleries section, click Master Pages. On the Master Page Gallery, you can click the drop-down menu and select Edit In Microsoft Office SharePoint Designer 2007.

The default master page is located at [drive letter]\Program files\Common Files\Microsoft Shared\Web Server extensions\12\Template\Features\MPLib. When this master page is uncustomized, its page definition is cached on the front-end Web server and shared across sites. If the master page definition in default.master is edited for a particular SharePoint site, an edited copy of the master page file is stored in the content database. This is called customization.

The Master Page toolbar is the key tool for customizing placeholders and creating new ones. The Master Page toolbar includes the functions listed in Table 27-3.

Table 27-3: Master Page Toolbar Functions
Open table as spreadsheet

Image	Description
	This drop-down list shows all the placeholders available in the master page.
	Click to open the Manage Content Regions dialog box.
	Click to show the Content Regions Labels in the page.

To create a new master page and add content placeholders, follow these steps:

1. From the Folder List task pane, open the _catalogs folder and right-click the masterpage folder. Select New, and then select SharePoint Content. The New SharePoint Content window opens.

2. Click the Page tab, click General, click Master Page, and then click OK. (See Figure 27-16.)

3. To add new content regions, click Format, click Master Page, and then click Manage Content Regions or right-click the page in Design View and choose Manage Microsoft ASP.NET Content Regions. The Manage Content Regions window opens. Type a region name in the Region Name text box, and then click Add. The name of a region, also known as a placeholder, cannot contain any special characters or white spaces.

4. Select a region type for the content region. Click the region type of the new content region (by default, this is none). A drop-down list appears with the following three region types: Text And Images; Text Only; and Text, Layout, And Images.

Figure 27-16: The Create A New Master Page window

After you create or customize a master page, you probably want to attach the master page to a content page. You can choose whether you want to set your master page as the default or as a custom master page. There are two ways to attach your master page:

• In the Folder List task pane, right-click the master page and choose either Set As Default Master Page or Set As Custom Master Page. If you choose Set As Default Master Page, the default.master part of the master page token is replaced with the name of the new default master page. Make sure that you have included all the content placeholders that are used by the content pages in your master page.

• Click the Format menu (the main menu of SharePoint Designer 2007), select Master Page, and choose Attach Master Page. Doing this opens the Select A Master Page dialog box. Here you can set the default master page and the custom master page. (See Figure 27-17.)

Figure 27-17: The Select A Master Page dialog box

In addition to being able to attach a master page to an existing content page, you can create a new content page based on your own master page. Right-click your master page in the Folder List task pane and choose New from Master Page. (See Figure 27-18). Doing this creates an .aspx file with all the content placeholders your master page contains.

Figure 27-18: The New From Master Page link