Creating Site Definitions for Windows SharePoint Services

Patrick Tisseghem

March 2006

Applies to:
Microsoft Windows SharePoint Services (version 2)

Summary: Learn how to create a custom site definition for Microsoft Windows SharePoint Services sites. This article provides an understanding of how Windows SharePoint Services V2 site definitions work internally and how the Collaborative Application Markup Language (CAML) defines the structure of lists and views. (18 printed pages)


Introduction to Creating Site Definitions
Creating the Seminar Site Definition
Creating the List Definition
Additional Resources
About the Author

Introduction to Creating Site Definitions

This article discusses how to create a custom site definition for Microsoft Windows SharePoint Services (version 2) team sites. The goal is to provide you with a good understanding of how Windows SharePoint Services V2 site definitions work internally and how the Collaborative Application Markup Language (CAML) defines the structure of lists and views.

You can follow along with this article as I walk you through a step-by-step example of creating a simple custom site definition for storing and delivering information associated with a training seminar. My goal is to keep the instructions simple but educative so that you can relate everything I discuss to your own types of team sites.

Creating the Seminar Site Definition

Several MSDN white papers (listed at the end of this article) discuss how to create your own custom site definition by making a copy of an existing default site definition supplied by Microsoft. A good one to use is the SharePoint team site definition, physically represented by the STS folder found at drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\1033 on the server that is running Windows SharePoint Services. Your copy of that site definition has the same functionality and look and feel as the default SharePoint team site. You can modify this site definition to customize it. Before your custom site definition becomes active, you must create a copy of the Webtemp.xml file and modify its content. After you perform an iisreset command, your site definition becomes visible in the template picker page. Find more information and step-by-step guides in the additional resources listed at the end of this article.

The site definition I show you how to create is very simple and has limited features. The goal of the article is to give you insight into how the different components that compose a site definition interact with each other and what CAML elements you need to understand to create more-complex site definitions. A copy of the complete STS default site definition is too much to accomplish in the space allowed for this article. I therefore create the necessary site definition infrastructure manually. I do copy some files, though, just to simplify the work.

The Minimal Site Definition Infrastructure

Site definitions are collections of physical files located in drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE and in language-specific folders (such as 1033 for English-US) under it. You perform the initial work for the custom site definition in this folder.

Follow these steps to create the initial minimal site definition infrastructure. I expand the various components step-by-step later in the article.

  1. Create a new subfolder named SEMINAR under drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\1033. The name of the folder must use all uppercase letters.
  2. Every team site has a home page typically represented by a physical file named default.aspx. The default.aspx page from the STS folder is a good candidate to start with. You customize it later for this project. So copy this default.aspx into your own SEMINAR folder.
  3. Also copy the XML subfolder from the STS folder. In it are three important XML files that Windows SharePoint Services uses to get your site up and running.
    1. Onet.xml provides Windows SharePoint Services with information about the navigation, lists, and document libraries that users can create; the templates for the document libraries; the base list types, and the possible site configurations.
    2. Stdview.xml is the configuration file containing the definition of the standard views upon which you can base your own custom views.
    3. Vwstyles.xml defines the various styles for creating new views.
  4. To conclude, create a second subfolder named LISTS and copy the subfolders CUSTLIST and WPLIB from the LISTS folder in the STS site definition folder.

Figure 1 shows the initial framework of the site definition.

Figure 1. Initial site definition framework

Modifying the Onet.xml file

The first file to examine in closer detail is Onet.xml. It is an extremely important file within your site definition. Figure 2 summarizes the six major sections within Onet.xml. The Project element encapsulates all of them; I simply modify the Title attribute of this element to store the title of the custom site definition.

<Project Title="Seminar SharePoint Site" ListDir="Lists" 
xmlns:ows="Microsoft SharePoint">

Figure 2. Components of the Onet.xml file

Let's look at each section more closely.

  • The NavBars element defines the navigation infrastructure on the pages that compose the team site. The seminar site requires minimal navigation: a link to the home page, the agenda of the sessions, the speakers page, and the document library where the presentations and samples for download will be stored.

    The Quick Launch navigation elements are not used for this example. So you can remove the definition of it in the Onet.xml file. The only navigation bar we need (represented by the NavBar element) is the horizontal one at the top of the page.

  • Three NavBarLink elements define the hyperlinks. You provide the NavBarLink element with a name and the URL for the page to display.

        <NavBar Name="SharePoint Top Navbar" 
          Body="&lt;a ID='onettopnavbar#LABEL_ID#' 
          href='#URL#' accesskey='J'&gt;#LABEL#&lt;/a&gt;" ID="1002">
            <NavBarLink Name="Agenda Sessions" 
            <NavBarLink Name="Speakers" 
            <NavBarLink Name="Downloads" 
  • The next block, the ListTemplates, defines all the lists and libraries you make available for your site definition. In the example, you create two custom lists (one to store session information and one for the speaker information) and one custom document library (to store the downloadable files). For now, remove all except the custom list, the document library, and the internal lists (the galleries for the Web Parts and templates) necessary for a top-level team site.

      <ListTemplate Name="custlist" DisplayName="Custom List" ...
      <ListTemplate Name="doclib" DisplayName="Document Library" ...
      <ListTemplate Name="webtemp" DisplayName="Site Template Gallery" ...
      <ListTemplate Name="wplib" DisplayName="Web Part Gallery" ...
      <ListTemplate Name="datasrcs" DisplayName="DataSources" ...
      <ListTemplate Name="listtemp" DisplayName="List Template Gallery" ...
  • The DocumentTemplates, as you might expect, define the templates for the document libraries. For this example, delete everything except the minimum that the site requires. Keep only the definition for the document library that uses no templates.

        <DocumentTemplate  Name="" DisplayName="None" Type="100" 
         Description="This document library will not use templates.">
  • The BaseTypes block defines the five different types of lists with which users can work on team sites. Do not change anything in this block; simply leave it as it is. Every BaseType definition includes the various field types and the ways they are rendered in the various modes (edit, new, and view mode).

       <BaseType Title="Generic List" 
             Image="_layouts/images/itgen.gif" Type="0">
       <BaseType Title="Document Library" 
             Image="_layouts/images/itdl.gif" Type="1">
  • A site definition can have multiple configurations, each represented by the Configuration element. Examine the default STS site definition. You can see that the blank team site and the default team site already contain some instances of lists and Web Parts added to the home page. The seminar site definition has only one configuration. The internal lists will be created, and on the home page you will have an empty Content Editor Web Part that can be used by the administrator to provide a description of the seminar. An image Web Part shows a default image. In the configuration section, you point to the module where the Web Parts to be added will be defined.

       <Configuration ID="0" Name="Default">
          <List Title="Site Template Gallery" Type="111"
                Url="_catalogs/wt" RootWebOnly="TRUE" />
          <List Title="Web Part Gallery" Type="113"
                Url="_catalogs/wp" RootWebOnly="TRUE" />
          <List Title="List Template Gallery" Type="114"
                Url="_catalogs/lt" RootWebOnly="TRUE" />
          <Module Name="Default"/>
          <Module Name="WebPartPopulation"/>
  • The Modules section is the last one to consider. Within the Configuration element, I defined a link to two modules: Default and WebPartPopulation. The first one defines what needs to be dropped at the start on the home page and the second one fills the internal Web Part gallery with the two Web Parts users can drop on the Web Part Pages. The Web Parts placed on default.aspx are defined by the AllUsersWebPart element.

     <Module Name="Default" Url="" Path="">
       <File Url="default.aspx" NavBarHome="True">
          <AllUsersWebPart WebPartZoneID="Left" WebPartOrder="1">
             <WebPart xmlns="">
               <Assembly>Microsoft.SharePoint, Version=, 
               Culture=neutral, PublicKeyToken=71e9bce111e9429c</Assembly>
               <Title>Welcome to the conference site</Title>
         <AllUsersWebPart WebPartZoneID="Right" WebPartOrder="1">
            <WebPart xmlns="" 
              <Assembly>Microsoft.SharePoint, Version=, 
               Culture=neutral, PublicKeyToken=71e9bce111e9429c</Assembly>
              <Title>Site Image</Title>
         <NavBarPage Name="Home" ID="1002" Position="Start">
        <Module Name="WebPartPopulation" List="113" Url="_catalogs/wp" 
         Path="lists\wplib\dwp" RootWebOnly="TRUE">
            <File Url="MSContentEditor.dwp" Type="GhostableInLibrary"/>
            <File Url="MSImage.dwp" Type="GhostableInLibrary"/>

