When a new team site gets created, note that several lists and libraries get created automatically. In the Chapter 2 site, go to Site Actions | View All Site Content. Shared Documents, Tasks, Announcement, Calendar, Links all exist because the site definition for a team site (the provisioning instructions for creating the site) included the creation of these lists.
What if you wanted to include the automatic creation of a Proposals document library every time a team site was created? You may think to modify the out-of-the-box team site definition to accomplish this. Please DO NOT ever modify an existing site definition, out-of-the-box or otherwise! You will introduce breaking changes if you do! You may then wish to create your own custom site definition, which can be a daunting and non-trivial task. In over 90% of cases, what you are looking to do can be accomplished using a Feature Stapler.
A Feature Stapler is used to literally attach (or "staple", I guess) an additional Feature to an existing site definition. So, by stapling the Proposal Library feature to the team site definition, we will accomplish the behavior that every time a team site is created, we will see a Proposals library. Simple!
Open the SP2010ProposalLibrary Visual Studio Solution you created in the previous recipe:
- Right-click on the SP2010ProposalLibrary and select Add | New Item.
- Select Module from the presented list, provide a name such as ProposalLibraryFeatureReceiver and click on the Add button.
- Provide the following lines of XML to the Elements.xml file:
<!-- We are stapling both the schemal and proposal library features --> <!-- to the Team Site definition (STS#0) --> <FeatureSiteTemplateAssociation Id="afebf5af-9083-4596-aa4f-56b1bfd0a9a7" TemplateName="STS#0" /> <FeatureSiteTemplateAssociation Id="f3b08329-d903-4a99-844c-c9924f88feb7" TemplateName="STS#0" />
- Right-click the SP2010ProposalLibrary project and select Deploy Solution. Wait until you see the Deploy Succeeded message in the bottom left-hand corner of Visual Studio.
A Feature Stapler took longer to explain than to actually do! The above line of code takes the GUIDs for our Features (which you can look up in the properties of each feature to verify), and "attaches" them to the team site definition. The code name for the team site is "STS#0", and the code name for a blank site is "STS#1". The short form "STS" comes from the "acronym" that is the directory name for the site definition. If you wish to view it, go to the SharePoint root folder, and then the subfolder TEMPLATE/SiteTemplates.
To test our Feature Stapler, we will create another site collection for this chapter:
- Go to Central Administration and click on the link Create Site Collections.
- Ensure the correct web application is selected. Enter Chapter 2 New for the title and Chapter2New in the textbox for the URL.
- Leave the Template Selection defaulted to Team Site, and enter administrator for the Primary Site Collection Administrator.
- Leave all other options at their default values. Scroll to the bottom and click on Ok.
- When the screen Top Level Site Successfully Created appears, click on the link provided.
- Note that the Libraries section now has a Proposals library!
Feature Staplers are an excellent means of "adding" to an out-of-the-box site template and making it "your own". As you can staple any Feature, literally the possible uses for this simple technique are endless.