The webtemp files are stored the SharePoint root directory at TEMPLATE/1033/XML. Note that the 1033 in this path refers to the English version of SharePoint, or the English language packs. If you are running a different version of SharePoint, such as a Spanish or a Chinese version, 1033 will be replaced by a different locale identifier. If you have multiple language packs installed on your SharePoint server and you want a site definition to be available for all of those languages, you will have to deploy your webtemp file to the XML folders for all those languages.

On a SharePoint server there are several webtemp files, all of which start with webtemp and end with .xml. The file name of the webtemp file can be made unique by adding something in between webtemp and .xml. The webtemp file that contains information about the eDiscovery site definitions, for instance, is called webtempedisc.xml. The webtemp of the basic SharePoint Foundation sites is simply called webtemp.xml. Figure 11-1 shows the contents of the TEMPLATE/1033/XML folder on a server that is running SharePoint Server 2013 Enterprise Edition.

Figure 11-1. The TEMPLATE1033XML folder containing the webtemp*.xml files

A single webtemp file can contain information about more than one site definition. The webtemp.xml file, for instance, contains information about 16 different site definitions. Some of them are hidden and should not be used by end users or by developers to create sites; others are visible and can be selected as templates when sites are created through the user interface. Site definitions can be made hidden for several reasons. In some cases, they are only for SharePoint internal usage, such as the GLOBAL site definition and the Central Administration site definitions. Other times, Microsoft might want to deprecate a site definition because it is no longer in line with how SharePoint can best be used, or because a better alternative exists. Because existing sites might break if a site definition is removed completely, Microsoft won’t remove the site definition from SharePoint, but they will make it hidden so that existing sites in your environment will continue to work. The fact that the definitions can still be found in the file system of a SharePoint server does not mean that it is a good idea to use them to create sites. Changing the Hidden property of an out-of-the-box site definition so that end users can use the site definition to create sites is not supported and should not be attempted.

The webtemp file contains Template and Configuration elements. The template element is linked to an ONET.xml file. Multiple configurations can be defined in a single ONET.xml file, with a Configuration element for each one. In the Configuration element, the title as users will view it, whether a site definition is hidden, a description, and a display category are defined. The display category is the tab on which the site definition will appear in the site creation user interface in SharePoint. The image used to be visible when subsites were created from an existing site collection, but in SharePoint 2013 the image won’t show up anywhere in the user interface:

<Template Name="STS" ID="1">
    <Configuration ID="0"
                   Title="Team Site"
                   Hidden="FALSE"
                   ImageUrl="/_layouts/15/images/stts.png?rev=23"
                   Description="A place to work together with a group of people."
                   DisplayCategory="Collaboration" >
    </Configuration>
    <Configuration ID="1"
                   Title="Blank Site"
                   Hidden="TRUE"
                   ImageUrl="/_layouts/15/images/stbs.png?rev=23"
                   Description="A blank site for you to customize
                             based on your requirements."
                   DisplayCategory="Collaboration"
                   AllowGlobalFeatureAssociations="False" >
    </Configuration>
    <Configuration ID="2"
                   Title="Document Workspace"
                   Hidden="TRUE"
                   ImageUrl="/_layouts/15/images/stdw.png?rev=23"
                   Description="A site for colleagues to work together on a document.
                   It provides a document library for storing the primary document
                   and supporting files, a tasks list for assigning to-do items,
                   and a links list for resources related to the document."
                   DisplayCategory="Collaboration" >
    </Configuration>
 </Template>

Figure 11-2 shows the template selection box that is displayed when a new subsite is created.

Figure 11-2. The template selection box as displayed when a new subsite is created

Now that we have discussed the webtemp file, we can move on to the ONET.xml file. The ONET.xml file serves as the top-level manifest for a site definition. This manifest file is used to define provisioning instructions that activate features and create site elements. ONET.xml files are deployed to a subfolder of the TEMPLATESiteTemplates folder. Each site definition has its own dedicated subfolder. The name of this subfolder matches the name of the site definition in the webtemp*.xml file. The ONET.xml file for the Team site and Blank site, for instance, is deployed to the TEMPLATESiteTemplatesSTS folder.

