Tuesday, January 11, 2011

Site definition?

What is Site Definition?

A set of predefined components needs to be included when a site was created in the SharePoint server. The site definition contains the information of Web parts, Lists, Features, and Navigation Bars to be included in the site.

Site Definition:

By default SharePoint comes with several OOB site definitions which you can select to create your site. In the file system these definitions are available in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates.
Each of this site definition consists a XML folder and a Home page (default.aspx). Some of the site definition will be having some more details about the definition which we will walkthrough in more detail later.
The XML folder of the site definition contains the ONET.XML (Office .NET) file. This file contains the information about all the web parts, Lists, Features and Navigation Bars.
The configuration of this site definitions are defined in another XML file which is available in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\1033\XML folder.
Following is the detail of the XML configuration file and the respective site definitions

Configuration XML file    Site definition 

To create a site definition the first step is to create the “WebTemp” file. The purpose of the webtemp file is to describe to SharePoint the new Site Definition or Site Portal Definition. After the WebTemp file, the Site Definition file should be created, this is known as the ONET.XML file. Each Site Definition contains one or more configurations of lists and features. A site Definition can also point to a Portal Definition. The portal definition uses one or more site definitions. The relationship of files is shown below: 


All the webtemp files are XML files which live in the <12-hive>\TEMPLATES\1033\XML. The webtemp file can be thought of as Meta data or a description of a Site Definition. For example, the file contains the name of the site definition, as displayed in the Create Site page in a site or the Create Site Collection page in Central Administration.
Each Site Definition description is in a <Template> node that contains one or more configuration nodes. The name assigned to a Template must match the name of a directory in the <12-hive>\TEMPLATE\SiteTemplates directory. SharePoint then looks for the ONET.XML file in a subdirectory called XML to find the actual Site Definition. The ID of the Template must be unique across the SharePoint installation. The following is a sample template definition:
<Template Name="SPPR" ID="10856">
    <Configuration ID="0"
         Title="Syrinx Root"
         Description="This site is intended to be the root site collection for a Syrinx portal."

The Configuration declaration can define if the site definition can be used for a site root collection only, a sub web site only or both. This provides a level control on how the site definition can be used, and provides a mechanism to control how certain features are enabled.
In the case of a Portal definition, the webtemp template configuration adds some additional attributes:

<Template Name="SyrinxPortal" ID="10855">
    <Configuration ID="0"
        Title="Syrinx Portal Site"
        Hidden="FALSE"        ImageUrl="/_layouts/1033/images/template_corp_intranet.png"
        Description="This site is the definition of the Syrinx Portal collection."
        ProvisionAssembly="Microsoft.SharePoint.Publishing, Version=, Culture=neutral, PublicKeyToken=71e9bce111e9429c"

The attributes of interest are the ProvisionAssembly, ProvisionClass and ProvisionData. When creating a Portal site the class specified by the ProvisionClass attribute is called in the assembly specified by the ProvisionAssembly. The class is passed the value of the ProvisionData attribute as a parameter. Microsoft provides an implementation of a Provisioning Class. The Microsoft Provisioning Class (MPC) is used to create a Portal Site.
The MPC expects the ProvisionData value to be the path to an XML file, which contains instructions on the sites to create as part of the Portal Definition. This methodology is used to create the Publishing Site, which creates several sub sites. By looking in the PortalWebManifest.xml file specified above, it can be seen that four sites are created, News, Site Directory, Search Center, and Document center. Below is a sample Syrinx Portal Provisioning Data XML file.

<portal xmlns="PortalTemplate.xsd">
    <web name="Syrinx Root"
         displayName="Syrinx Portal Display Name"
         description="Syrinx Watch Portal Description">
        <web name="NorthEast"
             displayName="North East"
             description="North East Site Description">
            <web name="Massachusetts"
                 description="Massachusetts Site Description"/>
        <web name="SouthEast"
             displayName="South West"
             description="South West Site Description"/>

This file declares the top-level site that is to be created, and it uses the SPPR#0 site definition. This is a reference back into the webtemp files; it is referencing a site definition template called “SPPR” and from that definition use configuration “0”, the display name and description of the root level site are overwritten by the values entered by the user when the site is created.  Nested below this site, are two child sites that use configuration 0 from the SPRegion site definition, the North East and South East regional sites. Below the North East regional site is a sub site called Massachusetts, which uses configuration 0 from the SPState site definition.


