Approaches to Creating Master Pages and Page Layouts in SharePoint Server 2007
Summary: Learn two ways in which developers and designers can create Microsoft ASP.NET 2.0 master pages that define a site's global appearance and to create page layouts that define the rendering of specific content pages in Microsoft Office SharePoint Sever 2007 publishing sites. (9 printed pages)
Andrew Connell, Critical Path Training, LLC (Microsoft MVP)
February 2009
Applies to: Microsoft Office SharePoint Server 2007
Contents
Introduction to Creating Master Pages and Page Layouts in Publishing Sites
Understanding Customized and Uncustomized Files in Windows SharePoint Services 3.0
Two Approaches to SharePoint Project Implementations
Creating Master Pages for SharePoint Publishing Sites
Creating Page Layouts for SharePoint Publishing Sites
Summarizing Pros and Cons of the Customization and Development Approaches
Conclusion
Additional Resources
Introduction to Creating Master Pages and Page Layouts in Publishing Sites
Every Microsoft Office SharePoint Server 2007 publishing site—also known as a Web content management (WCM) site—consists of one of more master pages (*.master files) and page layouts (*.aspx files). Each type of file serves a specific purpose. The master pages, also used in traditional Windows SharePoint Services 3.0 collaboration sites, contain the overall appearance ("look and feel") and branding of a site. They contain elements such as cascading style sheet references, common navigation components, search controls, and the typical header and footer seen on all sites. Page layouts are used to define the specific rendering of content pages, or where content is found on the page. Just as in Microsoft ASP.NET 2.0 sites, page layouts are merged with master pages at run time to generate the complete page.
These two types of files are very similar to those found in ASP.NET 2.0 sites, but the process of creating and deploying them is very different in Office SharePoint Server 2007. In fact, in Office SharePoint Server there are two ways to create and deploy these files. As a developer or a designer, you should be aware of both approaches and the advantages and disadvantages of each before embarking on the next Office SharePoint Server 2007 publishing site project.
The primary reason for the difference in the master page and page layout creation process between ASP.NET 2.0 sites and Office SharePoint Server is due to the architecture of the SharePoint platform. In Office SharePoint Server, the file system of a site lives in a database, also known as the virtualized file system, whereas in an ASP.NET 2.0 site the files are on the file system.
This article explains the virtualized file system and then discusses the different approaches that you can use to create custom master pages and page layouts for use in an Office SharePoint Server 2007 publishing site.
Understanding Customized and Uncustomized Files in Windows SharePoint Services 3.0
The SharePoint platform facilitates the concept of delegation of empowerment: the SharePoint platform can host tens—or hundreds of thousands—of sites, each created in a decentralized configuration where the corporate IT group does not have to approve each site creation request and in which the delegated site owner can customize each site and page without affecting other pages and sites that are based on the same templates.
Delegation of empowerment is facilitated by creating instances of files in the SharePoint content database. When these files are requested, the SharePoint platform determines whether the source of the requested file is in the content database (the instance) or whether it is on the file system. The sources for files that are created and modified through the SharePoint API on a site-by-site basis are stored in the content database. After these files are modified, they are called customized files or customized instances. The key point to understand here is that the file customizations are stored in the database and are tied to that file in the specific site; other sites that use the same file are not affected by these changes.
The flexibility of customization does come at a cost because changes made to files in this way are not easily replicated from one SharePoint farm to another; for example, replicating changes from development to testing and then to production. Thankfully, this customization concept is built on top of the existing SharePoint platform that developers can use to implement a much more repeatable process in rolling out changes. Developers work with files that exist at a lower level—the file system. The files on the file system are the templates that the instances in the SharePoint site's content database point to. File instances in the content database that are not customized are called uncustomized files; the source of the file for an uncustomized instance is pulled from the file on the file system. These same files can be packaged and pushed to different SharePoint environments.
For more information about customized and uncustomized files, see Understanding and Creating Customized and Uncustomized Files in Windows SharePoint Services 3.0.
Two Approaches to SharePoint Project Implementations
When you begin to create a Windows SharePoint Services 3.0 site or publishing site, you can implement the site in one of two ways: through SharePoint customization or through SharePoint development.
Note
Neither process outlined in this article is a "right" or "wrong" approach; these approaches to implementing publishing sites simply differ. Consider the advantages and disadvantages of each approach before starting your next publishing site project. Weigh all the external factors, such as the experience of the individuals on the implementation team, the demands of the project, the budget, and the available time to help guide your selection of the implementation process that is best suited for your project.
SharePoint Customization
One approach to implementing a SharePoint project is called SharePoint customization. This approach is based on the fact that all changes made to a SharePoint site reside exclusively in the site collection's content database. SharePoint customization involves the use of tools that make changes to sites by way of the SharePoint API, such as the SharePoint browser interface and Microsoft Office SharePoint Designer 2007. SharePoint customization has advantages and disadvantages:
Advantages: Many resources are available to demonstrate SharePoint customization, and it is generally the easiest way to make structural changes because the tools provide more of a WYSIWYG environment and instant feedback on the changes. Tools such as Office SharePoint Designer and the browser interface provide a visual designer, and enforce all the necessary business rules, resulting in a faster implementation.
Disadvantages: Because all the changes are stored in the content database, the SharePoint customization approach can make it a challenge to replicate changes to items such as master pages or page layouts across multiple SharePoint farms, to all individuals on a project team, across a central development or build environment, to a test or staging environment, or to a production environment.
SharePoint Development
You can also implement SharePoint projects through SharePoint development. Unlike the customization approach, SharePoint development aims to keep files uncustomized, which makes it easier to facilitate a change control process for master pages and page layouts because uncustomized files can be packaged very easily into SharePoint solution packages (*.wsp files) and deployed to different environments.
Advantages: By keeping files uncustomized on servers running Office SharePoint Server, you achieve easier management and maintenance of file updates. You also have support for keeping files in a source control solution because the files ultimately live on the file system, and not in the content database. Deployment is easier because of the ability to use SharePoint solution packages, just as it is easier to install applications by using Windows Installer (.msi) files.
Disadvantages: Working with files at the file system level creates some extra work because all files used in a SharePoint site must be in the site's virtual file system, which is kept in the content database. To add files to a site's virtual file system, you must provision an uncustomized instance of the file to the content database. You provision files in a SharePoint site by using SharePoint Features. Therefore, you must create the master pages and page layouts, and you must also create the Features that provision the files into the site.
SharePoint development requires some additional work to keep files uncustomized on the SharePoint servers, but it offers the following:
Easier ongoing management and maintenance of file updates
Support for keeping files in a source control solution, because they ultimately live on the file system and not in the content database
Easier deployment of changes because of SharePoint solution packages
Creating Master Pages for SharePoint Publishing Sites
Creating master pages in SharePoint publishing sites is similar to creating them for ASP.NET 2.0 sites, but there is one fundamental difference: where you save the master pages. In an ASP.NET 2.0 site, master pages reside on the file system. However, in a SharePoint site, they are located in the Master Page Gallery in the top-level site of a site collection. You can get them into the Master Page Gallery in one of two ways:
Use SharePoint customization. Use Office SharePoint Designer to create the master page, and save it directly to the Master Page Gallery.
Use SharePoint development. Create the master page and save it on the file system of the server, and then use a SharePoint Feature to provision the uncustomized instance into the Master Page Gallery.
Creating Master Pages: The Customization Approach
How to begin the customization approach is described in the following procedure.
To create a master page by using customization
Open an existing publishing site in Office SharePoint Designer (on the File menu, click Open Site).
On the File menu, click New to create a master page.
In the New dialog box on the Page tab, click ASP.NET in the first column, click Master Page in the middle column, and then click OK (see Figure 1).
Figure 1. Creating master pages in Office SharePoint Designer 2007
.jpg "Creating master pages in SharePoint Designer")
Office SharePoint Designer creates a blank master page, but without any of the controls required for use in a SharePoint site. Required controls include the following:
Special SharePoint controls that inject the CSS files for branding
A minimal number of content placeholders that are used by Office SharePoint Server
The Web Part Manager that facilitates the use of Web Parts on pages
The controls that add the Site Actions menu and the publishing site's Page Editing toolbar.
From this point, you can proceed in one of the following ways:
Look at the controls in one of the provided publishing site master pages, for example, BlueBand.master, and use it as a baseline for the requirements of your new master page.
Find a minimal master page, which contains only the required core controls, and use it. A minimal master page is available in the Microsoft Office SharePoint Server 2007 SDK (for information about using minimal master pages, see How to: Create a Minimal Master Page). However, many people in the SharePoint community also create minimal master pages and post them on their blogs or on sites such as CodePlex or MSDN Code Gallery.
After you add all the controls and branding you need to your new master page, it is still checked out and unpublished. This is usually okay in a limited development environment where only one person has access to the site. But if the master page is created in an environment that many people can access, it should be checked in and published, and the publishing request should be approved. If these steps are not taken and the site (and all of its pages) is configured to use the new master page, users of the site receive a run-time error. This is because the page is not published and users do not have the necessary permissions to access the master page used by all pages on the site.
Note
Master pages that you create with SharePoint Designer are stored only within the SharePoint site’s content database.
Creating Master Pages: The Development Approach
The development approach differs significantly from the customization approach because you do not use SharePoint Designer. You first create the master page in a text editor or an integrated development environment (IDE) such as Microsoft Visual Studio. Unfortunately, the current versions of Visual Studio do not interact with SharePoint Server in the way SharePoint Designer does, and therefore there is no design-time preview. Visual Studio provides only the code or markup view.
The basics of the approach are to create the master page, and then to create a SharePoint Feature that you use to provision the master page. Because Features are essentially folders, XML files, and other resources they might use such as images, you can create them in many ways. Visual Studio can make it easier to create Features, however, because it provides IntelliSense for the SharePoint XML files, also known as Collaborative Application Markup Language (CAML) files, and helps you to organize the project.
Note
For more information about enabling IntelliSense for SharePoint CAML files, see the visual how-to Configuring IntelliSense with CAML Files When Developing for Windows SharePoint Services 3.0.
To create a Feature
Create a folder in the [..]\12\TEMPLATE\FEATURES folder that contains a Feature definition file (feature.xml) and element manifest file (elements.xml).
Configure the Feature definition file to be a site collection Feature, as shown in the following code.
Feature definition (feature.xml)
<?xml version="1.0" encoding="utf-8" ?> <Feature xmlns="https://schemas.microsoft.com/sharepoint/" Id="1D464A55-2456-4974-A584-01843989F70C" Title="MSDN: SharePoint Development" Scope="Site" Hidden="FALSE" Version="1.0.0.0"> <ElementManifests> <ElementManifest Location="masterPage.xml" /> <ElementFile Location="sample.master" /> </ElementManifests> </Feature>Add the following markup to the element manifest file.
Element manifest (elements.xml)
<?xml version="1.0" encoding="utf-8" ?> <Elements xmlns="https://schemas.microsoft.com/sharepoint/"> <!-- add master page(s) --> <Module Url="_catalogs/masterpage" RootWebOnly="TRUE"> <File Url="sample.master" IgnoreIfAlreadyExists="TRUE" Type="GhostableInLibrary"> <Property Name="ContentType" Value="$Resources:cmscore,contenttype_masterpage_name;" /> <Property Name="PublishingPreviewImage" Value="~SiteCollection/_catalogs/masterpage/Preview Images /MSDN/preview.gif, ~SiteCollection/_catalogs/masterpage/Preview Images /MSDN/preview.gif" /> <Property Name="Title" Value="Sample master page" /> <Property Name="MasterPageDescription" Value="Sample master page description." /> </File> </Module> <!-- add preview image --> <Module Url="_catalogs/masterpage/Preview Images/MSDN" RootWebOnly="TRUE"> <File Url="preview.gif" IgnoreIfAlreadyExists="TRUE" Type="GhostableInLibrary"> <Property Name="Title" Value="Sample preview image" /> <Property Name="MasterPageDescription" Value="Sample preview image" /> </File> </Module> </Elements>
You should notice a few things in the XML in the previous element manifest file. First, the Type attribute in the <File> node is set to GhostableInLibrary.
<File Url="sample.master" IgnoreIfAlreadyExists="TRUE" Type="GhostableInLibrary">
This tells SharePoint Server to provision an uncustomized instance of the file into the site collection, but at the same time, to record this file as being part of a document library or, in this case, the Master Page Gallery. The next thing to notice is the properties added to the file when it is provisioned.
The master page is added by using a specific content type given a title, a description, and a preview image.
<Property Name="ContentType"Value="$Resources:cmscore,contenttype_masterpage_name;" />
<Property Name="PublishingPreviewImage"
Value="~SiteCollection/_catalogs/masterpage/Preview Images
/MSDN/preview.gif, ~SiteCollection/_catalogs/masterpage/Preview Images/MSDN/preview.gif" />
The preview image field is a comma-delimited field composed of two values of a URL. One value is the text to display in the URL, the other is the target of the URL. This preview image is shown when someone changes the master page from Site Settings on the Master Page administration page.
At this point, the Feature should be deployed to all SharePoint servers in the farm, installed, and then activated on a site collection. The process of activating the Feature provisions an uncustomized instance of the master page into the Master Page Gallery for use in a publishing site.
Creating Page Layouts for SharePoint Publishing Sites
The process of creating page layouts for use within a publishing site is very similar to creating master pages. Similar to master pages, page layouts reside in the Master Page Gallery and can exist as either customized or uncustomized files. The primary difference from a master page is that page layouts must be associated with a content type that dictates the schema of a page.
Creating Page Layouts: The Customization Approach
Creating page layouts by using SharePoint Designer is almost identical to creating master pages. The only difference is that when creating the file, on the SharePoint Content tab in the New dialog box, select SharePoint Publishing in the first column and Page Layout in the center column. Before SharePoint Designer creates the page layout, it needs the file name, the page layout name, and the content type that is associated with this page layout (what defines the schema of the page), as shown in Figure 2.
Figure 2. Creating page layouts with SharePoint Designer
.jpg "Creating page layouts with SharePoint Designer")
After you create the file, your next step is to add all the controls required by content authors such as field controls, Web Part zones, and all the rendering controls needed to display the page. Finally, save the page layout. And just as in the case of master pages, it is a good practice to check in, publish, and approve the publishing request so others can see and use the page layout.
Creating Page Layouts: The Development Approach
As with the customization approach, the process of creating page layouts by using the development approach is almost identical to creating master pages. The only difference is that, with page layouts, you must tell SharePoint Server which content type the page layout is associated with.
Create another Feature (or reuse the previous Feature used to provision the master page) and, within the element manifest file, add the following markup to provision the page layout.
<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
<!-- add page layout(s) -->
<Module Url="_catalogs/masterpage"
RootWebOnly="TRUE">
<File Url="sampleLayout.aspx" IgnoreIfAlreadyExists="TRUE" Type="GhostableInLibrary">
<Property Name="PublishingAssociatedContentType"
Value=";#Article Page;#0x010100C568DB52D9D0A14D9B2FDCC96666E9F2007948130EC
3DB064584E219954237AF3900242457EFB8B24247815D688C526CD44D;#" />
<Property Name="PublishingPreviewImage"
Value="~SiteCollection/_catalogs/masterpage/Preview Images
/MSDN/sample.gif, ~SiteCollection/_catalogs/masterpage/Preview Images/MSDN/sample.gif" />
<Property Name="ContentType"
Value="$Resources:cmscore,contenttype_pagelayout_name;" />
<Property Name="Title"
Value="Sample page layout" />
<Property Name="MasterPageDescription"
Value="Sample page layout description." />
</File>
</Module>
<!-- add preview image -->
<Module Url="_catalogs/masterpage/Preview Images/StructuredDev"
Path="LayoutFiles"
RootWebOnly="TRUE">
<File Url="preview.gif" IgnoreIfAlreadyExists="TRUE" Type="GhostableInLibrary">
<Property Name="Title"
Value="Sample preview image" />
<Property Name="MasterPageDescription"
Value="Sample preview image" />
</File>
</Module>
</Elements>
Element manifest (elements.xml)
As the previous page layout markup shows, the only difference between provisioning a master page and a page layout is that page layouts have an additional property named PublishingAssociatedContentType.
<Property Name="PublishingAssociatedContentType"
Value=";#Article Page;#0x010100C568DB52D9D0A14D9B2FDCC96666E9F2007948130EC
3DB064584E219954237AF3900242457EFB8B24247815D688C526CD44D;#" />
This property is a delimited list of two values. The first value is the name of the content type that the page layout is associated with, and the second value is the same content type's identifier. These two values are separated by and surrounded by the delimiter of ;#.
Summarizing Pros and Cons of the Customization and Development Approaches
It is possible to combine and mix the customization and development approaches when creating and implementing master pages and page layouts.
When evaluating the two SharePoint implementation options, you might find the SharePoint development approach more appealing because of the benefits it offers you, such as the ability to leverage source control, to more easily adhere to change management processes, and to make the deployment story more repeatable and reliable. The primary issue is that it requires more work: You must create Features and there is no integrated design-time experience.
If you choose to go with the SharePoint development approach instead of the customization approach, you have some options. First, the Visual Studio extensions for Windows SharePoint Services 3.0 assist in the creation of SharePoint Features and solution packages. Unfortunately, they are not designed for use with Office SharePoint Server 2007 publishing sites. However, because master pages and page layouts do not require a special SharePoint Server–only Feature schema, and instead are just files that are provisioned into the Master Page Gallery, the Visual Studio extensions for Windows SharePoint Services 3.0 can be used to ease the process. Or, you can use the community tool STSDEV on CodePlex to stub out a Visual Studio project that provisions master pages and page layouts.
Regardless of the tools or techniques used, none of the available options allow the design-time experience of creating master pages and page layouts visually in a WYSIWYG environment, wrapping them in a Feature for provisioning, and then packaging everything in a solution. Fortunately, there is another option.
Consider that the process of creating master pages and the process of creating page layouts differ, but the ultimate result is the same. Ultimately, both implementation approaches get files into the Master Page Gallery. The fact that they are customized or uncustomized instances is moot. If that is the case, then you can use SharePoint Designer to create and edit master pages and page layouts. These can be created in one SharePoint site collection that acts as a temporary workspace. The file can be saved to the file system by using SharePoint Designer. Then, the resulting files can be provisioned into a different site collection by using a Feature. This allows developers and designers to take advantage of a WYSIWYG environment, SharePoint Designer, to quickly create and view their master pages and page layouts and still get the advantages of the development approach. In effect, you create a customized version of your files and then "Feature-ize" everything.
Conclusion
This article addresses two options that are available to SharePoint developers and designers to create master pages for SharePoint sites, and to create page layouts for Office SharePoint Server 2007 publishing sites. To fully understand the differences between the two options, you need a firm grasp of the virtualized file system that SharePoint Server relies upon. Prepared with this knowledge, you can then make an educated decision and weigh the advantages and disadvantages of the method you select to create and deploy custom master pages and page layouts. SharePoint customization may be the easier and faster option, but it can add complexity in an environment with multiple SharePoint farms. SharePoint development simplifies the deployment story, but it also requires additional work that SharePoint customization does not require. Neither approach is the right or wrong choice for a project. They each have different advantages and disadvantages that you should consider on a project-by-project basis.
Additional Resources
For more information, see the following resources: