SharePoint 2010 - WebTemplate feature

The new WebTemplate feature element in SharePoint 2010 was introduced mainly as a way to define site definitions in sandbox solutions (since you can't use the traditional site definitions in sandboxes). Still, this doesn't mean that you can't use WebTemplate features in a farm solution - there they can be used as an alternative to the old-style site definitions. About the pros and cons of the WebTemplate feature element – one thing that I can see at this point (we’re still lacking complete documentation on that) is that you may have one or more site definitions in a single feature and you have the option to have site definitions in separate features within a single SharePoint project. So, instead of having to maintain two different types of artifacts – features and traditional site definitions you may have the latter as a feature or a set of features too – this allows for finer control over what site definitions you may have in your farm – you can install and uninstall the WebTemplate features thus enabling or disabling the various site definitions that you have created instead of having to remove the whole solution to get the traditional site definitions removed.

Let me now show you how you can create a WebTemplate feature – so you can start with an empty SharePoint project (or with an existing project of yours) and add an empty SharePoint element to it. You can leave the default name of the element – e.g. EmptyElement1 but it is a good idea to give it the same name as you will put in the Name attribute of the WebTemplate element. I will explain shortly why this is necessary. In the elements.xml file of the empty element item you need to have the WebTemplate element’s XML similar to this one:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

  <WebTemplate Name="SimpleSite" Title="Simple site" BaseTemplateID="1" BaseTemplateName="STS" BaseConfigurationID="0" DisplayCategory="Simple sites" />

</Elements>

In the WebTemplate element you have four mandatory attributes – Name, BaseTemplateID, BaseTemplateName, BaseConfigurationID. While the Name attribute defines the internal name of the site template (that you can use with the object model to create sites based on that definition), the other attributes though required and seemingly specifying something like a site definition inheritance don’t actually do that. At least while I tested I didn’t see that any features or module elements defined in the base site definition got activated when a site based on the new one was created. The exact values for these attributes you can check in the webtemp.xml file or derived webtemp*.xml files in the 14/1033/XML folder. Two other attributes that are important though not mandatory are the Title and the DisplayCategory ones – the former specifies the display name of the site template that will appear in the create site collection or create site application pages and the latter - the category tab under which the template will appear on these pages.

After you have the WebTemplate element in the elements.xml file, you will need the onet.xml file which is actually exactly the same format as we know from the traditional site definitions. As was the general practice with SharePoint 2007 when we used to copy-paste and later modify onet.xml files from the standard site definitions when creating custom ones in this sample I just copied the onet.xml from the STS site definition without any modifications whatsoever. There is one difference however in the onet.xml files for WebTemplate feature elements and the traditional ones – in the former you can have just one Configuration element – actually there may be more than one in your onet.xml (as in the STS onet.xml) but just the one with ID=0 will be used. There is something important about the onet.xml file here – it needs to be in a subfolder of the feature’s root folder with the same name as the Name attribute of the WebTemplate element. That’s why it is handy to have the element item’s name the same as the Name attribute as I mentioned above, otherwise you will need to modify the DeploymentLocation property of the onet.xml file. Note also that the DeploymentType property of the onet.xml (and of the other files that you may have in the site definition) should be set to ElementFile.

The last thing that you need to set is the scope of the feature project item that contains the WebTemplate element item – the scope should be set to Farm – this is the only possible value for farm solution WebTemplate elements. The thing with farm scoped features is that you don’t need to activate them, simply installing them makes them available in the SharePoint farm – so basically you only need to deploy the containing solution to the farm to have the site definitions visible.

Here is a small screenshot of the solution explorer view of the sample project that I created for demonstrating the WebTemplate element:

So you see that besides the elements.xml and onet.xml files I also added two aspx files to the WebTemplate site definition – they are actually also copied from the standard STS template and are provisioned with a Module element inside the onet.xml file (actually this is true only for the default.aspx file since only the default configuration from the onet.xml file is used here).

After you deploy the solution containing your WebTemplate feature you will be able to see your new site template in the create site collection page in the central administration site – as in the case with my sample solution:

[Updated: 28 Sep 2011]

You can download the sample solution from here. Note – when you create a new site based on this sample site definition it will be exactly the same as look similar to the standard team site template – remember that I simply copied the onet.xml from the standard STS site definition. Note that all the features from the ONET.XML file of the standard STS site definition will be activated in the site based on this custom WebTemplate definition, but in the case of the standard team site definition the newly created site will have additionally all stapling features targeting the standard team site definition (whose number is quite big actually). This is an important difference to have in mind, because the feature stapling mechanism works only with the old style site definitions and not with WebTemplate definitions.

And one list thing here, quite important though – if you need to create a site collection or a site based on a WebTemplate site definition with the object model (or in a portal site definition manifest file) you need to provide the web template name in the following format:

{[id of the WebTemplate feature]}#[Name of the WebTemplate element]

In my sample solution the exact name is this:

{797fb1e4-d407-4599-9853-9a0adbaef1c7}#SimpleSite

This is because the ID of the WebTemplate feature is 797fb1e4-d407-4599-9853-9a0adbaef1c7 and the Name attribute of the WebTemplate element is SimpleSite. Note that you need the curly braces around the feature’s ID.