Incorporating a Master Page into a SharePoint site definition

Introduction

This is the sixth article in a six-part series on ASP.NET Master Pages and SharePoint.

1. Introduction to Master Pages.
2. Examining the out of the box Master Pages in SharePoint.
3. Developing a custom Master Page for SharePoint.
4. Deploy a Master Page for a production ready system.
5. Customizing the Application.master Page.
6. Incorporating a Master Page into a SharePoint site definition

In the previous article of this series we discussed how to build a customized master page and deploy it with a feature. However, the manual process of deploying the feature to each server in the farm and activating it isn’t as seamless as most developers would like. It would be nice to have the features automatically activate themselves when a new site in SharePoint is created from a template.

This article will discuss the creation of SharePoint site definitions, which are templates for SharePoint sites that will automatically create the master page feature on the site when created.

Site Definition

Site Definitions are templates that developers can build in SharePoint. You might also hear the term Site Template in SharePoint, which is a customization of a Site Definition. In order to clear up any confusion on these two terms, you can just think of them like this:

Site Definitions – SharePoint template that developers can create to manipulate how a site should be created. These are stored in the 12 hive of SharePoint and are referenced during site creation.

Site Templates – Customization of a Site Definition that administrators of the SharePoint site can create from the UI screens. These are stored in the content database and these are not meant for developers to manipulate.

When you create a SharePoint site and use one of the out of the box templates, you are actually using a Site Definition that Microsoft created and shipped with the SharePoint product. For more information about how SharePoint constructs the out of the box Site Definitions, please refer to the second article in this series: Examining the out of the box Master Pages in SharePoint .

WSP Solutions

In the fourth article of this series: Deploy a Master Page for a production ready system , we discussed the manual process of creating a feature, placing it in the 12 hive and deploying it with stsadm commands. While that is a valid process to deploy to SharePoint, it is a very manual process. Also, we are now bringing another factor into our project (i.e.: the Site Definition). So, we could manually deploy the site definition in addition to the feature, but now we are starting to have a lot of manual steps. Plus, if we have a large SharePoint farm, we are going to have to repeat these steps on each server.

Thus, SharePoint created a way to incorporate all your features, site definitions, etc… into one deployable solution. These solutions are called WSP files. WSP files are basically CAB files with an extension SharePoint understands so it can deploy to a SharePoint farm. These solutions automatically get deployed to all appropriate servers in the farm. Thus, you only have to install the WSP against the SharePoint web application in order to install all your features, site definitions, etc…

What are we showing in this article?

In this article we are going to show how to create a Feature, Site Definition and WSP solution.

The Feature will deploy the master page to the master page gallery of our site, just like in article four of this series: Deploy a Master Page for a production ready system.

The Site Definition will create the template for our site. This template tells SharePoint which aspx pages to create, which web zones to create, what features to activate, etc…

Lastly, the WSP solution will wrap everything up into one deployable package.

One question that undoubtedly comes up is “why are you incorporating the feature into the site definition instead of using feature stapling?”  Feature stapling is the process of creating features and stapling them to Site Definitions that already exist. For example: let’s say you created a web part in a feature and you wanted that feature to be activated on all sites created with the WSS team site definition that comes out of the box in SharePoint. However, you want to keep all the other parts of that site definition intact, all you want to do is add one more feature onto it. With feature stapling you can create a feature and tell it to attach itself to pre-existing site definitions (even the ones that come out of the box in SharePoint).

The decision to use feature stapling versus custom site definitions has to deal with the amount of customizations you need to make. There might be times when you want to use feature stapling instead of brand new site definitions. However, in a lot of cases you need to make changes that go above and beyond just the features in a site definition. Thus, it is good to create custom site definitions to manipulate these functionalities. Plus, custom site definitions activate the features when the site collection is getting created, while feature stapling activates the features after the site has been created. This timing is important to understand in some complicated situations.

So, for this particular demo I am going to activate my master page feature in a custom site definition to show the process. But, I am not saying this is the best way. If you already have a site created and just need to deploy the master page feature, you might want to look into feature stapling as an option.

What tools are we going to use?

One of the more difficult things to understand when you first learn how to create WSP solutions is the install files that are needed to build the WSP solution. These files are called the manifest and the ddf files. These files basically explain to SharePoint what features, site definitions, etc… is part of your solution so that SharePoint can install the solution to the web application.

Since these files are difficult to understand, there are a lot of third party tools available that will build the manifest and ddf files for you. These tools are usually extensions to Visual Studio. Microsoft built one called Visual Studio Extensions for WSS. Plus, there are many open source ones on CodePlex including STSDEV, SPBuilder, WSPBuilder, etc… Each of these tools provides a different approach to building SharePoint solutions.

My personal favorite is WSPBuilder. The way this product works is it mimics the 12 hive in a Visual Studio solution. As long as your Visual Studio solution has the same folder structure as the 12 hive, it will build the correct files to create the WSP solution. This is very powerful and flexible. I like this over the Visual Studio Extensions for WSS because I feel that I am restricted in what I can do with Visual Studio Extensions for WSS.

The choice of the solution builder tools you want to use is a personal choice. For this article I am going to work with the WSPBuilder add-in for Visual Studio.

Here is an example of how WSPBuilder works. Notice that the servers 12 hive matches the Visual Studio solution:

Servers 12 hive

Visual Studio Solution

As long as the 12 hive matches, you can right click on your project and use the WSP Builder menu options to build your WSP file.

Also, when you are developing on a SharePoint server, you can right click on your project and use the WSPBuilder menu options to deploy your WSP file to the local server. This will deploy it to all web applications on your development machine.

Thus, when you are developing, you should be developing on a SharePoint server. Virtual machines such as VPC or VMWare are great for this. Then, every time you make a change you can just go to the deploy menu option of the WSPBuilder menu. After you are finished developing, you can build the WSP file using the menu options and it will physically place the WSP file in your projects folder. At this point you can copy that WSP file to the production machine and deploy it with stsadm commands.

Walkthrough

Create The Structure

• Start Visual Studio and choose a new WSPBuilder project.

• Create a folder structure for the solution that matches the folder structure for the SharePoint 12 hive (this is really important – WSPBuilder works on the premise that the Visual Studio solution matches the structure of the SharePoint 12 hive). For now we are just going to create the following folders:
  • Template – subfolder under 12 that holds the other subfolders
  • 1033 – holds the xml files that will tell SharePoint about our new site definitions
  • Features – holds the new features we are going to build (i.e.: lists, webparts, master pages, etc…)
  • Layouts – holds our reference files (i.e.: images, css, js, etc…)
  • Site Templates – holds our site definitions

Create a Site Definition

• Create a new site definition based off the team site definition in SharePoint.
• Copy the team site definition folder from the 12 hive:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates\sts

• • Paste the folder in the Visual Studio solutions SiteTemplates folder.
  • Rename the sts folder to something unique (DemoCompanySiteDef for this example)
  • Delete the defaultdws.aspx file because we aren’t going to use it for this example.

• • Open the default.aspx file and change the master page to a new master page. Call this custom.master (yes, I know that this is not the name of our master page. We are going to configure SharePoint to do a string replacement of custom.master with DemoCompany.master in later steps). We will create this master page in the next step.

<%@ Page language=”C#” MasterPageFile=”~masterurl/custom.master”

Modify the Onet.xml file of the Site Definition for initial preparation

• Open the Onet.xml file (located in the xml folder) and clean it up for our simple site definition.

The Onet.xml file is the file that tells SharePoint how to create the site definition. Whenever you create a new site in SharePoint it reads from the Onet.xml file to determine how to create the site. It is important to note that SharePoint is reading from the Onet.xml file when the site is being created. So, if you already have created a site, you can’t go back to the Onet.xml file, make changes, and expect it to show up on your already created sites.

• Scroll down to the Configurations XML nodes and remove 2 configurations:
  • ID=1 – Blank
  • ID-2 – DWS

Be very careful not to remove ID=0 – Default, because this is the configuration we are going to use for this site definition. When removing the other two get rid of the whole xml tag as well as everything within their xml tag.

• Scroll down to the Modules XML nodes and remove 2 modules:
  • DefaultBlank
  • DWS

Once again, be very careful not to remove the Default module because this is the module we are going to use for this site definition. When removing the other two get rid of the whole xml tag as well as everything within their xml tag.

Create the new master page feature