For now, that is everything you change in Onet.xml. Later we return to it to define the custom speaker list.

Making Changes to the Home Page

The home page (physically represented by default.aspx in your site definition folder) is a normal ASP.NET page filled with controls that are specific to Windows SharePoint Services and Microsoft FrontPage components. Figure 3 depicts the elements that compose the home page.

Figure 3. The typical components of a SharePoint home page

  • The two navigation bars (the horizontal navigation bar and the Quick Launch) are defined within Onet.xml and rendered by a combination of a FrontPage component and a navigation server control specific to Windows SharePoint Services. Based on the ID value of NavBar or NavBarLink, the navigation bars are rendered appropriately.

    <td class="ms-banner" width="99%" nowrap ID="HBN100" valign="middle">
     <!--webbot bot="Navigation" 
       S-Btn-Nml="<a ID='onettopnavbar#LABEL_ID#' href='#URL#' 
       S-Btn-Sel="<a ID='onettopnavbar#LABEL_ID#' href='#URL#'   
       S-Target startspan -->
       <SharePoint:Navigation LinkBarId="1002" />
     <!--webbot bot="Navigation" endspan -->
  • Dynamic information is rendered on the page using ASP.NET server controls that are specific to Windows SharePoint Services.

    • Microsoft.SharePoint.WebControls.ProjectProperty renders the title and the description of the team site.
    • Microsoft.SharePoint.WebControls.ViewSearchForm renders the search box.
    • Microsoft.SharePoint.WebControls.PortalConnection renders the link to the parent site, which can be either a portal or a team site.
    • Microsoft.SharePoint.WebPartPages.AuthenticationButton renders a possible Sign In button when anonymous access is allowed.
    • Microsoft.SharePoint.WebPartPages.SettingsLink renders the Modify Shared Page link for accessing the Web Part galleries and other settings.
  • In the Onet.xml file, the Configuration and the Module elements define the content of the page at the start. In the Quick Launch, you see a number of lists and libraries already available; on the page itself you find some Web Parts already presented. Containers for these Web Parts in default.aspx are provided through the Microsoft.SharePoint.WebPartPages.WebPartZone server control.

  • You can make many kinds of modifications to this default.aspx page by opening it in Microsoft Visual Studio .NET. For your site definition, I told you to remove the part that defines the Quick Launch area because the NavBarLink elements have been deleted from Onet.xml. In the source, look for the navigation comment and remove everything until just before the contents comment.

Activating the Site Definition

The new custom site definition you created is not yet active. Windows SharePoint Services does not yet know that a new site definition is available for users. A number of XML files whose names begin with the Webtemp prefix are loaded by Windows SharePoint Services when it starts. These XML files provide Windows SharePoint Services with the list of default and custom site definitions for the users who are creating new sites. The Webtemp file must be created within the drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\1033\XML folder. I recommend that you begin with a copy of the default Webtemp.xml file and rename it to Webtempseminar.xml.

After opening the file in your XML editor, you modify it as follows:

<?xml version="1.0" encoding="utf-8" ?>
<!-- _lcid="1033" _version="11.0.5510" _dal="1" -->
<!-- _LocalBinding -->
<Templates xmlns:ows="Microsoft SharePoint">
 <Template Name="SEMINAR"     ID="10100">
    <Configuration ID="0" Title="Seminar Site" Hidden="FALSE" 
     Description="This template can be used to create a seminar site.">

The name of the template must match the name of the folder in which you store the site definition. Every site definition needs a unique identifier on your computer. The site definition allows for one configuration as you have defined it in Onet.xml.

