Syrinx on SharePoint

Site Definitions in SharePoint 2007

For many of our clients we need to build custom site definitions. When building SharePoint solutions the terms site template, definition and to a lesser extent site portal are often used. Each of these allows the user to create a new site with a predefined set of Content Types, Layouts, and Lists etc. In the case of the Portal, it allows the user to create a site and one or more nested child sites.

Site definitions are our preferred way to develop custom sites. A portal definition is a variation of the Site Definition except that the definition describes a series of sites to be created. An example of this is the Site Collection Publishing Template, which creates a root site collection, a News sub site, a Documents sub site and some others.

The focus of this article is on how site definitions and Portal definitions can be created and deployed. Site definitions are usually deployed as a part of a solution package, which is a compressed cabinet file made up of XML files and other resources. Solution packages are first added and then deployed to the MOSS farm. Once deployed the contents of the solution can be made available to sites, or used to create new sites.

The Solution Package can also deploy Site Features. A Site Feature can do myriad things, such as deploying a new web part, defining a new content type, site column, list type, adding a new page layout, or even a graphic image. Site Features can then be activated in a site, or automatically applied in a new site definition. We typically deploy several features as part of the new site definition, as this allows multiple developers to work together without interfering with one another. The solution and feature methodology is a powerful new model for MOSS and is used by Microsoft to build and extend MOSS.

CREATING A 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:

WEBTEMP FILE
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:

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:

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"

         siteDefinition="SPPR#0"

         displayName="Syrinx Portal Display Name"

         description="Syrinx Watch Portal Description">

      <webs>

        <web name="NorthEast"

             siteDefinition="SPRegion#0"

             displayName="North East"

             description="North East Site Description">

          <webs>

            <web name="Massachusetts"

                 siteDefinition="SPState#0"

                 displayName="Massachusetts"

                 description="Massachusetts Site Description"/>

          </webs>

        </web>

        <web name="SouthEast"

             siteDefinition="SPRegion#0"

             displayName="South West"

             description="South West Site Description"/>

      </webs>

    </web>

  </portal>

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.

ONET.XML FILE
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.

NAVIGATIONAL AREAS
In the quick launch bar (left navigation in MOSS 2007), there sections under which lists and other links are displayed, for example:

 

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.

  <NavBars>

    <NavBar Name="$Resources:core,category_Top;"

      Separator="&amp;nbsp;&amp;nbsp;&amp;nbsp;"

      Body="&lt;a ID='onettopnavbar#LABEL_ID#' href='#URL#' accesskey='J'&gt;#LABEL#&lt;/a&gt;"

      ID="1002"/>

    <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;"

      Suffix="&lt;/table&gt;"

      ID="1004"/>

  </NavBars>

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

EMAIL FOOTER
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.

DOCUMENT TEMPLATES
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.

LIST TEMPLATES
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 http://msdn2.microsoft.com/en-us/library/ms439434.aspx.

MODULES
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:

<Modules>

    <Module Name="HomePage"

        Url="Pages"

        Path="">

      <File Url="Default.aspx"

       Type="GhostableInLibrary">

        <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;/font&gt;

&lt;/div&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;" />

      </File>

    </Module>

</Modules>

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

COMPONENTS
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.

CONFIGURATIONS
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.

LISTS
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"

          Type="101"

          Title="Syrinx Restaurants "

          Url="Restaurants"

          QuickLaunchUrl="Restaurants/Forms/AllItems.aspx"/>

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:

http://sharedvision/layouts/new.aspx?FeatureId={00bfea71-e717-4e80-aa17-d0c71b360101}&ListTemplate=101

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

SITE FEATURES
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:

<SiteFeatures>

  <!-- 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
      or
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>

  </TABLE>

</TD>

<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;

 </DIV>
</TD>

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.

WEB FEATURES
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.

MODULES
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.

TESTING A SITE DEFINITION
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:

iisreset
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 http://dev-sp:2112
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.