Feature Stapling in WSS V3

Background:

New to the WSSv3 Platform is a concept called Features. These enable you to package chunks of functionality and allow this functionality to be turned on or off in a WSSv3 based site. This could be things like:

- List templates

- List instances

- Menu Items

- Workflows

- Web Parts

- ...

I am not going to go into these in a lot of detail here, but if you want to read more about them then you can here:

http://msdn2.microsoft.com/en-us/library/ms460318.aspx

One of the big problems people faced in WSS (V2) was that we did not support you making changes to the out of the box site definitions. One of the big reasons for this was that we might need to update that site definition in a Service Pack and overwrite your changes.

This meant that you need to take a copy of our out of the box site definitions and then hide the originals from the user ... and then make all the changes you like. This would ensure we would not break the site definition in a Service Pack for example.

I guess I like to refer this to who “owns” a site definition. Microsoft “own” the out of the box site definitions and you “own” any that you create and add to the product. That way in a service pack we will only update the site definitions that we ship with the product and not step on any site definitions you might have added.

So! What am I attempting to get to :)

We built Features so that you can turn functionality on and off in a site after it was create ... even if it was not in the original site definition.

So what happens if you want to associate a Feature with a site definition?

Well, as you should know by now, it is not advisable to modify the out of the box site definitions. So how do you do this?

This is where Feature Stapling comes in...

Solution == Feature Stapling

Feature Stapling allows you to “staple” a Feature to a site definition without modifying it in any way. This means you can add your feature to all sites created using that site definition.

E.g. You want to add your WidgetFeatureXYZ to the out of the box Team Site definition. Simple ... use a Feature Staple!

So how do you do this?

How-To:

To create a staple you actually create another Feature that does the staple. Below is an excerpt from a staple feature we use in the product to staple a Multilanguage feature to the STS, BDR & SPS site definitions.

Feature.xml file:

Title="$Resources:MultiLangStaplingFeatureName"
Description="$Resources:MultiLangstaplingFeatureDescription"
Version="12.0.0.0"
Scope="Farm"
xmlns="http://schemas.microsoft.com/sharepoint/"
DefaultResourceFile="_Res">

TransMgmtFunc.xml file that contains the FeatureSiteTemplateAssociation element:

http://schemas.microsoft.com/sharepoint/">

In the above example it “staples” the Feature with the ID “29D85C25-170C-4df9-A641-12DB0B9D4130” to the STS#0, STS#1, BDR#0 & SPS#0 site definitions.

This is very powerful as it allows you to add functionality to site definitions without having to modify the site definitions themselves.

Now ... one last final note on this, if you want to staple your Feature to ALL site definitions then you can staple it to the GLOBAL site definition and it will be added to all sites that are created.

Pretty cool huh!

TIP: ADDED BONUS FOR THOSE WHO HAVE READ THIS FAR:

Replacing ExecuteURL:

You can use Feature stapling to effectively replace your use of the ExecuteURL property in a site definition.

Scenario: You want to run some custom code whenever a site is created. (a typical use of the ExecuteURL property in V2)

Solution: Build a Feature that has an Event Receiver defined on it; & have it catch the Feature activation event. Run your custom code in there. Then, use a Feature Staple to staple your Feature to the site definition e.g. FOO#0 (or whatever one you want to run your code for).

Bingo! You can now run your custom code whenever a site is created :)

Hope this helps...

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 Featureelement.
• 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. Inside this root element, you can place any number of feature element descriptions. In this example I will present the use of the 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/">      <FeatureSiteTemplateAssociation      Id="{CC3144A5-E055-4474-928E-5D21CDE53D38}"      TemplateName="STS#0" />      <FeatureSiteTemplateAssociation      Id="{E739683D-ACB8-4187-A764-1323BE76D12D}"      TemplateName="STS#0" /> Elements>

This example associates two features with the Team Site definition. The 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"?>   <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 TemplateNamerequired 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.

MOSS 2007 : Feature Stapling

Introduction
Recently, I came across a situation, where-in I need to apply our custom theme to sharepoint site upon creation, i.e. setting our custom theme as a default one.
We generally have to go for customizing the out of box templates. In such a case, modifying the 12 hive folder is one option, but isn’t recommended as it will render the site unsupported in case of an upgrade.

In this post, I will be demonstrating how to attach a custom feature with a site template. Feature Stapling allows to staple a Feature to a site definition without modifying it in any way. To use feature-stapling, you first need the feature(s) you wish to link to the site definition - these should be created in the normal way. Then you should create a 2nd feature which does the actual stapling.

Step 1 - Create a Sample Feature
Create a sample feature, which will be activated every time a site is created with a specified template.

• Create a Class Library project and inherit SPFeatureReceiver class
• Override FeatureActivated() method.
• Strongly name the assembly.
• Add assembly to GAC.

• Create a folder called ACMEThemeFeature inside FEATURES folder. (%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES)
• Create a feature.xml file inside ACMEThemeFeature folder.

• Run the following command to install this feature:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN>stsadm -o installfeature -name ACMEThemeFeature

Step 2 - Associate a Template with Feature
After creating and installing a feature, we need to associate a template with this feature, for that purpose we will again create a feature but with scope as FARM(This is called a stapler feature).

• Create a folder called ACMEThemeStapler inside FEATURES folder.
• Create Feature.xml file inside ACMEThemeStapler folder.

• Create Element.xml inside ACMEThemeStapler folder.

• FeatureSiteTemplateAssociation ID inside Element.xml is id of theACMEThemeFeature feature.
• TemplateName is the teamplet name, you will get a list of TemplateName from Roadburn’s SharePoint 2007 blog.
• Install ACMEThemeStapler feature using below command from command prompt:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN>stsadm -o installfeature -name ACMEThemeStapler

Now, whenever a new site is created, ACMEThemeFeature feature will be activated and the will apply the specified theme to site.