HOW TO: Create a custom site definition in SharePoint 2010

By
Todd Baginski
– November 2, 2009

 

This article describes how to create a custom site definition in SharePoint 2010.  The process to create a custom site definition has not changed much since the last version of SharePoint, the only differences are the directory names and some of the XML in the WEBTEMP files.  See this blog post if you would like to see how this is done in WSS 3.0 / MOSS 2007.

Site Definition basics

Site definitions are located in the following folder on the SharePoint server: 

C:Program FilesCommon FilesMicrosoft Sharedweb server extensions14TEMPLATESiteTemplates

Each site definition has its own sub directory under this folder.

Inside each site definition sub directory the .aspx pages for the various web pages and lists that make up the site definition are stored.  Some of the new site definitions that come with SharePoint 2010 also include image files in these subdirectories.  The ONET.XML file specifies the various configurations and modules the site definition is made up of.  It is stored inside the XML subdirectory inside each site definition sub directory.

*Note: I think it is interesting that the SDK refers to Site Templates as the .stp files that are generated when you save a site as a template from the web UI, and the SDK refers to file based site templates as site definitions – yet this directory is named SiteTemplates.  This has been the case for a couple of versions now so I don’t think we’ll see it change in the future.

Site definitions are registered with SharePoint and made available via the WEBTEMP<NAME OF SITE DEFINITION>.XML file.  Theoretically, you could register a site definition with SharePoint with one of the out of the box WEBTEMP XML files, however this could introduce problems when service packs or newer versions of the product are released.  It is considered best practice to create your own WEBTEMP XML file to register your custom site definitions.

WEBTEMP XML files are located in the following folder on the SharePoint server: 

C:Program FilesCommon FilesMicrosoft Sharedweb server extensions14TEMPLATE1033XML

Creating a custom Site Definition in SharePoint 2010 – Manual Approach

Step 1: Clone an existing Site Definition

Step 2: Create the WEBTEMP XML fragment file to register the site definition with SharePoint

Step 3: Reset the application pool

Step 4: Create a site based on the custom site definition

Step 1: Clone an existing site definition

Navigate to the following directory on the SharePoint server in Windows Explorer:

C:Program FilesCommon FilesMicrosoft Sharedweb server extensions14TEMPLATESiteTemplates

Copy the STS directory and paste it back into the same directory.  (You can copy any of the existing site definitions and use them as a baseline to create your own.)
 

Rename the Copy of STS directory to SAMPLE

Step 2: Create the WEBTEMP XML fragment file to register the site definition with SharePoint

Create a file called WEBTEMPSAMPLE.XML in the following directory:

C:Program FilesCommon FilesMicrosoft Sharedweb server extensions14TEMPLATE1033XML

Put the following XML into the WEBTEMPSAMPLE.XML file:

<?xml version="1.0" encoding="utf-8"?><!-- _lcid="1033" _version="14.0.4514" _dal="1" --><!-- _LocalBinding --><Templates xmlns:ows="Microsoft SharePoint"> <Template Name="SAMPLE" ID="10001">    <Configuration ID="0" Title="Sample Team Site" Hidden="FALSE"         ImageUrl="/_layouts/images/stts.png" Description="A sample team site."         DisplayCategory="Custom Site Definitions" >    </Configuration>    <Configuration ID="1" Title="Sample Blank Site" Hidden="FALSE"         ImageUrl="/_layouts/images/stbs.png" Description="A sample blank site."         DisplayCategory="Custom Site Definitions" AllowGlobalFeatureAssociations="False" >    </Configuration>    <Configuration ID="2" Title="Sample Document Workspace" Hidden="FALSE"         ImageUrl="/_layouts/images/stdw.png" Description="A sample document workspace."         DisplayCategory="Custom Site Definitions" >        </Configuration> </Template> </Templates>

*Note: The DisplayCategory attribute of the <Configuration> element dictates which tab the configuration will appear on in the create new site web dialog. You can create your own tabs by putting your own values in this attribute (like I have done in the XML above and displayed in the screenshot below).  The screenshot below demonstrates how the Configuration element’s attributes (inside the WEBTEMP file) map to the create a site dialog.
 

WEBTEMP Configuration element attribute mapping diagram.

Save the file.

Step 3: Reset IIS

Open a command prompt on the SharePoint server

Type in the command: iisreset

Wait for IIS to reset

Step 4: Create a site based on the custom site definition

Open Internet Explorer

Navigate to a SharePoint site on the server where you performed the steps above.

Click the Site Actions menu

Select New Site

Click the Custom Site Definitions tab on the left side of the create a site dialog to see the new site templates you registered with the SAMPLE site definition. 

Select one of the sample site templates you created.

Enter a title and URL

Click the Create button and your new SharePoint site is created.

Creating a custom Site Definition in SharePoint 2010 – Visual Studio 2010 Approach

Visual Studio 2010 simplifies the process by providing a project type specifically tailored for this purpose.  To create a custom site definition with Visual Studio 2010 first create a new Site Definition project.  See the screenshot below for reference.

Creating a Site Definition project type in VS 2010.

Then set the path to the SharePoint site where you would like to deploy the site definition.

Set the site where you would like to deploy the custom site definition.

Once the project is created, you can see all the files needed to support a custom site definition in the Solution Explorer.

Solution Explorer showing the files which make up the Site Definition project.

After you make edits to the files all you need to do is press F5 and the custom site definition is packaged into a WSP and deployed to the SharePoint server.  All that is left to do is to create a new site based on the custom site definition to verify it works properly. 

How the custom SharePoint site template appears when made from the out of the box VS 2010 Site Definition project type.

Here you can see what the site template looks like when you use the out of the box Visual Studio 2010 Site Definition project type.

SharePoint site made from out of the box VS 2010 Site Definition project type.

Wrap Up

There are several blog posts which discuss when and why you may want to create a custom site definition.  Some folks are of the opinion it is something you should never do, other folks believe it makes sense to do it in certain situations.  Personally, I believe they are a good solution when you need a new ID to staple features to.

Tags: , , , , ,