You can test this by first restarting Internet Information Services (use the command iisreset from your command line) and then creating a new team site based on your custom site definition. Figure 4 displays the TemplatePicker page with the new site definition template.

Figure 4. TemplatePicker displaying the Seminar Site definition you created

Figure 5 shows the resulting team site.

Figure 5. A new Seminar Site based on the custom site definition

Creating the List Definition

Now that you have your site definition infrastructure up and running, you can add more to it. You must make two lists available: One list stores the details of the speakers, and a second list stores the details of the sessions. This section shows you how to define the speakers list definition in CAML.

The Speakers List

The speakers list is a small custom list with the following custom fields:

  • First Name (single line of text)
  • Last Name (single line of text)
  • E-mail (single line of text)
  • Bio (multiple lines of text)

To define this list as part of the site definition, you must complete a few steps. Note that the Title field (an internal field you cannot remove) remains a column of the list and contains the full name of the speaker.

Copying the CUSTLIST

To start, you need to create a copy of the CUSTLIST folder. You can take the one that is already available in your site definition folder. Rename the CUSTLIST folder to SPEAKERS.

The folder contains four ASP.NET pages and one XML file:

  • AllItems.aspx
  • DispForm.aspx
  • EditForm.aspx
  • NewForm.aspx
  • Schema.xml

Initial Modifications to Schema.xml

Modify Schema.xml slightly so that you can later determine whether the list appears on sites that are based on the site definition. Open the Schema.xml file in your favorite XML editor.

  • The root element is the List element. Here you must change the Name, Title, and URL attribute values.

    <List xmlns:ows="Microsoft SharePoint" Name="Speakers" 
     Title="Speaker List" Direction="0" 
     Url="Lists/Speakers" BaseType="0" >
  • Windows SharePoint Services requires you to have a DefaultDescription element for a custom list. This element needs to be created as a child element of the MetaData element.

    <DefaultDescription>List for storing information regarding the 

Activating the Speakers List

You must return to the Onet.xml file associated with the seminar site definition to activate the speakers list. In it, you register the new list within the ListTemplates section.

<ListTemplate Name="speakers" DisplayName="Speakers List" Type="500" 
 BaseType="0" OnQuickLaunch="TRUE" SecurityBits="11" 
 Description="Create a list to store speaker information for the seminar."

The list template must have a type number. The guideline here is to use a type number less than 1000.

You create one instance of this list during the creation process of the team site. A ListViewWebPart displaying the All Items view (that is, the default one in the custom list template) should be inserted on the home page.

For this, you need to edit the Configuration element within Onet.xml and add a List element as a child element to indicate that you want to create the instance.

<List Title="Speakers" Type="500" />

Next, in the Module element named "default," create another List element as a child element under the File element that represents default.aspx. You add the ListViewWebPart directly under the content editor Web Part you already have in the left Web Part zone. To indicate the order within the Web Part zone, use the WebPartOrder attribute.

<View List="500" BaseViewID="0" WebPartZoneID="Left" WebPartOrder="2"/>

Testing the Changes

After you make all the changes, you can test the modified site definition again by first restarting IIS (iisreset) and then creating a new team site based on the seminar site definition, as displayed in Figure 6.

Figure 6. Seminar site with the speakers list

The Schema.xml File

Now take a closer look at Schema.xml. This important file contains the CAML elements that express the definition of the list. Like the Onet.xml file discussed earlier, Schema.xml comprises several XML sections. (See Figure 7.)

Figure 7. Components of the Schema.xml file

