Introduction

This is the fourth 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 in SharePoint Designer. At the end of the previous article we discussed that making the modifications directly in SharePoint Designer is not the most deployable solution for production life cycle environments.

This article will discuss the other option to customize and deploy a master page for a production ready system.

Features

Features are SharePoint’s way to activate and deactivate certain code on particular site and/or site collection, within a SharePoint website. Features can contain things like - what webparts should be available, what lists should be available, what actions should be on list menus, etc…

Features can also deploy master pages to the master page gallery of a SharePoint site and/or site collection. Using a feature to deploy the master pages gives us reusable files that can be deployed to any SharePoint environment through SharePoint commands. This means that we can create build scripts to deploy our master page to a master page gallery. This is much better than the copy and paste method of SharePoint Designer we showed in the previous article.

Features contain two main files:

1. Feature.xml -When a feature is installed SharePoint looks for the feature.xml file to determine how to deploy the feature. The feature.xml file defines the feature and provides the paths to the other files involved in deploying the feature.
2. Elements Manifest - this file is referred to from the feature.xml. This is the file that determines what the feature should do when it is activated.

Features can be installed to a SharePoint environment through stsadm commands. Stsadm is the command line tool for SharePoint and is used for multiple administrative and development operations in SharePoint.

Once a feature is installed on a SharePoint machine, it can be activate or deactivated on a particular SharePoint site or site collection. Every feature.xml file contains a “Scope” attribute. If the scope of a feature is “Web”, that means that the feature can only be activated at the SharePoint site level. If the scope of a feature is “Site”, that means the feature can only be activated at the SharePoint site collection level. Site Collections contain all the sites in a SharePoint tree, thus if a feature is activated at a site collection, it is activated for all the sites in the site collection. If a feature is activated at a site, it is activated for that site only.

To activate a feature you can go to a site and/or site collection and then go to the Site Settings. In the site settings you will see a link for “Site features”. If you are on a top level site in the site collection, you will also see a link for “Site collection features”.

When you click on the “Site features” and/or “Site collection features” link you will go to the feature activation page for the site and/or site collection respectively. From this page you can activate or deactivate sites for the site and/or site collection.

Custom Master Page file

To customize a SharePoint master page with a feature, you need to create a custom master page file. This file gets uploaded to the master page gallery in SharePoint through the feature.

There are multiple ways to create your own master page files. Here are a few techniques I recommend:

1. Copy Technique:
   • Copy the default.master from %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\Global.
   • Make your changes directly to the html (in the copied file).
   • Make sure the copy file has a different name than default.master.
2. Designer Technique
   • Make your changes in SharePoint designer as described in the previous article: http://sharepointmagazine.net/technical/customisation/developing-a-custom-master-page-master-pages-and-sharepoint-part-3-of-6.
   • Do not save these changes against your site - you can do this against a test site to make things easier.
   • Copy the html out into a custom master file and give it a unique name.
3. Minimal Master technique
   • Make a master page file with the minimal master html code found here: http://msdn.microsoft.com/en-us/library/aa660698.aspx
   • The minimal master html is a master page with all the content place holders that you will need for SharePoint. This is a good starting point if you want to start from scratch in creating your master page. You should become familiar with what all the content place holders are for when using this technique.
   • Save this file as a new master file and give it a unique name.

Create the Feature

Features are created in Visual Studio and then moved into the SharePoint 12 hive %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES. After the feature is in the 12 hive, stsadm commands can be used to deploy the feature to the SharePoint environment. Then the feature needs to be activated on the SharePoint site.

Steps to create a feature for Master Page deployment:

Note: We will not be using any tools like Visual Studio Extensions for WSS or WSPBuilder for this walkthrough. However, I recommend using these tools to wrap the features in solutions. We will talk more about this in the last article in this series.