The onet.xml file contains the actual site definition and is broken in to several sections, navigational areas, list templates, document templates, configurations, modules, components, and server e-mail footer. The MSDN documentation provides an good reference on the structure and contents of an onet.xml file (see http://msdn2.microsoft.com/en-us/library/ms474369.aspx). The best way to create a new onet.xml file is to copy one from the site templates directory which is close to what you need and then modify it to suit your needs. Below is an overview of the sections within the onet.xml file.


Each of the sections – Pictures, Documents etc is defined within the Navigational areas piece of the onet.xml file; this is done within the “Navbars” tag. For example, the following is for the Syrinx Portal State Site.

    <NavBar Name="$Resources:core,category_Top;"
      Body="&lt;a ID='onettopnavbar#LABEL_ID#' href='#URL#' accesskey='J'&gt;#LABEL#&lt;/a&gt;"
    <NavBar Name="$Resources:core,category_Documents;"
      Prefix="&lt;table border=0 cellpadding=4 cellspacing=0&gt;"
      Body="&lt;tr&gt;&lt;td&gt;&lt;table border=0 cellpadding=0 cellspacing=0&gt;&lt;tr&gt;&lt;td&gt;&lt;img src='/_layouts/images/blank.gif' ID='100' alt='' border=0&gt;&amp;nbsp;&lt;/td&gt;&lt;td valign=top&gt;&lt;a ID=onetleftnavbar#LABEL_ID# href='#URL#'&gt;#LABEL#&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&lt;/td&gt;&lt;/tr&gt;"

These declarations have embedded HTML and have special functionality based on the value of the Name attribute and are not covered in detail here.

The Email footer section contains the text that is to be displayed at the bottom of e-mails generated from the site. This is just textual information

The document template section describes documents that can be created on the “New Page”. Each document Template defines a name, description, and a template file to be used. In most cases this section can be left unchanged


The List Templates section allows for the creation of new List Types, which can be used as part of the site. The supporting files for the list template should be stored in a subdirectory called Lists below the Site definition directory. Another method of deploying a new List Type as part of a site definition is to deploy it as a feature. The Site definition can then activate the feature and use the List Type. This has the benefit of allowing the list type to be used independently of the site definition. For more information about the List Template section, see
The Modules section specifies a collection of files or modules, which can be deployed when a site is created. A module could be a Web Part, or a file, which is to be added to a document library etc. When adding a file to a library, it is possible to specify the value of the properties the item should have. This even allows you to add web parts to a layout page when the site is created.
For the Market Watch Project, modules were created for such things as default home pages for publishing sites. Several property values were set including some HTML content, as shown below:
    <Module Name="HomePage"
      <File Url="Default.aspx"
        <Property Name="Title"
         Value="Regional Home Page" />
        <Property Name="ContentType"
         Value="$Resources:cmscore,contenttype_welcomepage_name;" />
        <Property Name="PublishingPageLayout"
         Value="~SiteCollection/_catalogs/masterpage/defaultlayout.aspx, $Resources:spscore,DefaultLayoutTitle;" />
        <Property Name="PublishingPageContent"
         Value="&lt;div style=&quot;padding-left:7px;padding-top:8px&quot;&gt;
&lt;font style=&quot;font-size:12pt;font-family:Tahoma&quot;&gt;&lt;b&gt;&lt;font size=2&gt;Welcome to the&lt;/font&gt; &lt;/b&gt;
&lt;div style=&quot;padding-left:7px;padding-top:8px&quot;&gt;
&lt;font style=&quot;font-size:12pt;font-family:Tahoma&quot;&gt;&lt;b&gt;&lt;span class=ms-rteCustom-ArticleHeadLine&gt;Syrinx Portal.&lt;/span&gt;&lt;/b&gt;
&lt;/font&gt;&lt;/div&gt;" />

For more information on the Modules section, see http://msdn2.microsoft.com/en-us/library/ms467997.aspx

The components section allows you to define new “FileDialogPostProcessors” and “ExternalSecurityProviders”. These are low level processing objects within the SharePoint System; in most situations, no changes are required.

The configuration section is where the bulk of the site setup is defined. A site definition can contain one or more configurations; each configuration is uniquely identified and named within the site definition. The Configuration is broken down into several subsections, Lists, Site Features, Web Features, and Modules.

The Lists section defines Lists, which should be created as part of the site provisioning. For example in the Syrinx Portal State Site definition, a new document library list is created called Restaurants:

<List FeatureId="00B97871-E717-4F80-AA17-D0C71B363691"
          Title="Syrinx Restaurants "

The Feature Id is the GUID of the feature that created the base list type for this list. The type identifies the list type from the specified GUID. The Title is the display name for the list. The URL is the partial URL for the root of this list. Finally the QuickLaunchUrl is the URL to be used for the link in the quick launch bar.
To find the GUID and the type for a specific list type, the easiest way to do this is to navigate to the Site Actions->Create page. This will present a page of list types, which can be created in the site. Select the list type you wish to use, and use the right mouse button to get the properties of the link. The link will contain the feature id and list template or type id.  For example:


Note that some list types are only available after certain features have been activated.


The site features section is used to control which features are enabled when the site definition is used to create a site, which is a root site collection. Some features can only be enabled at a collection level. For example, the following list of features is from the Syrinx Portal root Site Collection definition:
  <!-- Workflow Expiration -->
  <Feature ID="C85E5759-F323-4EFB-B548-443D2216EFB5" />
  <!-- Workflow Review -->
  <Feature ID="02464C6A-9D07-4F30-BA04-E9035CF54392" />
  <!-- Workflow Signature -->
  <Feature ID="6C09612B-46AF-4B2F-8DFC-59185C962A29" />
  <!-- Workflow Translation -->
  <Feature ID="C6561405-EA03-40A9-A57F-F25472942A22" />
  <!-- PublishingUberSiteFeatureDescription -->
  <Feature ID="F6924D36-2FA8-4f0b-B16D-06B7250180FA" />
  <!-- BaseFeatureDescription -->
  <Feature ID="B21B090C-C796-4b0f-AC0F-7EF1659C20AE"/>
  <!-- Basic Web Parts -->
  <Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />
  <!-- Report Center Creation Feature - creates a whole site -->
  <Feature ID="8156EE99-DDFB-47bb-8835-7AE42D40D9B9" />
  <!-- Office SharePoint Server Enterprise Site Collection features -->
  <Feature ID="8581a8a7-cf16-4770-ac54-260265ddb0b2"/>
  <!-- Syrinx Portal Custom Site Columns -->
  <Feature ID="0185ca1f-a6d6-4df9-8d67-93f896f95c6b" /></SiteFeatures>

This is a large number of feature ids, to understand and identify. There are two methods to identify the feature id's required for a site definition. The first method is to review site definitions that have the features enabled and look at the either the site or web features nodes within the configuration nodes. This is usually required when the site definition being constructed combines the features of two existing site definitions. The second method is to find the feature id's from the features activation page.
To find the feature id's navigate to the

Site Actions->Site Settings->Site Collection Features
Site Actions->Site Settings->Site Features.

From this page, use the right mouse button to view the source of the HTML page. Search for the name of the feature you wish to have activated in your site definition. For example searching for “Office SharePoint Server Enterprise Site features” the HTML should look something like the following:
<TD class="ms-alternating" style="padding-top: 4px; padding-bottom: 4px; ">
  <TABLE width="100%" cellpadding="0" cellspacing="0" border="0">
    <TR><TD class="ms-vb2" style="font-weight: bold;"><H3 class="ms-standardheader">Office SharePoint Server Enterprise Site features</H3></TD></TR>
    <TR><TD class="ms-vb2">Features such as the business data catalog, forms services, and Excel Services, included in the Office SharePoint Server Enterprise License</TD></TR>
<TD class="ms-alternating" style="padding-top: 4px; padding-bottom: 4px;">
  <DIV id='0806d127-06e6-447a-980e-2e90b03101b8'>
    <input type="button" name="ctl00$PlaceHolderMain$featact$rptrFeatureList$ctl01$btnActivate" value="Activate"
           onclick="BLOCKED SCRIPT__doPostBack('ctl00$PlaceHolderMain$featact$rptrFeatureList$ctl01$btnActivate','')"
           id="ctl00_PlaceHolderMain_featact_rptrFeatureList_ctl01_btnActivate" class="ms-ButtonHeightWidth" />&nbsp;&nbsp;&nbsp;&nbsp;

Looking at the DIV tag it has an id, which is a GUID. This GUID is the feature id for the feature. This can then be added to the SiteFeatures node.


The web features section behaves the same as the site features section, except that the features are activated when the site definition is used to create a child site. Note that some features can and should only be activated on a Site Collection root site.


The modules collection defines the set of modules that are to be deployed as part of the site provisioning. This is not to be confused with the Modules section for the template described above. This is the set of modules defined in the Modules section which are to be installed for the current configuration.


There are several steps to testing a Site Definition. The first is to make sure you have a Web Application that you can use for testing; typically this runs on a different port than the default SharePoint instance (I like to use port 2112). Once you have an empty Web Application, there is a 10 step process to test a site definition. The steps are:
1. Edit Site Definition and Features
2. Build Solution Package
3. Reset IIS
4. Add Solution Package
5. Deploy Solution Package
6. Create Site Collection
7. Test Definition
8. Delete Site Collection
9. Retract Solution Package
10. Delete Solution Package

Steps 1 and 2 can be executed in Visual Studio or other XML Editor.
Steps 3, 4, and 5 can be executed in a BAT file using stsadm commands. For example:

stsadm -o addsolution -filename SyrinxPortal.wsp
stsadm -o deploysolution -name SyrinxPortal.wsp -allcontenturls -immediate –allowGacDeployment
Step 6 can be executed either via a stsadm command or via the Central Admin administration UI. I prefer to use the UI, as this allows me to rename the site definition on each of the iterations and verify I am using the correct one.
Step 7 requires using the UI.
Steps 8 and 9 can be combined in to a BAT file, and executed using stsadm commands. For example:

stsadm -o deletesite -url
stsadm -o retractsolution -name SyrinxPortal.wsp -allcontenturls –immediate
Step 10 can be executed from a BAT file using stsadm commands. For example:

stsadm -o deletesolution -name SyrinxPortal.wsp

Note however, that both the deployment and the retraction of the solution package uses the SharePoint Timer Service (OWSTIMER.EXE) and so do not take effect immediately; a job is created by the stsadm command for the timer to execute, this prevents the commands form all being executed from one batch file.

Hopefully this article has given you a jump start on building your own site definitions.