Providing your customers with packages of features that you activate selectively is a great way to extend Microsoft SharePoint to cover the requirements of most projects. Some situations, however, require a more robust solution: creating a ready-to-go site with predefined structure and content from the ground up, starting from a custom template.
For example, suppose you have to create an extranet site collection to host a set of websites, where each site represents the private extranet of a customer. Because every customer’s site will have a common set of contents and features (for example, a library of orders, a library of invoices, and a discussion area), you might be tempted to base each site on one of the site models SharePoint provides for common scenarios, such as team site, blog, or community site. Don’t do it. These templates are very broad, and you’d go crazy trying to manually provision the content using features. It’s better to build your own new web template that defines the structure of a customer’s extranet website, and then create every site instance starting from that template.
In this chapter, you will learn how to create, deploy, and manage these more complex site models.
SharePoint 2013 provides four main techniques for provisioning features and reusable site models:
Site definitions
Feature stapling
Site templates
Web templates
Before you can put them to work, you need to understand their differences and individual strengths.
A site definition is a site model defined on the file system and stored in the folder SharePoint15_RootTEMPLATESiteTemplates of every front-end server. Saving files on the file system is an ancient habit that requires direct access to the servers in your server farm. Thus, it is not suitable for Microsoft Office 365 or SharePoint Online.
Feature stapling is a technique that enables you to customize existing site definitions by adding custom features to extend the site definition. The new features will also be included on all the new sites created using that specific site definition. Bear in mind, however, that feature stapling cannot be applied to already created sites. Once you deploy a site definition on the file system, changing its configuration is unsupported. This chapter will not cover feature stapling, because it is available mainly for backward compatibility and is not available in Office 365.
More Info
For further details about feature stapling, you can read Vesa Juvonen’s blog post at http://blogs.msdn.com/b/vesku/archive/2010/10/14/sharepoint-2010-and-web-templates.aspx.
A site template is an exported snapshot of an already existing site instance, with or without its content. You can use a site template, which is basically just a WSP package, to replicate a site instance from one environment to another, as long as the base site definition is available on the target environment, too. In addition, you can import site templates into Microsoft Visual Studio 2012 to create custom template projects. To save a site template from an already existing site instance, simply click Save Site As Template in the Site Actions menu group on the Site Settings page. The one exception, however, is that a site template cannot be created from a site in which publishing features are enabled, so it’s only usable in team and collaboration sites.
Available since SharePoint 2010, a web template is a specific WebTemplate feature that you can create using Microsoft Visual Studio 2012 and provision using a sandboxed solution. A web template enables you to define a custom site model for future reuse. You can deploy web templates at the site collection level, through a sandboxed solution, or at the farm level using a full-trust WSP solution package. Because web templates can use a sandboxed solution for deployment, you can use them against Office 365 and SharePoint Online, too.
When creating custom site models, often a good way to start is by simply extending one of the site definitions provided in SharePoint 2013. To choose the right model to get started with, though, you need to know what the models are. The native site definitions are stored in the file system of the servers, specifically in the SharePoint15_RootTEMPLATESSiteTemplates folder. There, you will find a subfolder for every base site definition or group of site definitions. Whenever you create a new site collection or a new subsite under an existing site collection, SharePoint provides a list of all the available site templates, site definitions, and web templates from which you can choose the model to use for your new site. Figure 13-1 shows the standard page for choosing the template for a new subsite.
Behind the scenes, SharePoint loads the list of available models, reading all the available files with the prefix webtemp*.xml found in the SharePoint15_RootTEMPLATEIdCultureXML folder, where IdCulture corresponds to the currently selected language in the Create Site window. Regarding the IdCulture argument, 1033 stands for English (United States), 1040 stands for Italian, and so forth. The webtemp*.xml files enumerate one or more site models, together with their name, configuration, and folder. In The content of the standard webtemp.xml file, set for English, the content of the main, standard webtemp.xml file is set for the English language.
The file provides a list of Template items, each with a Name attribute and an optional SetupPath attribute. Each Template element is the parent of one or more Configuration elements, which provide a custom configuration for that specific template. For example, the STS template is available in three configurations: STS#0, STS#1, and STS#2. The syntax of {TemplateName}#{Configuration ID} is common in SharePoint. Table 13-1 lists the main available site definitions with the corresponding configurations, described as they are in SharePoint.
Table 13-1. Some of the main native site definitions available in SharePoint 2013
Title | Base definition | Configuration | Description |
Team Site | STS | 0 | A site for teams to quickly organize, author, and share information. |
Blank Site | STS | 1 | A blank site for you to customize, based on your requirements. |
Document Workspace | STS | 2 | A site for colleagues to work together on a document. |
Central Admin Site | CENTRALADMIN | 0 | A site for hosting the SharePoint Central Administration (SPCA) site. This template is hidden. |
Blog | BLOG | 0 | A blog site. |
Document Center | BDR | 0 | A site to centrally manage documents in your enterprise. |
Records Center | OFFILE | 1 | A record management site. |
Business Intelligence Center | BICenterSite | 0 | A site for presenting Business Intelligence Center. |
Personalization Site | SPSMSITE | 0 | A site for delivering personalized views, data, and navigation from this site collection into My Site. |
Publishing Portal | BLANKINTERNETCONTAINER | 0 | A starter site hierarchy for an Internet-facing site or a large intranet portal. |
Enterprise Wiki | ENTERWIKI | 0 | A site for publishing knowledge that you capture and want to share across the enterprise. |
Enterprise Search Center | SRCHCEN | 0 | A site for delivering the enterprise search center. |
Basic Search Center | SRCHCENTERLITE | 0 | A site for delivering a basic search center. |
Visio Process Repository | Visprus | 0 | A site for teams to quickly view, share, and store Microsoft Visio process diagrams. |
The availability of some of these site definitions depends on your SharePoint 2013 license. For example, the Enterprise Search Center site requires you to have SharePoint Server 2013 Enterprise licensed and installed. By default, SharePoint 2013 includes a few other site definitions, but they are hidden and available only for backward compatibility. When you create a site instance by code, you can reference the site definition using the syntax {TemplateName}#{Configuration ID}. For example, STS#0 means Team Site, BLOG#0 means Blog Site, and so forth.
The webtemp*.xml files are just directories of site templates configurations. The actual configuration is included in an XML file named ONET.XML, which is located in the XML subfolder of every site definition. For example, consider the group of templates defined in the STS site definition. The corresponding ONET.XML file declares some common configuration items, such as the document templates, the list templates, the navigation bar groups, and the custom pages and Web Part pages to deploy. Then it defines some Configuration elements, each one corresponding to a specific configuration for the STS template. The ONET.XML file for the standard STS site template defining STS#0 shows the ONET.XML file of the STS template, defining the configuration for STS#0.
The configuration declares the list instances that will be created in the target site, the modules that will be provisioned (the pages that will be created), and the site-level and web-level features that will be activated. Additionally, consider that all of the site definitions inherit from a common and global definition named GLOBAL, which is defined in the SharePoint15_RootTEMPLATEGLOBAL folder. There, in the ONET.XML file in the XML folder, are defined all the base list templates and list types used by the other site definitions.
Assuming you are working on-premises, defining your own site definitions is simple. To manually create a custom site definition, copy an existing folder and change the ONET.XML file to select the list definitions to use for creating list instances, the modules to provision, and the features to activate. Next, define a custom webtemp*.xml file and copy it into the proper folder within SharePoint15_RootTEMPLATESIdCultureXML. You will be able to use the new definition after you recycle the application pool of your target web application, or after you execute IISRESET, which resets the entire Internet Information Services (IIS) environment.
Important
Do not change any of the out-of-the-box site definitions, because changing such files and folders would lead you to an unsupported and probably unstable environment.
Try an example: copy the SharePoint15_RootTEMPLATESSiteTemplatesENTERWIKI folder and name it MYENTERWIKI. Then open the ONET.XML file in the XML subfolder of MYENTERWIKI and change the Configuration section as you see fit. To add a Shared Documents list to the standard Enterprise Wiki site, for instance, add a List element to the Lists element of the Configuration tag in the ONET.XML file, like so:
<List FeatureId="00BFEA71-E717-4E80-AA17-D0C71B360101" Type="101" Title="$Resources:core,shareddocuments_Title_15;" Url="$Resources:core,shareddocuments_Folder;" OnQuickLaunch="TRUE" />
The values for the FeatureId and Type attributes are those corresponding to the base list definition of the document library, as it is declared in the DocumentLibrary feature in the SharePoint15_RootTEMPLATESFEATURESDocumentLibrary folder.
To make the site template available for creating new site instances, you need to define a custom webtemp*.xml file; for example, call it webtempcustom.xml and copy it into the SharePoint15_RootTEMPLATESIdCultureXML folder. The source code of the custom webtempcustom.xml file for the custom MYENTERWIKI site definition shows the source code of such a file.
Notice the ID value of 10001 used in the Template definition. In custom site templates, you should use values equal to or greater than 10000 for the ID attribute, to avoid overriding the IDs of native templates.
To use your new site definition named MYENTERWIKI#0, you now need to recycle the application pool of the target web application where you want to create a site based on this template. You can also reset IIS by invoking the IISRESET command to make the template available on all the web applications. Recycling the application pool or resetting the IIS process is required because SharePoint loads the site templates once at startup and then caches them for performance reasons. Figure 13-2 displays the new site template available in the list of templates.
Figure 13-2. The standard page for choosing the template for a new subsite, with the new custom site definition.
Figure 13-3 illustrates the home page of a site created using the new My Wiki Site template, with the Shared Documents library at the top of the page.
To include a list view of the document library on the home page, you need to add a View element inside the Module element that is provisioning the Default.aspx page, in the ONET.XML file of your site definition. You’ll learn more about this last topic in the next section.
Manually creating site definitions is simple, but it is not always the best solution, nor is it considered a best practice. For example, the technique works only in an on-premises farm, and it requires great effort if you have many servers in a farm, because you must copy the files and folders to each server to use your custom site definition. Although you were able to use features already available in the farm for the My Enterprise Wiki example, quite often you will need to define a custom site template to take advantage of custom features and custom contents, which you need to deploy together with your site definition. To help you in such cases, Microsoft Visual Studio 2012 provides some item templates for creating a site definition from scratch. Figure 13-4 shows the Add New Item window of Visual Studio 2012, with the proper item template selected.
Figure 13-4. The Add New Item window of Visual Studio 2012 with the Site Definition item template highlighted.
Important
Each time you define a project in Visual Studio, it builds and deploys an assembly. In general, however, a site definition is a codeless solution, unless you do not write custom code to support your custom features or you implement a custom feature receiver. Thus, in case you do not have custom code, you can simply exclude the assembly from being deployed and avoid having an empty assembly deployed on the farm. To exclude an assembly from deployment, you need to set the value of the Include Assembly In Package property for the current project to False using the Visual Studio property grid.
Once you choose the project template, Visual Studio 2012 prompts you with the common window, asking for the target site URL and the type of deployment (farm solution or sandboxed solution). For the site definition, your only choice is a farm solution deployment, because the site definition must be stored on the file system of the farm’s servers. The sandboxed deployment is not available. The template project outline is made up of the minimal contents for defining a site definition: an ONET.XML file, a webtemp*.xml file, and a Default.aspx home page. To define your site definition, you simply need to add features (as you did in previous chapters), package the solution, and then deploy it.
For example, suppose that you want to deploy a new site definition for managing work projects, with a custom list definition, based on a new content type describing a project item and a corresponding list instance of projects. Additionally, you need an XsltListViewWebPart to show the content of that list of projects on the home page (Default.aspx) of the site.
First, you must edit the webtemp*.xml file, providing a name and an ID for the Template element, as well as a value for the attributes Title, Description, and DisplayCategory of the Configuration element. The content of the webtemp*.xml file related to the sample Projects site definition presents the webtemp*.xml file corresponding to the sample project’s site definition.
In The content of the webtemp*.xml file related to the sample Projects site definition, the name of the template is DLPROJECTS, the ID has a value of 10002, and the configuration ID is 0, which means it is the first configuration. So, if you want to reference that site definition configuration by code, you should use the name DLPROJECTS#0.
Because the name assigned to the template is DLPROJECTS, the deployment location for ONET.XML, Default.aspx, and any other file of the site definition will target the folder SiteTemplatesDLPROJECTS. For example, because the ONET.XML file will be deployed in the XML folder of the site definition, its deployment location will be SiteTemplatesDLPROJECTSXml. Visual Studio 2012 will carry this out for you.
Just after defining the webtemp*.xml file, you should work on the ONET.XML file, which is the main schema file for the custom site definition. You could define the Projects list within the ONET.XML file by using the ListTemplate element and a List instance element. Be aware that if you provision data through the ONET.XML file, you will not be able to extend or maintain it over the course of the site’s lifetime. In fact, data provisioned with a site definition cannot be upgraded, and you would need to write custom code of your own to upgrade it. Instead, as you learned in Chapter 3 you could add the content type, list definition, and list instance defining the Projects data structure by using feature elements, which can be upgraded and maintained during the life cycle of your site. (You should already know how to manage this; if not, refer to Chapter 3 and Chapter 4) In addition, if you use features, you can add feature activation directives to the ONET.XML file. For example, suppose you have a feature provisioning a new list instance of projects, based on a custom list definition and a custom content type. The content of the ONET.XML file related to the sample Projects site definition shows a sample ONET.XML deploying that list of projects, using a custom feature and the custom Default.aspx page.
The first thing to notice in the ONET.XML file is the Configuration element, which corresponds to the one defined in the webtemp*.xml file. To use the content defined by your custom provisioning feature, you need to put a Feature element within the WebFeatures element. The feature provisioning the list instance of Project, together with site columns, content types, and list definition, is a web-scoped feature. Additionally, the feature provisions a Module element for the Configuration, referencing one of the available Module elements defined in the Modules section of the ONET.XML file.
The Module element provisions the Default.aspx page and also declares a View element, which includes a Web Part of type XsltListViewWebPart that renders the items of the list of projects, with the path Lists/Projects, into the WebPartZone control with ID CentralZone, defined in the source code of Default.aspx. The source of the Default.aspx page provisioned with the sample Projects site definition illustrates the source code of the Default.aspx page provisioned with the custom site definition.
To deploy the site definition, you can simply select the Deploy command in Visual Studio. I suggest, however, that before you deploy the site definition, you change the deployment configuration from Default to No Activation in the project’s properties, under the SharePoint properties page (see Figure 13-5). This will avoid activating the features in the deployment target site, as well.
After deploying the site definition, you will find its corresponding folder in the SharePoint15_RootTEMPLATESSiteTemplates folder, and you will be able to create new site instances by using the new custom site template. Figure 13-6 displays the new site definition available in the list of creatable site definitions, while Figure 13-7 presents the home page of a site of projects created using the new site definition.
Finally, remember that this technique for deploying custom site templates with Visual Studio is available only on-premises, and you cannot access it within Office 365. In order to create site models suitable for on-premises infrastructure as well as for the cloud, you have to use web templates, which are discussed in the following section.
When you create a new site instance from the UI of SharePoint, you are prompted to select a model, as shown previously in Figure 13-6. In addition to the site definitions you just learned about, the list of available site models contains web templates.
You can create a custom web template by exporting the definition of an existing site instance, with or without its content, and storing the result into the content database as a sandboxed solution. To export an existing site definition, you can use the web browser and navigate to the Save Site As Template page, located under the Site Actions group on the Site Settings page of the current website.
Regardless of how you save the web template, the result will be a WSP package with a feature element specifically introduced in SharePoint 2010 for managing deployment of custom web templates. The corresponding element is the WebTemplate element. To have a look at its structure, you can simply export an existing site instance, save the generated WSP file, and then rename it to CAB. You can then extract the element manifest declaring the WebTemplate feature. The WebTemplate element structure reveals the structure of the WebTemplate element.
The WebTemplate element comprises a set of attributes, which are described in Table 13-2.
Table 13-2. The attributes supported by the WebTemplate element
Attribute name | Description |
AdjustHijriDays | Optional Integer attribute that specifies the number of days to extend or reduce the current month in Hijri (Islamic) calendars used on the target website. |
AlternateCssUrl | Optional Text attribute that specifies the URL for an alternative cascading style sheet (CSS). |
AlternateHeader | Optional Text attribute that provides the name of a custom ASPX page. AlternateHeader defines a custom alternative header for provisioned pages. It should be available in the SharePoint15_RootTEMPLATELAYOUTS folder. |
BaseTemplateID | Required Integer attribute that specifies the ID of the parent site definition. BaseTemplateID contains the value of the ID attribute of the Template element in the webtemp*.xml file that defines the parent site definition. |
BaseTemplateName | Required Text attribute that specifies the name of the parent site definition. BaseTemplateName contains the value of the Name attribute of the Template element in the webtemp*.xml file that defines the parent site definition. |
BaseConfigurationID | Required Integer attribute that specifies the ID of the configuration of the parent site definition. BaseConfigurationID contains the value of the ID attribute of the Configuration element in the webtemp*.xml file that defines the parent site definition. |
CalendarType | Optional Integer attribute that specifies the type of the default calendar type for calendars created on the target website. |
Collation | Optional Integer attribute that specifies the collation to use for the target website. |
ContainsDefaultLists | Optional Boolean attribute that specifies whether the parent site definition contains lists that are defined in the ONET.XML file of the GLOBAL site definition. |
CustomizedCssFiles | Optional Text attribute that specifies custom CSS files. |
CustomJSUrl | Optional Text attribute that provides a custom JavaScript file located in the SharePoint15_RootTEMPLATELAYOUTS folder, which will be executed within the target website. |
Description | Optional Text attribute that specifies a description for the site template. |
DisplayCategory | Optional Text attribute that specifies the category in which the web template will appear in the SharePoint UI for creating a new site. |
ExcludeFromOfflineClient | Optional Boolean attribute that specifies whether the site must be downloaded during offline client synchronization. |
ImageUrl | Optional URL address of the preview image of the model, which is displayed in the SharePoint UI for creating a new site. |
Locale | Optional Integer attribute that specifies the locale ID of the language/culture for the target website. |
Name | Required Text attribute that specifies the internal name of the web template. |
ParserEnabled | Optional Boolean attribute that specifies whether the values of columns in document libraries will be automatically added to documents added to libraries of the target website. |
PortalName | Optional Text attribute that provides the name of the portal associated with the website. |
PortalUrl | Optional Text attribute that specifies the URL of the portal associated with the target website. |
PresenceEnabled | Optional Boolean attribute that specifies whether online presence will be enabled for users of the target website. |
ProductVersion | Optional Integer attribute that specifies the version of SharePoint Foundation used to create the web template. |
QuickLaunchEnabled | Optional Boolean attribute that determines if the Quick Launch area will be enabled on the target website. |
Subweb | Optional Boolean attribute that specifies whether the web template has been created from a child Web site or from the root Web site of a site collection. |
SyndicationEnabled | Optional Boolean attribute that determines if RSS syndication will be enabled on the target website. |
Time24 | Optional Boolean attribute that specifies whether to use the 24-hour format to represents hours. |
TimeZone | Optional Integer attribute that specifies the default time zone for the target website. |
Title | Optional Text attribute that provides the title for the web template. |
TreeViewEnabled | Optional Text attribute that specifies whether the tree view in the left navigation area of pages will be enabled. TreeViewEnabled can only take TRUE or FALSE text values. |
UIVersionConfigurationEnabled | Optional Boolean attribute that specifies whether users can change the UI version of the target website. |
The WebTemplate element feature generated from the sample Projects site definition instance shows an example of a WebTemplate instance, generated by exporting an instance of the sample site for managing projects, which you saw in the previous section.
Note in The WebTemplate element feature generated from the sample Projects site definition instance how the WebTemplate element references its parent site definition (10002, DLPROJECTS#0). In fact, all the three attributes—BaseTemplateID, BaseTemplateName, and BaseConfigurationID—reference the site definition created in the previous section. For this reason, Microsoft does not support changing or removing a site definition after having used it for creating sites. If a referenced site definition is changed or removed, elements such as the WebTemplate feature in The WebTemplate element feature generated from the sample Projects site definition instance will no longer work.
The easiest way to create a WebTemplate feature using Visual Studio is to design the site in the browser. Then you can save it as a template and export the resulting WSP package file, downloading it from the Solution Gallery page of the site collection. From there, you simply need to import the WSP file into Visual Studio 2012, creating a new project of type SharePoint 2013 - Import Solution Package. Now you can choose to define a sandboxed solution, because the WebTemplate feature has been implemented by Microsoft specifically to satisfy the requirement of deploying web templates through sandboxed solutions. Visual Studio will start a wizard that will prompt you to choose the WSP file, and then it will analyze the WSP file and generate a list of items that will be imported. In general, you should accept the proposed list unless you prefer to exclude some content from the web template. When you click the wizard’s Finish button, you will have a new Visual Studio project, complete with a SharePoint package full of features and elements that correspond to the structure of the original site that was used to generate the web template.
To customize the web template project, you can manually open the imported ONET.XML file and change its contents. Figure 13-8 illustrates the interface of Visual Studio while an imported web template is being edited.
Visual Studio makes a lot of features and elements available, but the application needs only a few. The important elements are the list of projects and the custom home page.
Of course, you could also create a project for a web template from scratch, manually adding items to the corresponding folders and creating a project structure like the one shown in Figure 13-8.
It is important to understand that creating a site definition or a web template is an uncommon and complex task. In general, you should create features and solutions to deploy custom data structures and content. Features and solutions are more flexible, modular, and more easily maintained than site definitions or web templates, and they are typically the easiest to define.
If you decide that you need to create a new site model, you will need to choose between creating a site definition or a web template. In such situations, you should factor in the following:
Deploying a web template requires only the proper rights to upload the WSP file into the solution gallery of the target site collection. A site definition requires physical access to the file system of the servers in the farm. In fact, a web template is a sandboxed solution.
A site definition cannot be deployed in a cloud environment (SharePoint Online or Office 365), while a web template can be deployed and used in the cloud.
A web template can be versioned without affecting existing site instances created from a previous version.
When you change the pages defined in a web template, those changes will be available only in new sites, while changing the layout of pages provisioned through a site definition will also affect previously deployed sites. However, Microsoft recommends you not change a site definition after you have used it. Instead, for versioning or changing a site definition, you should use features stapling.
A web template can do almost everything a site definition can. The only capabilities that are not available in a WebTemplate feature are module elements for provisioning pages, custom components to process files or security (FileDialogPostProcessor and ExternalSecurityProvider), ServerEmailFooter configuration for custom e-mail footers (which, however, are not that useful), feature stapling, and variations hierarchy.
Thus, the best practice is to favor web templates and avoid using site definitions, unless you really do need them.
In this chapter, you learned the difference between site definitions and web templates. You also learned how to create your own site definitions, both manually and with Visual Studio, and how to define a web template within Visual Studio 2012. Finally, you were presented with some important characteristics to consider when deciding whether to create a site definition or web template.