Let’s examine the contents of the ONET.xml file that serves as the manifest for the STS or Team Site site definition. The basic structure of the ONET.xml file includes a top-level Project element, which contains several child elements such as NavBars, ListTemplates, DocumentTemplates, Configurations, Modules, and ServerEmailFooter:

<Project
  Title="$Resources:onet_TeamWebSite;"
  Revision="2"
  ListDir="$Resources:core,lists_Folder;"
  xmlns:ows="Microsoft SharePoint"
  UIVersion="4">

  <NavBars />
  <ListTemplates />
  <DocumentTemplates />
  <Configurations/>
  <Modules />
  <ServerEmailFooter/>

</Project>

The NavBars node defines the set of navigation bars that are created when a new site is provisioned. The NavBars element inside the STS site definition has been written to create several navigation bars that are used by the top link bar and the Quick Launch bar:

<NavBars>
  <NavBar Name="$Resources:core,category_Top;" ID="1002" />
  <NavBar Name="$Resources:core,category_Documents;" ID="1004" />
  <NavBar Name="$Resources:core,category_Lists;" ID="1003" />
  <NavBar Name="$Resources:core,category_Discussions;" ID="1006" />
</NavBars>

Note that these NavBar elements are based on well-known ID values. The NavBar element with an ID of 1002 is used to create the navigation bar used by the top link bar. The NavBar elements with IDs of 1004, 1003, and 1006 are used to create dynamic collections of navigation nodes that are displayed in the Quick Launch bar. For example, the NavBar element with an ID of 1004 creates a dynamic collection of navigation nodes that link to document libraries that have been created, with the option to display them on the Quick Launch bar. If the NavBar elements are omitted, some navigation will still be displayed in the site, but it won’t be possible to adjust the navigation by using the user interface.

The Configurations section of the ONET.xml file contains a child Configuration element for each supported configuration. This is what makes it possible for a single ONET.xml file to be used to provision several types of sites. The ONET.xml file in the STS site definition defines three separate Configuration elements for creating team sites, blank sites, and document workspace sites:

<Project>
  <Configurations>    <!-used to create team sites -->
    <Configuration ID="0" Name="Default" />      <!-used to create blank sites -->
    <Configuration ID="1" Name="Blank" />        <!-used to create document workspace sites -->
    <Configuration ID="2" Name="DWS" />
  </Configurations>
</Project>

A Configuration element contains attributes such as ID, Name, and MasterUrl. A Configuration element also contains child elements such as Lists, Modules, SiteFeatures, and WebFeatures, which are used to create site elements and activate features:

<Configuration ID="0" Name="Default"
               MasterUrl="_catalogs/masterpage/seattle.master">
  <Lists />
  <Modules />
  <SiteFeatures />
  <WebFeatures />
</Configuration>

The Configuration element for a team site contains a Lists element that creates the Documents document library:

<Lists>
  <List FeatureId="00BFEA71-E717-4E80-AA17-D0C71B360101"
        Type="101"
        Title="$Resources:core,shareddocuments_Title_15;"
        Url="$Resources:core,shareddocuments_Folder;"
        OnQuickLaunch="TRUE"
        QuickLaunchHeading="TRUE" />
</Lists>

The Configurations section contains a Modules element that is used to reference Module elements. For example, the Configuration element for a team site includes a Modules element that references a Module named Default:

<Modules>
  <Module Name="Default" />
</Modules>

Although Module elements are referenced inside the Configurations element, they are actually defined in a Modules element that is nested directly inside the top-level Project element. A Module element can contain a File element that creates a Web Part page and can optionally populate it with Web Part instances. The STS site definition contains a Module element named Default, which is referenced by the Configuration element for a team site. This Module element provisions a home page for a new team site named default.aspx and adds a link to the top link bar:

<Module Name="Default" Url="" Path="">
  <File Url="default.aspx" NavBarHome="True">
    <NavBarPage Name="~siteTitle" Url="~site" ID="1002" Position="Start" />
    <NavBarPage Name="~siteTitle" Url="" ID="0" Position="Start" />
  </File>
