{"id":36,"date":"2007-06-18T18:06:00","date_gmt":"2007-06-18T23:06:00","guid":{"rendered":"http:\/\/www.dontpapanic.com\/blog\/?p=36"},"modified":"2011-04-19T08:38:23","modified_gmt":"2011-04-19T12:38:23","slug":"feature-to-install-a-custom-master-page","status":"publish","type":"post","link":"https:\/\/www.dontpapanic.com\/blog\/?p=36","title":{"rendered":"Feature to Install a Custom Master Page"},"content":{"rendered":"
\n
\n

A former student brought an excellent BLOG post that Heather Solomon made last October (http:\/\/www.heathersolomon.com\/blog\/articles\/servermstpageforsitecollect_feature.aspx<\/a>) 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.<\/p>\n

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<\/em> and CustomMasterUrl<\/em> attributes represent two replaceable parameters that can be used to set the Masterpage attribute of the @Page <\/strong>declaration on the pages of a SharePoint site.  \u201cOut of the Box\u201c .aspx pages point to a Masterpage at ~\/masterurl\/default.master<\/strong>. This will be replaced at runtime by the MasterUrl <\/em>property of the Website.  The default setting for this is _catalogs\/masterpage\/default.master<\/strong>.  This is the default.master<\/strong> 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<\/em> files from your Site Definition directory into the Masterpage gallery of the site using a Module<\/em> Element.  Then you can set the MasterUrl<\/em> and\/or CustomMasterUrl<\/em> attributes of the Configuration<\/em> Element in the ONET.xml<\/strong> file to point at these ghosted .Master files.  If you also change the @Page <\/strong>directive of the .aspx files on your site to use ~\/masterurl\/custom.master <\/strong>you will establish a hierarchy of master pages that will be used.  The page will first try to use the customMasterUrl <\/em>setting, then the masterUrl<\/em> setting, and finally the default.master<\/em> file in GLOBAL.<\/p>\n

Making these changes later will NOT result in a change to existing Sites, but you can also set the MasterUrl<\/em> and CustomMasterUrl<\/em> 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<\/em> 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.<\/p>\n

First, we need a Feature. <\/strong>To create our Feature we need a Subdirectory Called CustomMaster<\/strong> in the TEMPLATE\\FEATURES<\/strong> directory of the 12 hive.  Then we need add 4 files to this directory:  Feature.xml, Elements.xml, Custom.master, and myDefault.master.<\/p>\n

FEATURE.XML<\/u> –<\/strong> 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:<\/p>\n

<\/font> <\/p>\n

\n
   1:  <\/span><?<\/span>xml<\/span> version<\/span>="1.0"<\/span> encoding<\/span>="utf-8"<\/span> ?><\/span><\/pre>\n
   2:  <\/span><<\/span>Feature<\/span> xmlns<\/span>="http:\/\/schemas.microsoft.com\/sharepoint\/"<\/span><\/pre>\n
   3:  <\/span>         Id<\/span>="90969656-A1C9-4f40-A95F-A3BDDF5723BF"<\/span><\/pre>\n
   4:  <\/span>         Title<\/span>="Use Custom Master File"<\/span><\/pre>\n
   5:  <\/span>         Scope<\/span>="Web"<\/span><\/pre>\n
   6:  <\/span>         ReceiverAssembly<\/span>="CustomMaster, Version=1.0.0.0,<\/pre>\n
   7:  <\/span>             Culture=neutral, PublicKeyToken=bcee0f83b26fbb16"<\/span><\/pre>\n
   8:  <\/span>         ReceiverClass<\/span> ="CustomMaster.ChangeMaster"<\/span> ><\/span><\/pre>\n
   9:  <\/span>    <<\/span>ElementManifests<\/span>><\/span><\/pre>\n
  10:  <\/span>        <<\/span>ElementManifest<\/span> Location<\/span>="Elements.xml"<\/span>\/><\/span><\/pre>\n
  11:  <\/span>    <\/<\/span>ElementManifests<\/span>><\/span><\/pre>\n
  12:  <\/span><\/<\/span>Feature<\/span>><\/span><\/pre>\n<\/p><\/div>\n