1. Open Visual Studio
2. Create a New Project
3. Choose a Class Library project (for this walkthrough I am referring to a C# class library, but the steps are the same for other types)
4. Call it DemoMasterPageFeature
5. Delete Class1.cs
6. Add a new folder to the project and call the folder “12″
7. Add a new folder to the “12″ folder, call it “Template”
8. Add a new folder to the “Template” folder, call it “Features”
9. Add a new folder to the “Features” folder, call it “DemoMasterPage”
10. Add a new folder to the “DemoMasterPage” folder, call it “MasterPages”
11. Add a new master page file to the MasterPages folder
    • There are multiple ways to create this file
      • You can copy the one from SharePoint
      • You can copy a modified one out of SharePoint Designer. If you have been following this series you can go to article 3 {insert link here} and use the html we modified in SharePoint Designer for your new master page file.
      • You can start with a minimal master page http://msdn.microsoft.com/en-us/library/aa660698.aspx
    • We are going to use the technique of copying the one from SharePoint
      • Go to %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\Global.
      • Copy the default.master
      • Paste it in the MasterPages folder (in the Visual Studio project)
    • Rename the file demomasterpage.master
12. Add a feature.xml file to the DemoMasterPage folder.
    • This file tells SharePoint how to install the master page
    • It must be called “feature.xml”
    • Put the following xml in it

    <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\demomasterpage.master” />
    </ElementManifests>
    </Feature>

    • Notice the following:
      • Scope - this tells SharePoint where to install the feature. Our scope is “site”, thus we want to install the feature at the site collection level. This is because our master page gallery lives at the site collection level. If we wanted to install the feature at the sub-web level, it would say “web”
      • ElementManifest - this tells SharePoint the other files involved in creating this feature. Remember, SharePoint only knows to look at the feature.xml file when installing a feature, so the feature.xml file must tell SharePoint about the other files involved.
      • Id - this is the unique GUID for the feature. It must be unique. So, if you create multiple features, make sure you use a unique GUID here. This is also how we can reference the feature when we start building solutions.
13. Add an elements.xml file to the DemoMasterPage folder
    • This file tells SharePoint what to do with this feature. For example: we want to deploy our master page to the master page gallery. This is the file that will tell SharePoint to do that.
    • It doesn’t have to be called elements.xml. But, it does have to be called whatever you put as the ElementManifest Location in the feature.xml file. I like to use elements.xml when I create these files
    • Put the following xml in it

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

    • Notice the following:
      • Url - this is how we tell SharePoint to put the file in the master page gallery. _catalogs/masterpage is the location of the master page gallery when dealing with site collections. We know we are dealing with site collections because the feature.xml file has a scope of “site”.
      • File - this tells SharePoint the name of the file it is going to put at the master page gallery. The type is “GhostableInLibrary” - this means the file is still going to be on the 12 hive and SharePoint is going to keep a Ghosted reference to the file. Please refer to article 3 http://sharepointmagazine.net/technical/customisation/developing-a-custom-master-page-master-pages-and-sharepoint-part-3-of-6 for more information about Ghosting.
14. Build the project in order to save your changes.

The final folder/file structure should look like this:

Deploying the Feature

There are 2 steps to deploy a feature:

1. Copy the contents to the 12 hive.
   • Copy the folder “DemoMasterPage” (this is the folder we created in the Visual Studio solution in the last section). Be careful to only copy the “DemoMasterPage” folder, not all the folders we created.

   
   Also, you probably won’t be able to copy from Visual Studio. So, go to windows explorer to do the copy of the folder.

   • Paste the “DemoMasterPage” folder in %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES.
2. Run stsadm commands to install the feature
   • Open up a command prompt
   • Enter the following: cd C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN.
     Note: this assumes you installed SharePoint on your C drive. Please change the install path if otherwise.
   • Enter the following: stsadm -o installfeature -name DemoMasterPage -force
     Note: do not copy and paste. Sometimes copy and paste into command lines won’t work. Please retype in your command line
   • Enter the following: stsadm -o activatefeature -name DemoMasterPage -url http://mysitecollectionpath -force
     Note: do not copy and paste. Sometimes copy and paste into command lines won’t work. Please retype in your command line
     • The string after “name” is the name of feature of your feature folder.
     • The url is the url to your site collection root. You can copy it from your browser, but don’t keep the “default.aspx” on the path

What’s wrong with this picture?

Any developer will say this is not correct. Developers don’t want to copy files manually and paste them in a folder. Yes, I understand this. I am showing this technique to lead up to the last article in this series on solution deployment. The solution will take care of moving the files to the 12 hive and running the commands for you. However, it is important to understand what solutions do before jumping right into them. Thus, I am showing you this manual way so you can get an idea of what the solution is doing behind the scenes.

Set the new master page

The feature we just created placed the new master page in the master page gallery. However, it did not tell SharePoint to use this new master page on your SharePoint site. There are multiple ways to do this including: custom site definitions, programmatically setting the default master page, using SharePoint Designer, or using the MOSS master page selection page.

If you are using WSS, please refer to article 3 in this series http://sharepointmagazine.net/technical/customisation/developing-a-custom-master-page-master-pages-and-sharepoint-part-3-of-6 in order to see how to set the master page in SharePoint designer.

If you are using MOSS, you can go to your site collection and then go to site settings. Then under “Look and Feel” click on the “Master Page” link. You can now choose the demomasterpage.master to be the master page for your site collection.

Making Changes to the Master Page

Now the Master Page has been installed to the SharePoint farm and activated on the site collection. So, what if you want to make further customizations to the master page? Do you have to go through the process of re-installing and re-activating? The answer is no. Here comes the power of ghosting. Please refer to article 3 http://sharepointmagazine.net/technical/customisation/developing-a-custom-master-page-master-pages-and-sharepoint-part-3-of-6 for more information about Ghosting. Since the master page is ghosted, the SharePoint site keeps a reference to the 12 hive version of it. So, if you want to make a change to your master page, all you have to do is update the demomasterpage.master file in the feature folder of the 12 hive (%Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEA)TURES.

Deactivating the Feature

Sometimes there are changes you need to make to a feature that are not ghosted. Examples of these types of changes are things in the feature.xml file. You cannot change the id of a feature.xml file and expect to be able to just re-install and re-activate the feature. Instead, you have to deactivate the feature and uninstall the feature first. Here are the commands to do this.

1. Open up a command prompt
2. Enter the following: cd C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN.
   Note: this assumes you installed SharePoint on your C drive. Please change the install path if otherwise.
3. Enter the following: stsadm -o deactivatefeature -name DemoMasterPage -url http://mysitecollecitonpath -force
   Note: do not copy and paste. Sometimes copy and paste into command lines won’t work. Please retype in your command line
4. Enter the following: stsadm -o uninstallfeature -name DemoMasterPage -force
   Note: do not copy and paste. Sometimes copy and paste into command lines won’t work. Please retype in your command line

Conclusion

Using features to deploy the master page to the master page gallery is a reusable way to deploy master pages in SharePoint. However, there are still manual processes involved (including copying files to the 12 hive). Thus, using features is not the complete story when dealing with SharePoint deployments. In the last article in this series we will discuss SharePoint solutions (WSPs). WSPs are basically CAB files that wrap up features in SharePoint for easy deployment. The WSP file will move the feature files to the 12 hive for you. However, I think it is important to understand how this is done before jumping into creating WSP solutions. Plus, we can reuse the feature we created in this article when we build the WSP solution out in the final article of this series.