The master page will be created as a feature. The reason for this is that if the master page is in a feature the master page can be added to the master page gallery of SharePoint. This allows you to set out-of-the-box pages to the master page or your own custom site definitions. It also allows you to turn on or turn off the master page features on specific sites. Basically, having it in a feature (rather than directly in the site definition or in the layouts folder) gives you much more flexibility.

• Create a new folder under “FEATURES” and call it something unique for your master page. For this example we will call it DemoCompanyMasterPage.
• Create a folder under the DemoCompanyMasterPage called “MasterPages”.
  • Copy the general SharePoint master page from the 12 hive: C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\GLOBAL\default.master
  • Paste the file under the “MasterPages” folder in the Visual Studio solution.
  • Rename the file to something unique (DemoCompany.master for this example).
• Create two xml files under the DemoCompanyMasterPage folder.
  • feature.xml – this will give a unique GUID to the feature (which we will reference later). This file also gives some important information about the Scope of the feature. Lastly, this file tells SharePoint where all the other files that make up this feature lives. This file must be called feature.xml (this is because SharePoint will read all files called feature.xml from the Features folder).

<Feature Id=”95F25D4A-D256-4158-96FE-010F599149CC” Title=”Demo Master Page”
Scope=”Site” Version=”1.0.0.0″ Hidden=”FALSE” DefaultResourceFile=”core” xmlns=”http://schemas.microsoft.com/sharepoint/”
Description=”This Feature contains the demo master page”>
<ElementManifests>
<ElementManifest Location=”elements.xml” />
<ElementFile Location=”MasterPages\DemoCompany.master” />
</ElementManifests>
</Feature>

Please note that the Scope=”Site”. This is very important. This is telling SharePoint that this feature is for the site collection. If that Scope=”Web” then it would be telling SharePoint that this feature is for an individual site.

• elements.xml – this file is telling SharePoint to place the new master page into the master page gallery. This file does not have to be called elements.xml (unlike the feature file which has to be called feature.xml). It just has to match the name located in the “ElementManifest” of the feature.xml file.

<Elements xmlns=”http://schemas.microsoft.com/sharepoint/”>
<Module Name=”DemoCompanyMasterPage” Url=”_catalogs/masterpage” Path=”MasterPages” RootWebOnly=”FALSE”>
<File Url=”DemoCompany.master” Type=”GhostableInLibrary” />
</Module>
</Elements>

Modify Onet.xml file of the Site Definition

We are modifying the Onet.xml file of the Site Definition in order to tell this Site Definition to activate our Master Page feature when the site is created and to use our custom master page with the dynamic url replacement technique.

Dynamic Token URL replacement

To learn more about Dynamic URL replacement please refer to the second article in this series: Examining the out of the box SharePoint Master Pages.

• Open the onet.xml file in Visual Studio (located at SiteTemplates/DemoCompanySiteDef/xml).
• Find the xml node that says Configuration ID=0 Name=”Default”.
• Add in a reference for the new master page:

<Configuration ID=”0″ Name=”Default”                           CustomMasterUrl=”~SiteCollection/_catalogs/masterpage/DemoCompany.master”
MasterUrl=”~SiteCollection/_catalogs/masterpage/DemoCompany.master”>

Note: SharePoint will do a string replacement of any aspx page with ~masterurl/custom.master with the reference in CustomMasterUrl. And, it will replace any aspx page with ~masterurl/default.master with the reference in MasterUrl.

Activate the Feature

• Find the SiteFeatures XML node.
• Add a new Feature node in there that matches the GUID of the feature.xml file we created for our master page.

This section of the onet.xml tells the site to activate this particular feature on this particular site when it is being created. The reason it goes into the SiteFeatures (instead of the WebFeatures) is because this particular feature was scoped for a Site Collection. If the feature was scoped for an individual site then it would go in the WebFeatures.

Create the WebTemp*.xml file

WebTemp*.xml files tell SharePoint about site definitions. When a new site is being created in SharePoint the “Select Templates” list box is populated by anything it can find in the WebTemp*.xml files. There can be multiple of these files in SharePoint as long as they are in the 12/Template/1033/XML folder. SharePoint will basically read this folder for any file that starts with the word WebTemp.

• Add a new folder under 12/Template/1033 in our Visual Studio solution called XML.
• Add a new file to the 12/Template/1033/XML folder in our Visual Studio solution. This file must start with WebTemp. We will call this file WebTempDemoCompany.xml.

