Master pages are a very powerful new feature in WSSv3 (and MOSS2007 by extension). They allow you a level of control that just wasn’t possible in WSSv2. However, with anything new there can be some misunderstandings. I wanted to share a few things that I’ve discovered while trying to get my custom master pages working.
First, we’re creating a new site definition here so let’s start with that. Todd Baginski’s post “HOW TO: Creating a custom Site Definition in MOSS 2007” is a good walkthrough. Next we need a custom master page. A copy of the default.master from …12\TEMPLATE\GLOBAL makes a good starting point. Drop that off in your new site definition directory.
Now it’s time for some modifications, first, you may want to rename your default.master you copied into your site definition. You can use custom.master if you want – or any other name, it doesn’t matter. Next, open your default.aspx file and change the MasterPageFile attribute on the top line to read “~masterurl/custom.master” – use this string even if your custom master page isn’t named custom.master. SharePoint does a string replacement of this string with the value contained in the CustomMasterUrl property of the site (SPWeb). Save the default.aspx file and repeat the process for defaultdws.aspx. (If you want to know more about the string replacement you can look at the “Customizing Master Pages in Windows SharePoint Services” SDK entry.)
Now we need to connect that to your site definition. That’s in your ONET.XML in the XML subdirectory of the site definition. Locate the Configuration node. Add a CustomMasterUrl attribute and set it to “_catalogs/masterpage/mypage.master” where mypage.master is the actual name that you gave your new master page. Now in the Modules nodein the configuration add a new Module tag referencing a new module definition you’ll define in a second. The node should look something like:
<Module Name=”CustomMasterPage” />
After the <Configurations> node/section there’s a module node section. In this section add:
<Module Name=”CustomMasterPage” List=”116″ Url=”_catalogs/masterpage” RootWebOnly=”FALSE”>
<File Url=”mypage.master” Type=”GhostableInLibrary” IgnoreIfAlreadyExists=”TRUE” />
Again, replace mypage.master with whatever you named your custom master page.
At this point you’re done. You can save the files, do an IIS reset and use your site with a custom master page.
A few notes about the whole process:
1) The “Customizing Master Pages in Windows SharePoint Services” SDK entry seems to indicate that you need to set both MasterUrl and CustomMasterUrl whenever you customize the master page – this isn’t correct. You can simply modify the CustomMasterUrl if you wish. This is a preferred approach for me because then you can change your default.aspx back to use a MasterPage of ~masterurl/default.master if you encounter issues with your custom master page. Of course, if you do this your pages will need to reference ~masterurl/custom.master to get your custom master page.
2) In the comments of Todd’s post “HOW TO: Creating a custom Site Definition in MOSS 2007”, Dan gives most of the information here – with a few extras. One of the extra things that he includes is a <ListTemplate>. If you include this node the site will work fine when created directly from a site definition, but it won’t work if you recreate the site from a site template. For some reason, SharePoint ignores this node on creation from a site definition – but not when being recreated from a site template. You’ll get some errors provisioning the global masterpage gallery in the ULS logs and a SharePoint File Not Found error. However, the snipit works fine without the ListTemplate node.
Special thanks to Quang Sun who drew the PSS case I opened to get this all straightened out.