Open the Schema.xml file in your favorite XML editor because you must make a couple of changes.

  • The Fields section defines the fields that are included in the list inherited from the base type list (that is, the custom list). The definitions of these base type fields are done in Onet.xml under the BaseType element.

  • The speakers list has a few additional fields, each defined by a Field element. Most are simple text fields. For entering the bio information, define the field type Note so that the user can enter multiple lines of text. All the fields have the attribute Sealed set to True to disallow a user from removing them as columns from the list.

      <Field Type="Text" Name="FirstName" DisplayName="First Name" 
       Required="TRUE" Sealed="TRUE" />
      <Field Type="Text" Name="LastName" DisplayName="Last Name" 
       Required="TRUE" Sealed="TRUE" />
      <Field Type="Note" Name="Bio" DisplayName="Bio" Sealed="TRUE" />
      <Field Type="Text" Name="Email" DisplayName="Email" Sealed="TRUE" />
  • The Views section contains the definitions of the different views that are immediately available when an instance of this list is created. The custom list has only two views: the default view displayed within the ListViewWebPart on the home page, and the All Items view. For now, simply ensure that the fields created in the previous step are displayed in both views. Later you create a complete new view. The ViewFields child element, one of the last child elements of the View element, defines the list of fields to be included in the view. Add a FieldRef element for each of them. Remove the two FieldRef elements that are already there. Repeat this for both of the views.

      <FieldRef Name="FirstName"></FieldRef>
      <FieldRef Name="LastName"></FieldRef>
      <FieldRef Name="Email"></FieldRef>
      <FieldRef Name="Bio"></FieldRef>
  • The Forms section allows you to customize for each type of operation on the list (displaying, editing, or creating items) the dynamic part of the physical forms page. Use it, for example, to define additional actions or to add additional Web Parts to the pages.

  • The last section is the ToolBar section, which defines the actions displayed by hyperlinks in the Quick Launch. Examples are the Alert Me action and Modify Settings and Columns action. Again, you can add additional actions here.

After executing an iisreset command and creating a new team site based on your custom site definition, you have a list populated with the new fields, as shown in Figure 8.

Figure 8. Speakers list with custom fields

Creating a Custom View

The last topic I discuss in this article describes the steps to create a custom view using Schema.xml and CAML. Schema.xml contains one or more View elements, and each element defines one view. Every View element has at least six important sections:

  • ViewHeader
  • ViewBody
  • ViewFooter
  • ViewEmpty
  • Query
  • ViewFields

Remember that the goal of this article is to provide you with the basic techniques so that you build your own, more-powerful solutions. The example view basically displays the information of a speaker in the manner of a data list.

So how do you start? The bulk of your work occurs in Schema.xml. You currently have two views defined. You can create the third one directly under the second view. Views are defined by the View element. A number of attributes are important for the View element:

  • Name is required; it defines the internal name for the view.
  • DisplayName is the name of the view as the user sees it.
  • BaseViewID is an identifier for the custom view.
  • Url is the path to the ASP.NET page that is responsible for the rendering of the view. For this example, you make a copy of AllItems.aspx, already present in the SPEAKERS folder, and rename it to speakerssummary.aspx. Think of a scenario in which you start modifying this page to accommodate the view in a specific manner. This example will have the normal Windows SharePoint Services appearance.
  • In the ASP.NET page, Windows SharePoint Services fills the WebPartZone specified by WebPartZoneID.

The next elements to consider are ViewHeader, ViewBody, and ViewFooter. For now, keep it simple and provide only the infrastructure for the table to be generated. More details follow later. Notice that the insertion of HTML always needs to be enclosed in a CDATA element so that your XML is well-formed.

Initially, when you create a new team site based on the site definition, the list is empty. You can use the ViewEmpty part of the View to define what the user will see. For now, leave ViewBody empty.

You can also define a CAML query for sorting and possibly filtering the items displayed in the view. The definition of the list of fields included within the view is defined within the ViewFields element.

<View Name="SpeakersSummary" DisplayName="Speakers Summary" BaseViewID="2" 
  WebPartZoneID="Main" Url="SpeakersSummary.aspx">
     <![CDATA[ <table cellpadding="0" cellspacing="1" 
        border="0" width="100%" class="ms-nav"> 
        <tr><td><b>Speakers Summary View</b></td></tr>]]>
  <ViewFooter><HTML><![CDATA[ </table> ]]></HTML></ViewFooter>
    <FieldRef Name="LinkTitle"></FieldRef>
    <FieldRef Name="FirstName"></FieldRef>
    <FieldRef Name="LastName"></FieldRef>
    <FieldRef Name="Bio"></FieldRef>
    <FieldRef Name="Email"></FieldRef>