• Add in the proper xml to tell SharePoint about our new site definition

<Templates xmlns:ows=”Microsoft SharePoint”>
<Template Name=”DemoCompanySiteDef” ID=”10051″>
<Configuration ID=”0″ Title=”Demo Company Site”
Hidden=”FALSE”                                                                                                         ImageUrl=”/_layouts/images/stsprev.png”
Description=”A site for the Demo Company”
DisplayCategory=”Demo Company” >
</Configuration>
</Template>
</Templates>

A few things to note:

• The “Name” must match the site definition folder exactly. We used the name DemoCompanySiteDef. This matches our site definition name exactly.
• The Configuration ID must match the configuration ID in our onet.xml file of our Site Definition. We used configuration id 0.
• The display category will create a new tab on the new site screen in SharePoint.
• The ID has to be unique and SharePoint has already reserved certain IDs. To be safe use an ID over 10000 and make sure it is unique.

Use WSP Builder to build and deploy the solution

Now, at this point (in a regular SharePoint solution) we would create manifest.xml and ddf files. These are files SharePoint needs to install the solution properly. However, since we are using WSPBuilder, it will do that for us.

• Right click the project and click WSPBuilder – Build

• Verify your Web Application is created on your local SharePoint environment. Note: the Site Collection should not be created at this point, just the Web Application. And, you only need to do this once.
• If the build is successful, right click the project and click WSPBuilder – Deploy.

This is needed because the build command in WSPBuilder just builds a wsp file. This file can be sent to other machines and you can use stsadm scripts to install it on other SharePoint farms. However, in development, we need a quick way to deploy it to the current SharePoint farm. The WSPBuilder – Deploy command will deploy the wsp file on all the Web Applications in the local SharePoint farm.

Use the Site Definition

Open up SharePoint Central Administration and create a new Site Collection with the site definition we just created.

Now you can go back and modify the master page or default.aspx page as you wish. Just be careful not to mess with the ContentPlaceHolders too much. SharePoint reserve these for certain actions on some of its internal pages. After every change you make you can rebuild by clicking WSPBuilder – Build and update the solution by clicking WSPBuilder – Deploy. Then you can just go to the website and see your changes. Just be aware that everytime you deploy WSPBuilder does an app pool recycle (to ensure the changes get pushed out through IIS), so you might have to wait a few seconds to see your changes (during that few seconds the site could say Service Unavailable).

It is also important to note that the first time you deploy with WSPBuilder it does a true SharePoint install. However, every subsequent time it does a SharePoint solution update. Solution updates work for most changes, however, there are some things it can’t do. So, if you run into errors it is sometimes good to do WSPBuilder – Uninstall and then WSPBuilder-Deploy to do a real install in certain situations when you are making changes.

If you are curious to what a SharePoint solution is doing, then just check out the files in the 12 hive:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12

You will notice that all the files we created in our Visual Studio solution have been “pushed” down to the folders in the 12 hive. The WSP knows to “push” these files there. The WSP also knows to tell SharePoint that these files exist. This is exactly how SharePoint develops it’s out of the box site definitions.

Side Notes:

1. Any file you place in the Layouts folder can be reference in the aspx pages as “/_layouts/{filename}”. I usually recommend placing another folder under Layouts in the Visual Studio solution (just because it makes it easy to find later – you can call this folder the name of your company or the name of your project or anything that is obvious that it contains your custom reference files). Then you can reference everything in there by “/_layouts/{folder}/{filename}”. An example of this is css files in the master page. This is possible because SharePoint sets an IIS path up to the Layouts folder in the 12 hive and calls it _layouts.

2. If you want to create a custom webpart with WSPBuilder just click Add – new item… WSPBuilder – WebPartFeature. This will create the feature folder, for your webpart, and the .cs class for your webpart. This way you can go directly into coding and not have to worry about the Feature creation. Once you are done coding the webpart just make sure it is in the appropriate scope of your onet.xml file (SiteFeatures or WebFeatures) and it will become available to you in your webpart gallery. Then all you have to do is worry about your dll being installed in the Bin or GAC. If you choose GAC I recommend post-build scripts to move it.

3. Do not remove Content Place Holders from your master page if you start doing customizations. The reason for this is if you assign other files in SharePoint (such as list pages) to use your master pages, they will assume certain Content Place Holders exist. If they are not there, your site will just break.