</Module>

The last two items in an ONET.xml file that are important to discuss are the two elements inside the Configuration element named SiteFeatures and WebFeatures. These two elements contain Feature elements whose purpose is to activate specific features during the site provisioning process. For example, the SiteFeatures element for the team site configuration activates two site collection–scoped features that add support for the standard SharePoint Foundation Web Parts and the Three-State Workflow template:

<SiteFeatures>
  <!-- BasicWebParts Feature -->
  <Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />
  <!-- Three-State Workflow Feature -->
  <Feature ID="FDE5D850-671E-4143-950A-87B473922DC7" />
</SiteFeatures>

The WebFeatures element for the team site configuration activates five site-scoped features that add support for the basic functionality of a team site, such as collaboration list types and a standard wiki library named SitePages:

<WebFeatures>
  <!-- TeamCollab Feature -->
  <Feature ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" />
  <!-- MobilityRedirect -->
  <Feature ID="F41CC668-37E5-4743-B4A8-74D1DB3FD8A4" />
  <!-- WikiPageHomePage Feature -->
  <Feature ID="00BFEA71-D8FE-4FEC-8DAD-01C19A6E4053" />
  <!-- SiteNotebook Feature -->
  <Feature ID="F151BB39-7C3B-414F-BB36-6BF18872052F" />
  <!-- Getting Started List instance -->
  <Feature ID="4AEC7207-0D02-4f4f-AA07-B370199CD0C7" />
  <!-- MDS -->
  <Feature ID="87294C72-F260-42f3-A41B-981A2FFCE37A" />
</WebFeatures>

Because of the link that will always exist between the site and the site definition, changing a site definition after it has been used to create sites is not supported. It is never supported to adjust out-of-the-box SharePoint files, so adjusting the out-of-the-box site definitions is not supported even if they haven’t been used to create sites. If you need a new version of an existing site definition, you can either create a new site definition and hide the old one, or you can use feature stapling to add features and thus functionality to a site that is created based on the site definitions.

A feature can be used to attach one or more features to a configuration of a site definition through a technique known as feature stapling. For example, instead of creating a custom site definition, you can elect to create a custom feature to extend configurations from a standard site definition. For example, you can create a feature to staple the MainSite feature to the Team Site configuration.

To staple a feature to a configuration such as Team Site, you must create a second feature to associate the feature to be stapled with one or more configurations. Feature stapling is achieved by adding a FeatureSiteTemplateAssociation element that contains an Id attribute specifying the feature that is being stapled and a TemplateName attribute specifying the target configuration. The following example demonstrates stapling the MainSite feature to the Team Site configuration by using the feature’s ID and the name and configuration ID for Team Site:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <FeatureSiteTemplateAssociation
    Id="edcdcd75-dff2-479d-ac32-b37f8fa9d459"
    TemplateName="STS#0" />
  </Elements>

The purpose of feature stapling is to activate features automatically when a new site is created. After a feature that staples other features has been activated, SharePoint automatically activates the stapled features when new sites are created. However, it is important that you know how the scope of a feature that staples other features affects the provisioning behavior of SharePoint.

The activation scope of the feature performing the stapling must be higher than the features being stapled. For example, a feature that is activated at the site collection scope can only staple features that activate at site-level scope. A feature that activates at the web application scope can staple features that activate at site-level scope or at the site collection scope. A feature that activates at the farm scope can staple features that activate at any of the other three scopes. If you define a feature that activates at the web application scope, it provides a quick and easy way to automate the activation of its stapled features within every new team site that is created in the target web application. Going one step further, you can associate stapling a feature to the main configuration of the GLOBAL site definition. This technique makes it possible to staple a feature to all new sites, as opposed to only sites created from a specific configuration:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <FeatureSiteTemplateAssociation
    Id="edcdcd75-dff2-479d-ac32-b37f8fa9d459"
    TemplateName=" GLOBAL" />
</Elements>