It is time to test these changes. A new site based on your custom site definition now has a new view for the speakers list. It first displays the contents of the ViewEmpty elements and, after the insertion of a new speaker, the contents of ViewHeader, ViewBody, and ViewFooter.

You can finalize the view now by defining the contents of the ViewBody element.

  <HTML><![CDATA[ <tr><td> ]]></HTML>
  <Field Name="LinkTitle"/>
  <HTML><![CDATA[ </td></tr> ]]></HTML>
  <HTML><![CDATA[ <tr><td><i> ]]></HTML>
  <Field Name="Bio"/>
  <HTML><![CDATA[ </i></td></tr> ]]></HTML>
  <HTML><![CDATA[ <tr><td> ]]></HTML>
  <Field Name="Email"/>
  <HTML><![CDATA[ </td></tr> ]]></HTML>

While testing this change, notice that a JavaScript error occurs if you move your mouse pointer over the LinkTitle field. This is due to the fact that the default rendering of the LinkTitle field (as defined in Onet.xml) requires some client-side scripting code to be available. You haven't yet taken care of this. To fix this problem, insert the following block in the ViewHeader section. You can simply copy the block from the second view within your Schema.xml.

<HTML><![CDATA[<SCRIPT>ctx = new ContextInfo();ctx.listBaseType = 
<ListProperty Select="BaseType"/>
<HTML><![CDATA[;ctx.listTemplate = ]]></HTML>
<ListProperty Select="ServerTemplate"/>
<HTML><![CDATA[;ctx.listName =]]></HTML>
<HTML><![CDATA[;ctx.listUrlDir = ]]></HTML>
<ScriptQuote><ListUrlDir WebRel="TRUE"/></ScriptQuote>
<HTML><![CDATA[;ctx.HttpPath = ]]></HTML>
<HTML><![CDATA[;ctx.HttpRoot = ]]></HTML>
<HTML><![CDATA[;ctx.imagesPath = ]]></HTML>
<HTML><![CDATA[;ctx.PortalUrl = ]]></HTML>
<ScriptQuote><ProjectProperty Select="PortalUrl"/></ScriptQuote>
<HTML><![CDATA[;if (ctx.PortalUrl == "") ctx.PortalUrl = 
null;ctx.displayFormUrl = ]]></HTML>
<ScriptQuote><URL Cmd="DISPLAY" NoID="TRUE"/></ScriptQuote>
<HTML><![CDATA[;ctx.editFormUrl = ]]></HTML>
<ScriptQuote><URL Cmd="EDIT" NoID="TRUE"/></ScriptQuote>
<HTML><![CDATA[;ctx.isWebEditorPreview = ]]></HTML>
   <GetVar Name="WebEditorPreview"/>
   <Case Value="TRUE">1</Case>
<HTML><![CDATA[;ctx.ctxId = ]]></HTML>
<Counter Type="View"/>
  <Expr><ListProperty Select="ModeratedList"/></Expr>
  <Case Value="0"/>
  <Default>ctx.isModerated = true;</Default>
  <Expr><GetVar Name="RecursiveView"/></Expr>
  <Case Value="1">ctx.recursiveView = true;</Case>
<HTML><![CDATA[ ctx]]></HTML>
<Counter Type="View"/>
<HTML><![CDATA[ = ctx;</SCRIPT>]]></HTML>

The block of code is responsible for providing context information to the JavaScript functions that provide the actions to be performed on the list item (such as viewing and editing the properties). Figure 9 shows the final outcome of the custom view.

Figure 9. The custom view for the speakers list


In this article, you learned the basic steps required to create the infrastructure for a site definition and the CAML elements needed to create a custom list definition and a custom view. I hope that the material covered here has helped you better understand the various components that compose a site definition. Please contact me ( if you have any remarks or questions regarding the content.

Additional Resources

About the Author

Patrick Tisseghem is managing partner at U2U, a Microsoft .NET training services company based in Brussels. His main areas of expertise are the .NET Framework and all the products and technologies that relate to the information worker. In this role he is evangelizing SharePoint Portal Server 2003 and Office development for Microsoft EMEA.

This article was developed in partnership with A23 Consulting.