A former student brought an excellent BLOG post that Heather Solomon made last October (http://www.heathersolomon.com/blog/articles/servermstpageforsitecollect_feature.aspx) to my attention recently. Heather demonstrated how to create a Feature that could be used to install a Custom Master Page for a Site Collection. There was however one limitation to the approach that Heather used, it could only be used on a Site where the Publishing Feature was enabled. My student wondered if there was a way to do something similar for regular WSS Team Sites.
Normally, I teach students how to do this by planning ahead and creating or modifying Site Definitions BEFORE you create the Site Collection and Top Level Site. The MasterUrl and CustomMasterUrl attributes represent two replaceable parameters that can be used to set the Masterpage attribute of the @Page declaration on the pages of a SharePoint site. “Out of the Box“ .aspx pages point to a Masterpage at ~/masterurl/default.master. This will be replaced at runtime by the MasterUrl property of the Website. The default setting for this is _catalogs/masterpage/default.master. This is the default.master file in the Master Pages gallery of the website. Until you edit this file using SharePoint Designer it will point to a ghosted copy of the file in the TEMPLATE\GLOBAL directory of the 12 hive. You can also ghost custom .Master files from your Site Definition directory into the Masterpage gallery of the site using a Module Element. Then you can set the MasterUrl and/or CustomMasterUrl attributes of the Configuration Element in the ONET.xml file to point at these ghosted .Master files. If you also change the @Page directive of the .aspx files on your site to use ~/masterurl/custom.master you will establish a hierarchy of master pages that will be used. The page will first try to use the customMasterUrl setting, then the masterUrl setting, and finally the default.master file in GLOBAL.
Making these changes later will NOT result in a change to existing Sites, but you can also set the MasterUrl and CustomMasterUrl properties of a Website programmatically. So I reasoned it would be possible to create an Event Handler that would fire when a Feature was activated to set these properties and then move the .Master files using a Feature Module. Activating this Feature on a site would accomplish the same changes outlined above by a custom site definition. Here’s how it can be done.
First, we need a Feature. To create our Feature we need a Subdirectory Called CustomMaster in the TEMPLATE\FEATURES directory of the 12 hive. Then we need add 4 files to this directory: Feature.xml, Elements.xml, Custom.master, and myDefault.master.
FEATURE.XML – This file is used to identify the feature and list out the items that will be part of the Feature. Our Feature will include an assembly that will contain code to run in response to Feature events and an Elements.xml file. The code for our Feature is listed below:
1: <?xml version="1.0" encoding="utf-8" ?>
2: <Feature xmlns="http://schemas.microsoft.com/sharepoint/"
3: Id="90969656-A1C9-4f40-A95F-A3BDDF5723BF"
4: Title="Use Custom Master File"
5: Scope="Web"
6: ReceiverAssembly="CustomMaster, Version=1.0.0.0,
7: Culture=neutral, PublicKeyToken=bcee0f83b26fbb16"
8: ReceiverClass ="CustomMaster.ChangeMaster" >
9: <ElementManifests>
10: <ElementManifest Location="Elements.xml"/>
11: </ElementManifests>
12: </Feature>
ELEMENTS.XML – In this file we will identify two .Master files that will be ghosted to the masterpages gallery of the site.
1: <?xml version="1.0" encoding="utf-8" ?>
2: <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
3: <Module Name="AddMasters" Url="_catalogs/MasterPage" >
4: <File Url="MyDefault.master" Type="GhostableInLibrary"
5: IgnoreIfAlreadyExists="True">
6: <Property Name=“ContentType”
7: Value=“$Resources:cmscore,contenttype_masterpage_name;" />
8: </File>
9: <File Url="custom.master" Type="GhostableInLibrary"
10: IgnoreIfAlreadyExists="True">
11: <Property Name=“ContentType”
12: Value=“$Resources:cmscore,contenttype_masterpage_name;" />
13: </File>
14: </Module>
15: </Elements>
MYDEFAULT.MASTER and CUSTOM.MASTER – These are copies of the default.master file from the TEMPLATE\GLOBAL directory of the 12 hive. If your .aspx page references the master file ~/masterUrl/default.master then myDefault.master will be used. If you reference ~/masterUrl/custom.master then Custom.Master will be used. WARNING: Do not use SharePoint Designer to edit files stored in the 12 hive. This would break the files.
The last piece of the Feature is a Feature event handler that will be used to modify the masterUrl and customMasterUrl properties of the Website programmatically. The event handler will set the properties when the Feature is activated and reset them to the default when the Feature is deactivated. The code for the event handler is listed below:
1: using System;
2: using System.Collections.Generic;
3: using System.Text;
4: using Microsoft.SharePoint;
5:
6: namespace CustomMaster
7: {
8: public class ChangeMaster:Microsoft.SharePoint.SPFeatureReceiver
9: {
10: public override void FeatureInstalled
11: (SPFeatureReceiverProperties properties)
12: {
13: }
14: public override void FeatureUninstalling
15: (SPFeatureReceiverProperties properties)
16: {
17: }
18: public override void FeatureActivated
19: (SPFeatureReceiverProperties properties)
20: {
21: SPWeb CurrentWeb = properties.Feature.Parent as SPWeb;
22: CurrentWeb.MasterUrl = "/_catalogs/masterpage/MyDefault.master";
23: CurrentWeb.CustomMasterUrl = "/_catalogs/masterpage/custom.master";
24: CurrentWeb.Update();
25: }
26: public override void FeatureDeactivating
27: (SPFeatureReceiverProperties properties)
28: {
29: SPWeb CurrentWeb = properties.Feature.Parent as SPWeb;
30: CurrentWeb.MasterUrl = "/_catalogs/masterpage/default.master";
31: CurrentWeb.CustomMasterUrl = "/_catalogs/masterpage/default.master";
32: CurrentWeb.Update();
33: }
34: }
35: }
36:
Once the event handler has been compiled and added to the Global Assembly Cache and the Feature directory has been created you can Install and Activate the Feature. To install the Feature use the following command line:
stsadm -o installfeature -n CustomMaster
Then you can go to the Site Features link in SiteSettings on any SharePoint website and activate the Feature. Every website where the Feature is activated will use the myDefault.master stored in the Feature as its .master file. If you modify the @Page declaration of a page on the site to use ~/masterUrl/Custom.master then the Custom.master will be used.
*** Updated July 3, 2008 ***
I noticed recently that I left one line out of the Elements.xml file which prevented the feature from working in Site Collections where Publishing was turned on. In those sites the master pages gallery contains two content types so you have to specify what type of file you are "ghosting" with your . The Code that was added is italized in the code listing above.