This technique is powerful because it allows you to activate specific features on any type of site created within a farm. The one caveat here is that the configuration for blank sites is configured to ignore any features stapled to the GLOBAL site definition. This is done by setting the AllowGlobalFeatureAssociations attribute, that is added to the Configuration for the blank site in the webtemp.xml file, to False. Also, a feature stapled to a certain site definition will be stapled to that site definition in the entire farm. This might not always be appropriate.

Another downside of using stapled features is that it is not possible to define the order in which they are activated. When a site is provisioned, the features that are stapled to the site will be activated in a random order. This means that if one stapled feature requires another stapled feature to be activated first, you will have to use feature dependencies, or design your features in a different way.

When a site is provisioned by using a site definition, several steps are executed. We already discussed the first two. The full list is:

From this list, you can note a couple of things that might cause problems. The fact that site collection–scoped features are always activated before site-scoped features and that features that are listed in the ONET.xml file are always activated before stapled features means that you have to take this into account when designing your features. The good news is that this behavior is predictable. So all it takes it some proper planning up front to avoid problems. Another common challenge is that all features are activated before the pages that are defined in the Modules element of the ONET.xml are created. This means that if you create a feature to modify one of these pages (for instance, if you add a Web Part to the home page), the feature will be activated before the page exists and you will be trying to add Web Parts to a nonexistent page. To avoid this, it is a best practice to create your pages by using a separate feature. That way you can make sure that the page gets created before it is modified.

Technically it is possible for you to create your own custom site definitions. However, you are advised not to create custom site definitions, because site definitions cannot be removed after they have been used—they will need to exist as long as those sites exist, even when the environment is updated to a new version of SharePoint, which adds significant extra complexity to upgrades. Custom site definitions will always have to be deployed by using farm solutions, because that is the only way to deploy files to the file system and thus the only way to deploy the webtemp*.xml and the ONET.xml file to the right file locations. This means that if you ever want to move to a cloud-hosted service such as Microsoft Office 365, you will not be able to deploy your own custom site definitions, and you won’t be able to move your sites to that service. You will have to migrate the data from that site to new sites in the cloud-hosted environment.

So although the SharePoint Developer Tools have a predefined element called Site Definition, which you can use to create a custom site definition, you shouldn’t use it. There is really only one scenario that might require you to create custom site definitions. In all other scenarios, it is better to create a custom web template or use custom code to adjust your sites after provisioning them based on an out-of-the-box site definition. Neither of these approaches will work if you are creating a Variations Hierarchy. A Variations Hierarchy is mainly used for creating multilingual web content management sites. If the same pages with the same content have to be published in multiple languages, you might want to use Variations for this. If you want to create custom templates for the sites used in the Variations Hierarchy, you will have to create custom site definitions. In all other cases, you should not create custom site definitions.

Next open up the elements.xml file and add a WebTemplate element to it and fill in some of the attributes. When you add a WebTemplate element to an elements.xml file, you will notice that you can choose from a long list of properties. For this example, you will only use some of the basic and mandatory ones. The first one to fill in is the Name attribute. The name of the WebTemplate element has to be an exact match to the name of the EmptyElement. In this case, that is ProjectSite. The next properties are Title and Description. These are what users will see in the user interface when they are creating a site, so they should be something that a user can understand. The DisplayCategory is the tab of the template selection box that the template will show up in. You will choose WingtipToys and create your own tab, but you could have also used Collaboration to add it to the existing Collaboration tab.

