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.

Set Item Security based on Content Type

I’ve seen several queries asking how to limit the items or documents that a user can view.  Audiences can be used to filter views of List items and Library documents.  But Audiences aren’t and never have been security.  If a user wants access to all the items in a list or library all they need to do is create a custom view, no matter what audience they are part of.

So if you want to limit what a user has access to you need to set specific security on each item.  Item level security defaults to inheriting the security settings of the list or library in which they are created.  A user can implement specific security but it requires an additional step on each item created.  You could create items in folders with specific permissions and let the items inherit security from the folders, but then you can’t easily display items from diferent folders in a single view.

So the question is:  How can I set specific security rights automatically based on who the user is, content type, or the value of a metadata field?

In this post I’ll explain how to create an event handler that will automatically set security permissions based on the content type used to create the item.  First, lets look at the code of the event handler.

01: public class ItemSet : SPItemEventReceiver
02: {
03:   public override void ItemAdded(SPItemEventProperties properties)
04:   {
05:     base.ItemAdded(properties);
06:     SPWeb web = properties.OpenWeb();
07:     SPList list = web.Lists[properties.ListId];
08:     SPRoleAssignmentCollection roles = list.RoleAssignments;;
09:     SPListItem addedItem = properties.ListItem;
10:     addedItem.BreakRoleInheritance(false);
11:     foreach (SPRoleAssignment r in roles)
12:     {
13:       if (r.Member.Name.ToString().StartsWith(properties.ListItem.ContentType.Name
14:         .ToString(), StringComparison.CurrentCultureIgnoreCase))
15:       {
16:         addedItem.RoleAssignments.Add(r);
17:       }
18:     }
19:     this.DisableEventFiring();
20:     addedItem.Update();
21:     this.EnableEventFiring();
22:   }
23: }
 

In lines 6-8 the event handler instantiates the Sharepoint web holding the list and walks the heirarchy to get the list instance itself.  We’ll use this later to retrieve the groups that have permission to the list.  Line 9 retrieves the list item that was just added.  Line 10 calls the BreakRoleInteritance method to set the item up with its own security listing.  Passing ‘False’ as a parameter tells Sharepoint not to copy the security settings of the list when breaking inheritance.  The foreach loop in lines 11-18 compares the Name of each user/group who has permissions in the list with the ContentType of the item being added.  If the name of the user/group begins with the name of the Content type it is added to the permissions list of the item.  For example, if the Content type of the item is named ‘TypeA’ then groups named ‘TypeAContribute’ and ‘TypeARead’ would be granted permissions on the item, but a group called ‘TypeBContribute’ would not.  Finally, in lines 19-21 the event handler temporarily suspends event processing and updates the item instance in the Sharepoint database.  Events are temporarily disabled to prevent recursive events like ItemModifying from firing as a result of the security change.

Once the event handler has been strong named, compiled, added to the GAC and activated using a Web scoped feature we are ready to test the results.  The steps are listed below:

  1. Create and add specific content types to the list/library being secured.
  2. Create Sharepoint groups in the top level site of the site collection whose names start with the name of the content type that they should have access to.  For example: TypeAContribute group would have Contribute permissions for TypeA content.
  3. Assign the Sharepoint groups appropriate permission levels to the list. 
  4. Now create a new item in the list and security will automatically be changed so that only groups whose names start with the name of the content type will have access to the item.  For example, when I created an announcement based on a content type called ‘TypeA’ the security was set as shown below:TypeA SecurityWhen a member of one of the TypeA groups logs in they see and can access only the annoncements created using the TypeA content type.�TypeA 

But when a user logs in who is a member of a group called ‘TypeBContribute’ they only see and can access announcements based on the TypeB content type.

TypeB

You could modify the basic shell of this event handler in several ways to meet the requirements of other scenarios.  For example, you could compare the groups with defined permissions in the list to the groups that the author is a member of and only add groups that the author and the list share in common.  Or you could add a custom choice field to the list with the names of sharepoint groups and let the user choose which groups to grant access to when creating the item.  Once you’ve got the basic event handler the only limits on setting security to a local list item is your own creativity.

Group A List by Week Number

I’ve seen several requests recently for how to Group a Sharepoint list by Month.  I’ve also seen several Blog posts on how to do it.  But recently I saw a query about how to Group by the Week Number of the year and several responses stating that it couldn’t be done.  I’ve always liked a good challenge, especially one that someone else says is IMPOSSIBLE.  So I decided ot figure out how to do it.  The results are below.

To Group a List by Week Number do the following:
 
  1. Make sure the list has a column that contains the Date you wish to GroupBy.  I’ll use the Start Time column of a standard Event list but you can use any Date/Time column.  You don’t need to filter out the Time portion first, it will be ignored.
  2. Add a Calculated column to the list called ‘WeekNumber’ that uses the following formula:
          =INT(([Start Time]-DATE(2007,1,1))/7)
    where [Start Time] is the date column whose week you want to group by.
  3. Set the data type of the Calculated Column to Number with 0 decimal places
  4. Create the view that you want Grouped by Week.
  5. SORT the view by [Start Time] and GROUPBY the [WeekNumber] column.

You’ll get a view that looks something like this:

GroupBy
 
This will give you a grouped list with the week number from the first day of the year.  But January 1st is rarely a Sunday or Monday.  If you want to be more accurate substitute the date of the first Sunday prior to 1/1/2007 in place of Date(2007,1,1).  This will give you the week number counting from the First partial week of the year.
 
Of course you’ll need to redo the calculated column when January rolls around next year, but only to change the Calculated Column to point at the first day of next year.
 
 

VTI Shooting brings back bad memories

I wasn’t really planning for this to be the second post on my new Blog, but the events at Virginia Technical Institute bring back too many bad memories.  My prayers go out to the family and friends of the students and faculty at VTI.  I know a little of what they are going through. 

In May, 2003 I went through a similar attack while a professor in the Business school at Case Western Reserve University in Cleveland, OH.  Compared to VTI we were relatively lucky, only one student was killed and two people injured, but we certainly didn’t feel lucky at the time.  Three PhD students and I were trapped in my office on the 5th floor of the building from the time the shooting started at 4:00 PM until SWAT rescued us at 12:30 AM the next morning.  At one point while trying to FAX a phone list for the building to the local police I came face to face with the gunman.  It was a terrifying experience.

MSNBC has a good report of the attack at Case Here: http://www.msnbc.msn.com/id/15767366/

including some of my testimony at the gunman’s trial http://www.msnbc.msn.com/id/15787964/

Welcome to my BLOG

Well its been a long time coming, but I’ve finally decided to start a BLOG.  I’ve never been much for keeping Journals, but now its time.  I’ve spent the last couple years starting my own Consulting/Training business.  In that timeI have continually stumbled across technical "Nuggets" by listening to students or while researching student questions.  But I’ve never had anywhere to publish those "Nuggets".  A Blog seems to be the perfect place to store this kind of asynchronously acquired information in a categorized format. 

Now that I’ve decided to give up the “freelancing thing“ and go to work for Mindsharp fulltime I don’t even have the excuse that I’m too busy trying to build the business.  Since Mindsharp has their own Blog hosting site its finally time.

So watch this space and I’ll try to share the things I learn about SharePoint, CRM, and .NET development.  Hang on to your hats its liable to be a bumpy ride.

Paul Stork
MBA, MCT, MCSE, MCSA, MCSD, MCDBA, MCITP