SharePoint 2007 Deployment: Feature Stapling

Summary

This post is about developing features that associate other features to an existing site definition. This is one of the most powerful types of feature since it allows you to add new functionality to existing site definitions. Check the first post SharePoint 2007 Deployment: Overview for an introduction and the series index.

Package Structure

As I mentioned previously in the post SharePoint 2007 Deployment: Creating and Using Features, to build a feature you need to create the following files:

  • The feature manifest file (which must be named feature.xml)
  • One or more element manifest files

The feature manifest file contains the generic information about the feature package, and the element manifest files contain the information about each specific type of element that makes up the feature. Since I already explained all the possible contents of the feature manifest file in the above mentioned post, I will focus this one the element manifest that allows the feature stapling (feature site template association).

You can then place these two files inside a Solution following the instructions in the post SharePoint 2007 Deployment: Creating Solutions, to provide an easy way to deploy the feature (or upgrade it).

Feature Stapling

Feature stapling is the process of associating features to existing site definitions so that, when a new site is provisioned from that definition the associated features are automatically activated.

This means that you need, at least, two features to do this:

  • The feature (or features) you wish to associate (that is, to staple) to a site definition;
  • The feature that performs the association (the stapler).

The first one can be any feature with scope Site or Web. The second is the one I’m presenting in this post.

Allowed Scopes

The scopes to which a feature can be deployed, are dictated by the types of elements included in it. A feature with feature site template association elements can be deployed to Site Collection, Web Application or Farm scopes.

Feature Manifest

I will only present a simple feature manifest, since the additional options were presented in the above mentioned post.

<?xml version="1.0" encoding="utf-8" ?>
<Feature
    xmlns="http://schemas.microsoft.com/sharepoint/"
    Id="{8213A053-46B0-43f9-B00C-B2A8CF7A3355}"
    Title="My Feature Stapling"
    Description="This feature staples other features to a
site definition.
" Scope="Farm" Creator="Create IT" Version="1.0.0.0"> <ElementManifests> <ElementManifest Location="Elements.xml"/> </ElementManifests> </Feature>

Notes about this feature manifest:

  • The title of the feature is My Feature Stapling.
  • It will be deployed as a Farm feature, since it’s Scope value is Farm. By default, SharePoint automatically activates features of this scope. You can, however, override this behaviour by setting the ActivateOnDefault attribute to false on the Feature element.
  • It references a single element manifest file: Elements.xml.

Element Manifest

The element manifest file can have any name you wish (in this example it’s called Elements.xml), but it’s root element must be <Elements>. Inside this root element, you can place any number of feature element descriptions. In this example I will present the use of the <FeatureSiteTemplateAssociation> element which is used to associate features to existing site definitions.

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <!-- My Site Columns -->
  <FeatureSiteTemplateAssociation 
    Id="{CC3144A5-E055-4474-928E-5D21CDE53D38}" 
    TemplateName="STS#0" />
  <!-- My Content Types -->
  <FeatureSiteTemplateAssociation 
    Id="{E739683D-ACB8-4187-A764-1323BE76D12D}" 
    TemplateName="STS#0" />
</Elements>

This example associates two features with the Team Site definition. The <FeatureSiteTemplateAssociation> element has no child elements and only two attributes:

  • Id – (required) The GUID of the feature that is to be stapled to the site definition.
  • TemplateName – (required) The name of the site definition including the configuration Id. For SharePoint’s out-of-the-box site definitions, this attribute can be:
    • STS#0 (Team Site)
    • STS#1 (Blank Site)
    • STS#2 (Document Workspace)
    • MPS#0 (Basic Meeting Workspace)
    • MPS#1 (Blank Meeting Workspace)
    • MPS#2 (Decision Meeting Workspace)
    • MPS#3 (Social Meeting Workspace)
    • MPS#4 (Multipage Meeting Workspace)
    • CENTRALADMIN#0 (Central Administration)
    • WIKI#0 (Wiki Site)
    • BLOG#0 (Blog Site)
    • BDR#0 (Document Center)
    • OFFILE#1 (Records Center)
    • SPSMSITEHOST#0 (My Site Host)
    • SPSMSITE#0 (Personalization Site)
    • CMSPUBLISHING#0 (Publishing Site)
    • BLANKINTERNET#2 (Publishing Site with Workflow)
    • BLANKINTERNETCONTAINER#0 (Publishing Portal)
    • SPSPORTAL#0 (Collaboration Portal)
    • SPSNHOME#0 (News Site)
    • SPSITES#0 (Site Directory)
    • SPSREPORTCENTER#0 (Report Center)
    • SRCHCEN#0 (Search Center with Tabs)
    • SRCHCENTERLITE#0 (Search Center)

There can be other site definitions depending on which site templates you have installed on your farm. The best way to check which ones you can use is to go to the folder C:\…\12\TEMPLATE\[LCID]\XML where [LCID] represent the Language ID of the site definition you are looking for, and open each webtemp*.xml file.

Each of these files will have the following structure:

<?xml version="1.0" encoding="utf-8"?>
<!-- _lcid="1033" _version="12.0.4518" _dal="1" -->
<!-- _LocalBinding -->
<Templates xmlns:ows="Microsoft SharePoint">
  <Template Name="STS" ID="1">
    <Configuration ID="0" 
                   Title="Team Site" 
                   Hidden="FALSE" 
                   ImageUrl="/_layouts/images/stsprev.png" 
                   Description="A site for teams to quickly […] 
                   DisplayCategory="Collaboration" >          
    </Configuration>
    <Configuration ID="1" 
                   Title="Blank Site" 
                   Hidden="FALSE" 
                   ImageUrl="/_layouts/images/blankprev.png" 
                   Description="A blank site for you to […] 
                   DisplayCategory="Collaboration" 
                   AllowGlobalFeatureAssociations="False" >      
    </Configuration>
    <Configuration ID="2" 
                   Title="Document Workspace" 
                   Hidden="FALSE" 
                   ImageUrl="/_layouts/images/dwsprev.png" 
                   Description="A site for colleagues to work[…] 
                   DisplayCategory="Collaboration" >          
    </Configuration>
    [...]
  </Template>
</Templates>

In the sample above you can see the description of the three configurations of the STS site template. To build the TemplateName required for the feature site template association, you get the template name (attribute Name of the element Template), which in this case is STS, add a hash sign (#) and complete the string with the configuration ID (attribute ID of the element Configuration), which in this case can be 0, 1 or 2, depending on the chosen configuration.

Sample

You can download this sample here. This sample includes:

  • The solution manifest file (manifest.xml).
  • The solution cab structure file (solution.ddf).
  • The feature manifest file (Feature.xml).
  • The feature site template association element manifest file (Elements.xml).
  • A batch file (build.bat) that creates the solution package (MyFeatureStapling.wsp).

Notice: This sample is given for illustrative purposes only. Feel free to modify and use it as a template for your solutions and features.