The next three attributes are linked together: BaseTemplateID, BaseTemplateName, and BaseConfigurationID. These properties are used to link the web template to a site definition. You saw earlier that the SPWeb has three properties—the WebTemplateName and the WebTemplateId that store the site definition that was used to create the site, and Configuration, which stores the ID of the configuration that was used. Even when a web template is used to create a site, SharePoint still requires a value for each of these properties. You will specify these values through the values that you assign to the BaseTemplateID, BaseTemplateName, and BaseConfigurationID attributes. The values are just for reference; the site definition and configuration that you select aren’t actually used when a site is created. Only the information from your web template is used. You should still select a site definition and a configuration that are relatively similar to the template you are creating. After the site has been created for SharePoint, it will seem like the site was created by using the specified site definition, and the changes between the site definition and what the site actually looks like are made afterward. Though there is no requirement for the site definition and the configuration to be similar to what you’re creating, it is less likely to cause problems in the future if the selected site definition doesn’t deviate too much from what’s specified in the web template. In this example, you will use the Team Site template as the base. The elements.xml contents are show in Example 11-1. After the site has been created, it has no reference to the web template that was used to create it. The only reference the site has is to the site definition and configuration that you specified. This means that you can safely change or even remove a web template after it has been used to create sites, making it a lot easier to maintain and a lot more flexible than site definitions.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <WebTemplate BaseTemplateID="1"
               BaseTemplateName="STS"
               BaseConfigurationID="0"
               Name="ProjectSite"
               Title="WingtipToys Project Site"
               Description="Use this template to create
                            a Wingtip Toys project site"
               DisplayCategory="WingtipToys">
  </WebTemplate>
</Elements>

The next file to create is an ONET.xml file. The ONET.xml file of a web template is very similar to that of a site definition, and because of that, the easiest way to start is by copying the ONET.xml file of a site definition into your empty element. Copy the ONET.xml of the standard Team Site definition from the TEMPLATESiteTemplatesstsxml folder in the SharePoint root directory. If you copy files into your project this way, you always have to check the deployment type of the file by selecting the file in Solution Explorer and scrolling to the bottom of the properties pane. If the deployment type is set to No Deployment, you have to adjust it so that it is set to ElementFile, as shown in Figure 11-3.

Figure 11-3. Solution Explorer and the properties pane showing the web templates solution and ONET.xml properties

Though the ONET.xml file of a web template is similar to that of a site definition, they are not the same. Some elements that are used in a site definition’s ONET.xml file are not supported in the ONET.xml of a web template. Elements that are not supported are:

Modules are used to add pages to your site. We already discussed earlier that it is a best practice not to use the Modules element, but to use a feature instead, so this limitation won’t have much of an impact.

The FileDialogPostProcessor and ExternalSecurityProvider elements are hardly ever used, so there will be very few people affected by the fact that they can’t use these elements in a web template. Although the ServerEmailFooter is used in, for instance, the out-of-the-box team site, its use isn’t critical to the workings of the site definition, so this element won’t be missed too much either.

The ONET.xml file can also only contain one configuration when you are using web templates. You saw that for site definitions it is possible to specify several configurations in a single ONET.xml file, but you can’t use this technique when using web templates. Each type of site will need to have its own web template. This is not a problem, but something to keep in mind. The ID of the configuration in the ONET.xml file must match that specified in the BaseConfigurationID attribute in the elements.xml file.

Another “limitation” of web templates is that you can’t use feature stapling with them. However, the reason that feature stapling is so attractive when you are using site definitions is because you can use it to adjust the behavior of the site definition without modifying the definition itself, which is not supported after the site definition has been used to create sites. Web templates can be modified after they have been used to create sites, so instead of using feature stapling you can simply add all features you want activated on the site to the SiteFeatures and WebFeatures elements of the ONET.xml file. This way you can not only modify the features you want activated on the sites you are creating, you can also specify the order in which they are activated.

The order in which sites are provisioned by using a web template is:

If you add a lot of features to the SiteFeatures element of the ONET.xml file, it is worth paying attention to step 3 of the site provisioning process. If users are trying to create a subsite and the features specified in the SiteFeatures element aren’t activated on the site collection site, creation will fail with an error. In some cases, this can be expected behavior and no problem at all. But if you are creating a new version of an existing web template, and after you have deployed the new template users can’t create subsites anymore by using the same template they used to create the site collection, they might get annoyed. And they’d have a point. You can avoid this, especially when updating existing web templates, by not adding features to the SiteFeatures element. If you still have to add new site collection–scoped features to the web template, you can use a trick. You can create a web-scoped feature, and in the FeatureActivated event receiver of that feature run a little bit of code to activate the site collection–scoped feature. Before you write code like this, make sure that activating the site collection–scoped feature won’t cause a problem on any existing sites, because you will no longer have control over exactly where the feature is activated.

