Customizing Master Pages in Windows SharePoint Services

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

When you install Windows SharePoint Services, a single default master page is applied to all the pages in a site. You can, however, create your own master pages for a site and make them available to the site and any sites beneath it.

There are two supported scenarios for customizing master pages in Windows SharePoint Services:

  • Copy the default.master file that is installed with Windows SharePoint Services to another file and make your changes to your renamed file.

  • Edit the default.master page in Microsoft Office SharePoint Designer 2007, where you can edit master pages, view master pages, create content pages, and view content pages with the master pages marked as masters and read-only.

    Office SharePoint Designer is the only application in which you can see a master page preview.

Warning

Do not edit the default.master file directly in the <%System Drive%>Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\GLOBAL\ folder.

When a new site is created, it uses the default master page that is located in the file system. If a master page is customized using Office SharePoint Designer, Windows SharePoint Services stores a modified version of the master page in the content database. Changes to the master page do not affect the content pages that refer to it; they remain in the file system.

Note

Customization of the master page for a site changes only the content pages for that site. It does not affect application pages (pages in _layouts), because _layouts pages are pages of the Windows SharePoint Services application and are shared across sites.

Referencing the Master Page from a Content Page

Windows SharePoint Services provides several tokens to reference the master page—two dynamic tokens ("~masterurl/default.master" and "~masterurl/custom.master") and two static tokens ("~site/default.master" and "~sitecollection/default.master").

Note

These tokens apply to Windows SharePoint Services master pages only; they do not apply to ASP.NET 2.0 master pages.

  • Dynamic token "~masterurl/default.master"

    This token references a master page from a content page by using the MasterPageFile attribute together with the value of the MasterUrl property. As an example, in the following page directive, <%@ Page MasterPageFile="~masterurl\default.master"%>, the token "~masterurl/default.master" is replaced at run time by the value in the MasterUrl property. This property contains the server-relative full path to the master page, including file name.

    At installation time, all SharePoint content pages use this dynamic token and the MasterUrl property is set to the Windows SharePoint Services default.master; however, you can change this value at any time to point to a different master page.

    Important

    The entire string "~masterurl/default.master" comprises the token.

  • Dynamic token "~masterurl/custom.master"

    This token references a master page from a content page by using the MasterPageFile attribute with the value of the CustomMasterUrl property. 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.

    This token is not used by any SharePoint content pages by default, and is provided as a way to have a second shared master page.

    Important

    The entire string "~masterurl/custom.master" comprises the token.

  • Static tokens "~site/default.master" and "~sitecollection/default.master"

    You can use these tokens to link to a site-relative or site collection-relative master page. For example, if your content page is located at http://siteColl/subsite1/subsite2/default.aspx and you use the token "~sitecollection/mypage.master", your content page would use the master page at http://siteColl/mypage.master. If you use the token "~site/mypage.master", the content page would use the master page located at http://siteColl/subsite1/subsite2/mypage.master.

Note

The MasterUrl and CustomMasterUrl properties are both set to "/_catalogs/masterpage/default.master" by default. If you subsequently need to delete default.master, you must set both of those properties to a different value, not just one of them, or an error is raised that suggests the default.master file is still being used as the master page for the site.

Alternatively, you can change the master page used by a content page by directly changing the URL for the MasterPageFile attribute specified in the page directive. Unlike using the MasterUrl property to change a master page, however, this is a change to the page's content.

Additional Considerations for Working with Master Pages in Windows SharePoint Services

Consider the following when you are working with master pages in Windows SharePoint Services:

  • Compilation mode for master pages works like the compilation mode for any other .aspx page. You can change the compilation mode at any time, and you can combine compilation modes for master and content pages, for example, a compiled master page and a content page that is not compiled.

    Remember, however, that although compiled master pages can contain inline script, after that page is customized in Office SharePoint Designer, or a similar tool, the page is no longer compiled and script no longer runs. For that reason, it is recommended that you do not include inline script in your master pages.

  • Although the underlying technology enables the creation of nested master pages, nested master pages are not supported in Windows SharePoint Services.  Using nested master pages can cause unexpected behavior in some scenarios, such as preventing content from rendering.

    Note

    Some page editors may not effectively support nested master pages.

  • You cannot add Web Parts in zones to a master page. You can add static Web Parts (parts outside of a zone) to a master page, but you cannot add dynamic Web Parts to master pages.

    You can add zones to master pages and later add Web Parts to the zone in the browser, but the Web Parts are associated with the content page.

See Also

Tasks

How to: Customize the Display of Quick Launch

Concepts

Windows SharePoint Services Default Master Pages