Speaking at the GCPCUG Windows Server SIG

I will be speaking at the Greater Cleveland PC Users Group Windows Server SIG on Thursday, June 28th from noon til 1:30.  My topic will be an “Introduction to Microsoft Office SharePoint Server 2007”.  Collaboration is one of the big buzzwords in the IT industry. Teams working on documents and projects together. There’s also a lot of buzz about Microsoft Sharepoint – a tool for working collaboratively. But, that buzz includes a lot of confusion about the product. This meeting will answer some of the basic questions about Sharepoint.

The GCPCUG Windows Server SIG is focused on Microsoft Windows Server 2003, Windows 2000 Server and even Windows NT.  Whether you are a network administrator, working toward certification or just interested in learning more, you can get together with other interested people at the Windows Server Special Interest Group (SIG) meetings. We are affiliated with the Greater Cleveland PC Users Group which has many special interest groups you will want to check into.

The SIG meets at the local Microsoft Offices in Independence on Oak Tree, which is about 1/2 mile West of 77 on Rockside (First Energy is also there). They are the first building complex on the right and are on the 3rd Floor.

Meetings are free and open to the public.

Feature to Install a Custom Master Page

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.