SharePoint 2010 Feature Stapling

By: Shishir Bhandari | Updated: 2010-12-21 | Comments | Related: > SharePoint Administration

Problem

When you start using SharePoint, you tend to explore what it offers out of box. So you start using out of the box site definitions. But as time passes you realize you need customizations in order to fulfill your requirements.

You can do this customization on each of the sites created from this site definition OR you can customize the out of the box site definition itself. The latter has a drawback though.

A SharePoint service pack upgrade would break any customization to out of box site definition. Then What is the best way to add Customizations on out of box sites? How would you apply your customizations on multiple sites?

Solution

The solution is Feature Stapling!

This article deals with the Feature Stapling concept in SharePoint. I am assuming the reader knows how to create a feature. For more details refer to this msdn article.

In this article, we will cover what Feature Stapling is, when to use Feature Stapling, and how to code Feature Stapling?

In SharePoint Feature Stapling Part 2, we will cover Common Issues with their solutions while coding Feature Stapling and few exceptional scenarios.

What is Feature Stapling?

Feature Stapling has two features. A "Stapler" feature which staples another feature to the site definition and the "Staplee" feature which will be stapled. Let's take an example to understand it.

Scenario: You want to apply a custom Theme to all of the "Publishing site" site definitions.

This can be solved by creating a feature which will apply the Custom theme to the site and it can be associated with the publishing site's site definition.

How to associate feature with sites / site definition?

A Feature can be associated with the sites / site definition in three different ways:

If the number of sites under consideration are minimal and you don't mind activating your feature on all the sites manually, then you can create a site from that site definition and deploy your "custom theme" feature to the site and activate it.
If you already know all the required customizations before creating the site, you can include the features in the site definition (onet.xml) before you use it to create sites.
If you want to automatically provision your feature when the user creates the site & you don't want to include it in the <SiteFeatures> or <WebFeatures> child elements of the <Configuration> element that represents the site definition configuration, you can use Feature Stapling. Another reason would be when you want to do customizations on out of the box site definitions, I recommend the use of Feature Stapling.

1. This is self explanatory: since we have many sites under consideration, we can't go for this option.

2. Include the customization in site definitions. You can include the feature in the onet.xml file of site definition in <webfeatures> or <sitefeatures>. The section of the site definition which contains the web or site level features associated with it is shown below:

<Configuration ID="1" Name="Blank">
      <Lists />
      <Modules>
        <Module Name="DefaultBlank" />
      </Modules>
      <SiteFeatures>
        <!-- BasicWebParts Feature -->
        <Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />
        <!-- Three-state Workflow Feature -->
        <Feature ID="FDE5D850-671E-4143-950A-87B473922DC7" />
      </SiteFeatures>
      <WebFeatures>
        <Feature ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" />
        <!-- TeamCollab Feature -->
        <Feature ID="F41CC668-37E5-4743-B4A8-74D1DB3FD8A4" />
        <!-- MobilityRedirect -->
      </WebFeatures>
</Configuration>

Here the ID in the feature tag is the Feature ID/ GUID. The Sitefeatures tag has features which will be activated when this site definition is used to create a site collection, whereas, the Webfeatures tag has features which will be activated when this site definition is used to create a web.

Since we have to customize the (out of the box) "Publishing Site" site definition, we can't go for this option.

If you want to know more about creating custom site definitions, refer to this msdn article.

3. Feature Stapling

Feature Stapling is achieved through the creation of another feature ("stapler") that defines the association of your regular Feature (the feature carrying your "Custom Theme") and the site definition you want to "staple" it too. In other words, you need to create two Features to achieve a complete Feature Stapling implementation. This means you can add your "Custom Theme" feature to all publishing sites.

For Example: All newly created sites from "publishing site" site definition should have your custom theme.

How to code Feature Stapling?

Step 1:

Create a web scoped feature ("staplee") to deploy your custom theme. For creating a Custom Theme programmatically, create a SPFeatureReceiver. Refer to this msdn article for more details on creating Custom Themes.

The Feature.xml for the Custom Theme is shown below:

<?xml version="1.0" encoding="utf-8" ?><Feature xmlns=http://schemas.microsoft.com/sharepoint/
	Creator="Bhandari, Shishir"
	Hidden="false"
	Id=";8DEE24AC-1FF9-4fb3-AC07-2A0D9D616D99"
	Scope="Web"
	Title="Custom Theme"
	Version="1.0.0.0"
	ReceiverAssembly="EdgewoodLLC.SharePoint.Branding, Version=1.0.0.0, Culture=neutral, PublicKeyToken=";9822be71ccc3f186"
	ReceiverClass="EdgewoodLLC.SharePoint.Branding.InstallCustomTheme">
	
	<ElementManifests>
		<ElementManifest Location="elements.xml"/>
	</ElementManifests>
    </Feature>

Write your code in the class "EdgewoodLLC.SharePoint.Branding.InstallCustomTheme" as mentioned in the feature file above.

Step 2:

Create a Web Application scoped feature ("Stapler") for attaching our Feature with the "Publishing Site" site definition. Since we want all publishing sites created under our web application to have our custom theme, we have kept the feature scoped at "Web application" level.

Below is the feature.xml for Stapler feature:


<?xml version="1.0" encoding="utf-8" ?>
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
          Id="97A2485F-EF4B-401f-9167-FA4FE177C6F6"
          Title="Custom Theme Stapler"
          Description="Staples Custom Theme Feature to PUBLISHING SITE - site definition"
          Version="1.0.0.0"
          Scope="WebApplication"
          Hidden="false">
    <ElementManifests>
        <ElementManifest Location="FeatureSiteTemplateAssociations.xml"/>
    </ElementManifests>
</Feature>

As you can see in the feature.xml, it refers to FeatureSiteTemplateAssociations.xml wherein all associations with site definitions are made.

Below is the FeatureSiteTemplateAssociations.xml :

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
                <FeatureSiteTemplateAssociation Id="8DEE24AC-1FF9-4fb3-AC07-2A0D9D616D99" TemplateName="BLANKINTERNET#0" />
</Elements>

Let us try to understand how this association is done.

    <FeatureSiteTemplateAssociation Id="8DEE24AC-1FF9-4fb3-AC07-2A0D9D616D99" TemplateName="BLANKINTERNET#0" />

"Id" is the feature Id / GUID of our Custom Theme(i.e. "Staplee").

TemplateName follows the format "<site template name ><Configuration Number>".

So, "BLANKINTERNET#0" means - the site definition "BLANKINTERNET" with Configuration 0 which is the "Publishing Site" template under the PUBLISHING section.

As shown below, the "Publishing Site" template will be displayed under the "Publishing" section.

How do you find out the site template name and configuration ID of a site definition?

If SharePoint is installed on your C drive, go to "c:\program files\common files\microsoft shared\web server extensions\12\template\1033\XML"

Open webtempsps.xml. Search for "Publishing Site". See its Configuration ID and Template name. It is shown below:

Step 3:

Deploy the "Stapler" and "Staplee" features.
Activate your "Custom Theme Stapler" feature on the required web application.

(For activating, Go to Central Administration -> Application Management -> "Manage Web application features" under SharePoint Web Application Management)

Now when you create any site using the "Publishing site" site template, it will have your Custom Theme.