After you have added the WebTemplate element and its attributes to the elements.xml file and have stripped the ONET.xml file of the elements that you cannot use in web templates, you have the absolute necessities for your web template. The only thing left to do before you can deploy is to determine the scope of the feature. You can choose whether to set the scope of the feature to farm or site. You cannot use web application–scoped or web–scoped features to deploy web templates.

If you use a farm-scoped feature to deploy a web template, the web template can be used to create sites throughout the SharePoint farm. If you deploy a web template this way, it will behave exactly like a site definition would. From the user interface it will be impossible to tell the difference between the web template and a site definition. You can use the template to create a site collection from Central Administration, and you can use the template to create subsites from every site in the environment.

If you use a site collection–scoped feature, the template will only be available on sites where you activate the feature. If you want to create subsites based on the web template, you have to browse to the site settings page and click the Site Collection Features link in the Site Collection Administration area of the page. You should find your feature on this page. If you activate it, you will make the template available for users to create subsites based on it. If you want to use the web template to create a site collection, but you deploy the template by using a site collection–scoped feature, you can still do this—it will just take a couple more steps. To do this, first go to Central Administration and browse to the Application Management page. From there, click Create Site Collections. As shown in Figure 11-4, you can fill in a title and URL and optionally a description. In the template selection box, select the Custom tab and < Select Template Later >. Next, select a site collection administrator, and click OK to create the site.

Figure 11-4. Creating a site collection without selecting a template

Creating a site collection without selecting a template is relatively quick because the site won’t be fully provisioned yet. When the site is ready, you can click the link to browse to it. This will take you directly to the template selection page of the site. However, because the feature isn’t enabled yet, you can’t select your template. From the template selection page, you can browse to the site settings and site collection features pages and activate your feature. If you now try to browse to the home page of the site, SharePoint will take you back to the template selection page on which you can now select your web template. You can click OK to complete the provisioning of the site. SharePoint will come back to ask you whether to use existing SharePoint groups for the Visitors, Members, and Owners groups, or whether to create new ones. Because the existing ones were just created when you provisioned the first part of the site, it makes sense to stick to these and create a new site of groups.

If you use a farm-scoped feature to make the web template available in your SharePoint farm, you will have to use a farm solution to deploy the web template and the feature. However if you use a site collection–scoped feature, you can use a sandboxed solution to deploy the web template. Using a sandboxed solution to deploy a web template is particularly appealing if you are using a cloud-hosted environment such as Office 365, or if you only want to make the template available to certain people or even just to yourself. You could simply upload the sandboxed solution to the site collection Solution Gallery and activate the feature to make the template available on a particular site. If you want to create a site collection by using the template, you can follow the steps described previously and click the Solution Gallery link, as shown in Figure 11-5, to upload your solution before activating the site collection–scoped feature.

Figure 11-5. Selecting a web template on the template selection page in the site collection

Because there is no link between a site after it has been created and the web template that was used to create the site, it is a best practice to store this information about the web template when the site is created. This can easily be done by creating a web-scoped feature that will be activated as the last feature in the WebFeatures element in the ONET.xml file. The feature can contain an empty element that adds a couple of properties to the property bag of the site. You can add the properties by adding the PropertyBag and Property elements in the elements.xml file of the empty element. Storing information about the web template that was used to create the site makes it possible to identify sites and versions of sites later on, perhaps for grouping sites together, upgrading specific sites to new a new version of SharePoint, or maybe writing custom code to make the same changes to all sites of the same type or version:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <PropertyBag ParentType="Web">
    <Property Name="WingtipToys.WebTemplate" Type="string" Value="ProjectSite" />
    <Property Name="WingtipToys.WebTemplateVersion" Type="string" Value="1.0.0.0"/>
    <Property Name="WingtipToys.WebTemplateFeature" Type="string" Value="c1dd0ae6-e166-4dec-91eb-3eeacfc38257"/>
  </PropertyBag>
</Elements>