Building Master Pages for Windows SharePoint Services 3.0 using Site Definitions in Visual Studio 2005

Applies to:  Windows SharePoint Services 3.0, Microsoft Visual Studio 2005

Joel Krist, iSoftStone

August 2007

The Visual Studio 2005 extensions for Windows SharePoint Services 3.0 provide new support for creating SharePoint applications. The tools significantly simplify the process of creating SharePoint site definitions, with Microsoft Visual Studio 2005 automating the creation of the necessary content, configuration, and deployment files. This Office Visual How To illustrates how to build a Windows SharePoint Services 3.0 site definition and add a custom master page to the definition by using Visual Studio 2005 and Visual Studio 2005 extensions for Windows SharePoint Services 3.0.

Watch the Video

Length: 6:55 | Size: 7.44 MB | Type: WMV

Code It | Read It | Explore It

Code It

To illustrate how to build a SharePoint site definition with a custom master page, this section walks through five key steps:

  1. Creating a SharePoint Team Site Definition project in Visual Studio.

  2. Adding a custom master page to the site definition project.

  3. Editing the custom master page.

  4. Editing the site definition's onet.xml file to use the custom master page.

  5. Building and deploying the site definition to a SharePoint site.

Create a Team Site Definition Project in Visual Studio 2005

Begin by creating a Team Site Definition project in Visual Studio 2005.

To create a SharePoint Team Site Definition project

  1. Start Visual Studio.

  2. On the File menu, click New, and then click Project. The New Project dialog box appears.

  3. In the Project types pane, click Visual C#, and then select the SharePoint category.

  4. In the Templates pane, select Team Site Definition. Specify a Name and Location for the project, and click OK. Visual Studio creates the project and opens the generated onet.xml file.

Add a Custom Master Page to the Site Definition

If the default.master page already meets most needs and only a few changes are required, a good option for creating a new master page is to copy default.master and then modify the copy. This is the approach illustrated by this Visual How To.

By default, the default.master page is located in the following folder on the drive to which Windows SharePoint Services 3.0 was installed:

drive:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\GLOBAL

To add a copy of the default.master file to the project

  1. Copy the default.master file into the Site Definition folder under the site definition project folder that was created by Visual Studio. (The Site Definition folder contains the default.aspx and onet.xml files generated by Visual Studio.)

  2. Rename the copy of the master page to mydefault.master.

  3. In Visual Studio, click the Project menu, and then click Add Existing Item. Visual Studio displays the Add Existing Item dialog box.

  4. Navigate to the Site Definition folder that contains the mydefault.master file. In the Files of type list, select All Files (*.*). Select the mydefault.master file, and then click Add.

Edit the Custom Master Page

After you add the new master page to the project, you can customize it in Visual Studio. Open the master page from the Visual Studio Solution Explorer, and edit the page to make the needed changes. Save the changes to the master page.

Important

When editing the master page, be careful not to delete any of the ContentPlaceHolder controls that are on the page by default. They are required for the collaboration features of Windows SharePoint Services 3.0, such as SharePoint lists and libraries. Deleting those controls can break other SharePoint pages that rely on the presence of the named content regions.

Edit the Site Definition's onet.xml File

When Visual Studio created the Team Site Definition project, it generated a default onet.xml file that was configured to use the site and system defaults for master pages. You need to change the onet.xml file to use the custom master page.

To edit the onet.xml file to use the custom master page for the site definition

  1. In the Visual Studio Solution Explorer, open the onet.xml file. Figure 1 shows the changes you make in the following steps.

    Figure 1. Editing the onet.xml file

  2. Locate the Configuration element that has an ID of "0" and add the following attributes:

    CustomMasterUrl="_catalogs/masterpage/mydefault.master"
    MasterUrl="_catalogs/masterpage/mydefault.master"
    
  3. Windows SharePoint Services defines two types of master pages: the System Master Page and the Site Master Page. Forms and views pages use the System Master Page; publishing pages use the Site Master Page. The CustomMasterUrl attribute tells Windows SharePoint Services which page to use for the Site Master Page. The MasterUrl attribute tells Windows SharePoint Services which page to use for the System Master Page.

  4. Locate the Modules child element within the Configuration element and add the following Module element:

    <Module Name="MyDefaultMaster" />
    
  5. Locate the Modules element outside the Configuration element and add the following Module and File elements:

    <Module Name="MyDefaultMaster" Url="_catalogs/masterpage">
        <File Url="mydefault.master" Type="GhostableInLibrary" />
    </Module>
    
  6. Save the changes to the onet.xml file.

Building and Deploying the Site Definition

At this point the site definition project is ready to be built and deployed.

To build and deploy the site definition project

  • In Visual Studio, click Build, and then click Deploy Solution. Visual Studio builds the assembly for the site definition and generates the necessary configuration files for deployment of the solution. It then deploys the solution to the SharePoint site.

You can test the new site definition by creating a new SharePoint site that is based on the site definition. All pages on the site will use the custom master page.

Read It

This article illustrated how to build SharePoint Services 3.0 site definitions with a custom master page using Microsoft Visual Studio 2005 with Extensions for Windows SharePoint Services 3.0. The key steps include:

  1. Creating a SharePoint Team Site Definition project in Visual Studio.

  2. Adding a custom master page to the site definition project.

  3. Editing the custom master page.

  4. Editing the site definition's onet.xml file to use the custom master page.

  5. Building and deploying the site definition to a SharePoint site.

Explore It

For additional information, see the following resources: