Friday, February 02, 2007

Creating a Basic Site Definition in SharePoint 2007

Creating a site definition from scratch in SharePoint 2007 is no easy task; easier, certainly, than it was in 2003, but in some ways even more complex. Perhaps the most confusing new element to creating site definitions is the use of FEATURES. There are some great articles on what FEATURES are and how to use them (see here, here, and here) so do a little homework before you get started.

Unfortunately, the built-in WSS templates don't use the time-saving and oh-so-handy Publishing features of the portal definitions, so you'll have to create your own definition if you want to apply any customizations beyond basic style overrides. To get you going in the right direction, here's a handy little guide on creating a very basic site definition from scratch. Let's first assume that you want a custom Team Site - nothing fancy, just something you can style and modify without impacting the default definitions.

Begin by performing the same steps you would have done in 2003. Navigate to the \12\Template\SiteTemplates directory (the 60 hive is dead; long live the 12 hive). Copy the 'Sts' folder and rename it - say 'CUSTOMSITE' for this example. Next, find the WEBTEMP.XML folder in \12\Template\1033\Xml. Open it in Notepad and add a new Template node to the end, like so:

< Template Name="CUSTOMSITE" ID="1001" >
< Configuration ID="0" Title="Custom Web Site" Hidden="FALSE" ImageUrl="/_layouts/images/stsprev.png" Description="Customized site definition for My Team Site" DisplayCategory="Collaboration" > < /Configuration >
< /Template >

* Note: The same numbering conventions apply in 2007 as in 2003 - set your Template ID to something greater than 1000 and the first Configuration node should always start with '0'.

Save the file and do an IISRESET at the command prompt. This is all you really need for a basic site definition but, as you will discover if you create a new Site Collection using this new definition and open it in SharePoint Designer, there are some things missing. Some very important things, actually, like the DefaultLayout.aspx page (look in /_catalogs/masterpage and you'll notice that only the default.master page is present). Without DefaultLayout.aspx you'll be able to modify the master page but not the central content area of your site. Oops. What happened?

As I said at the beginning, it's all about the Features. In this case, not only does the ONET.XML file determine what Features are provisioned as part of the site, there are also Features which determine what goes into a site that have nothing to do with the site itself - they are system Features that SharePoint uses when provisioning all sites.

To make sure that your new Site Definition has all the right pieces and parts, navigate to the \12\Template\Features\BaseSiteStapling folder and open BaseSiteStapling.xml in Notepad. It should look something like this:

< Elements xmlns="">

< FeatureSiteTemplateAssociation Id="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" TemplateName="STS#0" / >
< FeatureSiteTemplateAssociation Id="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" TemplateName="STS#2" / >
< FeatureSiteTemplateAssociation Id="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" TemplateName="MPS#0" / >
< FeatureSiteTemplateAssociation Id="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" TemplateName="MPS#1" / >
< FeatureSiteTemplateAssociation Id="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" TemplateName="MPS#2" / >
< FeatureSiteTemplateAssociation Id="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" TemplateName="MPS#3" / >
< FeatureSiteTemplateAssociation Id="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" TemplateName="MPS#4" / >
< FeatureSiteTemplateAssociation Id="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" TemplateName="WIKI#0" / >
< FeatureSiteTemplateAssociation Id="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" TemplateName="BLOG#0" / >


Take note of the first child node - it defines a Feature (in this case, the BaseSiteFeatureTitle) to be included with the site identified by the TemplateName setting. Does this setting look familiar? It should, as it's the same as the STS (WSS Team Site) < Template > node in WEBTEMP.XML. The #0 after it refers to a specific < Configuration > child node. Since your new Site Definition needs to behave exactly as the STS definition does, you must create a < FeatureSiteTemplateAssociation > for each Feature that STS is associated with, like so:

< FeatureSiteTemplateAssociation Id="B21B090C-C796-4b0f-AC0F-7EF1659C20AE" TemplateName="CUSTOMSITE#0" / >

Simply go through BaseSiteStapling.xml and each time you see an ID associated with STS#0 add an entry for CUSTOMSITE. But wait, you're not done. You now have to do the same thing in the PremiumSiteStapling.xml file located in \12\Template\Features\PremiumSiteStapling folder and, if you want the included workflows, do the same in FeatureStapling.xml in \12\Template\Features\StapledWorkflows folder.

Perform another IISRESET and create a new Site Collection based on your custom Site Definition. Now, when you edit the site in SharePoint Designer, you will see all the right files in /_catalogs/masterpage, such as DefaultLayout.aspx, AdvancedSearchLayout.aspx, SearchMain.aspx, etc.

As an aside, you can mimic some of the Publishing functionality of the Portal Site Definitions by create your own Style and Images libraries, uploading your files, and referring to them from your customized master and layout pages by relative URL (such as ../../images/myhomepageimage.gif or ../../styles/custom.css). See this post for information on how to override CORE.CSS using this method.

kick it on