Site Definitions

A site definition is the top-level component in WSS that aggregates smaller, more modular definitions to create a complete site template that can be used to provision sites. For example, a site definition usually includes a custom page template for the site’s home page and can additionally reference external features to add support for other types of site-specific elements such as custom lists, secondary pages, and Web Parts. The value of creating custom site definitions is obvious. They enable you to develop site templates for creating new sites that act as prepackaged business solutions.

Tip 

While you can create and package list definitions and other components within a site definition, it’s a best practice to package components within WSS features and then reference them from one or more site definitions.

In WSS, every site is provisioned from a specific site definition. This is true for all top-level sites as well as child sites nested within a site collection. Once a site is provisioned from a particular site definition, it picks up a dependency on that site definition that remains in effect for the lifetime of the site. A site’s dependency on its underlying site definition can never be removed or changed, and the site definition must be installed and remain functional in the farm for the site to continue working properly.

Consider a scenario in which you create a custom site definition and deploy it within a particular WSS farm. Now imagine that you use this site definition to provision the top-level site within a new site collection. What would happen if you attempted to back up the site collection along with its top-level site by using the STSADM.EXE command-line utility and then restore it in another WSS farm? This would not work properly unless your custom site definition is installed in both farms.

Let’s now move on to a discussion of how site definitions are structured and deployed. Similar to a WSS feature, a site definition is defined with a set of Collaborative Application Markup Language (CAML)-based files that are deployed within a named directory on the file system of each front-end Web server in the farm. Site definitions are deployed within the 12\TEMPLATE\ SiteTemplates directory and are referenced in the 12\TEMPLATE\<culture>\XML directory in WEBTEMP.XML files, where the <culture> folder is the locale identifier (12\TEMPLATE\ 1033\XML for US English).

WSS offers several pre-installed site definitions to provide users with creatable site templates out of the box. For example, a site definition named STS provides familiar site templates such as Team Site, Blank Site, and Document Workspace. You can always back up a site created from one of these site templates and restore it on another farm because the STS site definition is guaranteed to be pre-installed in any farm running WSS 3.0.

Tip 

It is recommended that you avoid making changes to any of the pre-installed site definitions that ship with WSS and Microsoft Office SharePoint Server (MOSS). However, you are free to create your own custom site definitions. Later in this chapter, you will also see that you can create custom WSS features that add extra functionality to the pre-installed site definitions supplied by Microsoft.

A site definition itself does not represent a creatable site template. Instead, a site definition contains one or more configurations, and these configurations are what appear to users as creatable site templates. Therefore, the STS site definition contains three different configurations: Team Site, Blank Site, and Document Workspace.

Tip 

When creating a new site by using the STSADM.EXE command-line utility or through custom code, you are often required to reference a site definition and one of its configurations by name. This is done by specifying the name of the site definition followed by the pound sign and the integer identifier of the configuration. For example, you can use STS#0 to reference the site template titled Team Site and STS#1 to reference the site template titled Blank Site. The following example uses one of these site template references when creating a new top-level site by using the STS command-line utility.

 STSADM.EXE -o createsite -url http://litwareinc.com                          -ownerlogin LITWAREINC\Administrator                          -owneremail [e-mail]                          -sitetemplate STS#1

Remember to remove the line breaks between parameters when calling STSADM.EXE from either the command line or a batch file.

WSS provides several other pre-installed site definitions in addition to STS. A site definition named MPS contains five different configurations for the various Meeting Workspace site templates. Two site definitions are named Blog and Wiki, and each contains a single configuration for creating blog sites and wiki sites. Finally, a site definition named CENTRALADMIN provides the site template used to create the top-level site used in the WSS Central Administration Web application.

In a farm in which MOSS is installed, there are several pre-installed site definitions in addition to those normally included with WSS. MOSS uses these site definitions to provide site templates that add value on top of WSS by creating sites offering extended functionality in areas such as publishing, content search and management, business intelligence, and social networking. The fact that MOSS is so dependent on its own site definitions should provide you with a clear indication that developing custom site definitions is critical. This is what makes it possible to build real applications that are seen as complete business solutions on the WSS platform.

Tip 

As mentioned earlier, we recommend that you avoid making changes to any of the pre-installed site definitions that ship with WSS and MOSS. However, there is nothing stopping you from opening up the source files inside the site definitions on your developer’s workstation and snooping around to see how they’re built. Reverse engineering the preinstalled site definitions is a great way to learn about techniques that you can use when you build your own.

The Global Site Definition

WSS 3.0 introduces the Global site definition, which provides a common repository for site provision instructions required by every site definition. This new approach significantly improves the structuring of site definitions over the way things were previously structured in Microsoft Windows SharePoint Services 2.0, in which common provision instructions had to be included as redundant XML in each site definition. The Global site definition refactors more than 2,600 lines of required common components, such as Base Types and required Galleries, which were previously required in the ONET.XML file of every site definition.

The Global site definition is located at the 12\TEMPLATES\GLOBAL path. It contains the standard default.master page template along with instructions to provision an instance of default.master page into the Master Page gallery of every new site. The Global site definition also contains provisioning logic to create the following four site collection–scoped lists in every new top-level site:

• Web Parts gallery

• List Template gallery

• Site Template gallery

• User Information Profile list

Creating a Custom Site Definition

To create a simple site definition, create a new class library project. Similar to the feature projects introduced throughout this book, the Site Definition project is a class library project that is used for XML and ASPX editing and source control, whereas an install script is responsible for copying the files where they are needed for deployment. Later in this chapter, we will look at creating a WSS solution package for deployment that builds on this project format. We will also be localizing the site definition as it is built by using the Resources folder of the project.

At the top level of the project, create a RESOURCES folder and a TEMPLATE folder, which we will later deploy to the \\Program Files\Common Files\Microsoft Shared\web server extensions\12 folder, as was previously done with features. Next, create a folder structure as illustrated in Figure 9-1.

Figure 9-1: Folder structure for the Site Definition project

Inside the class library, create a SiteTemplates folder and a folder corresponding to your locale’s identifier, which is 1033 for US English. Within the SiteTemplates folder, create a folder with the same name as your site definition, which in this example is LitwareMarketplace. Within the LitwareMarketplace folder, create an XML folder with an XML file named ONET.xml. The final folder structure should look like Figure 9-1.

The ONET.xml file serves as the high-level manifest for the site definition and references the components that are to be used. Generally speaking, all components that you want to be automatically provisioned within sites created from the site definition should be referenced from this ONET.xml file. You also want to add references to WSS features that define list types that you want to be available to users so that they can create new lists on demand. Our approach is to create an empty XML file and paste in certain elements from the STS Team site definition, while defining the core of the elements ourselves.

The base structure of the ONET site definition schema is shown in Listing 9-1. Note that we define this XML file to use the SharePoint XML namespace, which gives us assistance with the schema when editing the file in Visual Studio. (The pre-installed site definitions do not reference this schema, although it is inferred.)

Listing 9-1: The basic Site Definition project schema

  <?xml version="1.0" encoding="utf-8"?> <Project Title="My Site Definition"          Revision="0"          ListDir="Lists"          xmlns:ows="Microsoft SharePoint"          xmlns="http://schemas.microsoft.com/sharepoint/">   <NavBars />   <DocumentTemplates />   <Configurations>     <Configuration  Name="NewWeb" />     <Configuration  Name="Default">       <Lists>       </Lists>       <Modules>         <Module Name="Default" />       </Modules>       <SiteFeatures />       <WebFeatures />     </Configuration>   </Configurations>   <Modules>     <Module Name="Default" Url="" >       <File Url="default.aspx" NavBarHome="True" Type="Ghostable"></File>     </Module>   </Modules> </Project> 

The basic structure defines core project attributes, navigation bars, document templates, configurations that group functionality, and modules that define files to be deployed-both static files and Web Part pages that can contain preconfigured Web Part instances upon page creation.

Tip 

Note that almost everything that can be defined in a site definition can also be defined in a feature. Features should be used for implementation, and site definitions should be used to aggregate features into user-creatable site templates. Both the Features element and the site definition Project element share common XML schema defined inside wss.xsd.

NavBars

The NavBars node defines navigation bars used in the site. These are optional items, but they are necessary if you’re going to use the pre-installed SharePoint navigation bars. If you’d like to simply use the default navigation scheme in your site definition, copy the contents of this node from the STS site definition. If you are building custom navigation controls and want to bypass the SharePoint navigation user interface entirely, you can skip this node. Note that navigation bars included in this node also define the Quick Launch sidebar within the Team Site, which can also be accessed by code through the object model. To add a navigation element to the Quick Launch sidebar, add an additional NavBar element to the NavBars node. Following is an example QuickNav bar that you can add through CAML in the site definition. Note that the HTML within the Prefix, Body, and Suffix attributes is XML encoded. The name of the NavBar specifies the heading of the navigation section, and each NavBarLink node represents a hyperlink.

 <NavBar Name="Site Pages"         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='/books/4/221/1/html/2//_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;"          >   <NavBarLink Name="Web Page 1" Url="SitePages/Page01.aspx" />   <NavBarLink Name="Web Page 2" Url="SitePages/Page02.aspx" />   <NavBarLink Name="Web Page 3" Url="SitePages/Page03.aspx" />   <NavBarLink Name="Web Page 4" Url="SitePages/Page04.aspx" /> </NavBar>

DocumentTemplates

The DocumentTemplates node documents are used as document library default documents within the site. You typically reuse the content from the STS site definition for this node. To do so, simply copy and paste from the STS site definition to this node. Alternatively, you can provide your own document templates for each type of document. If you do not provide document templates, the site is still created, but the user is not able to create new documents by using the New button in Document Libraries.

Configurations

Configurations are the actual creatable site templates listed in the standard pages that WSS presents to users when they want to create a new site. Each site definition can contain zero or more configurations. Without a configuration, the site definition is abstract and cannot be created; however, it can contain common infrastructure definitions, such as the Global site definition. You’ll note that you can reference components such as document templates in external site definitions, so you do not always need to have a configuration. The site definition can also have multiple configurations, but each configuration reuses the same modules, feature references, and lists. These named configurations must also be referenced in another configuration file, WEBTEMP.*.xml, to be available to Windows SharePoint Services. The following is a basic configuration inside the ONET.xml file that defines the Default configuration.

 <Configurations>   <Configuration    Name="Default">     <Lists>      </Lists>      <Modules>        <Module  Name="Default"/>     </Modules>     <SiteFeatures/>     <WebFeatures/>   </Configuration> </Configurations>

The configuration references all modules, lists, and default data that are created on site creation. To define lists within the configuration, specify the feature GUID of the list. You may need to browse the Features directory to locate this, or simply refer to the pre-installed site definitions. For example, the following List nodes specify that the Litware Customer List and Litware Vendor List be created on site creation at the site-relative Lists/Vendors and Lists/Customers URLs.

 <!–Adds the Litware Vendor List --> <List FeatureId="" Type="10001"    Title="Litware Vendors"    Url="Lists/Vendors" QuickLaunchUrl="Lists/Vendors/AllItems.aspx" /> <!-- Adds the Litware Customer List --> <List FeatureId="" Type="10002"    Title="Litware Customers"    Url="Lists/Customers" QuickLaunchUrl="Lists/Customers/AllItems.aspx" />

You might wish to refer to the lists referenced within the STS Team site definition as well include instantiations of common lists, such as Announcements. You can override certain settings of the list, including the default data. To specify a default List Item, use the Data element of the list and include a Row element for each list item. You can use CAML data-defining or HTML-rendering XML within the list item, including dynamic tags such as <TodayISO/>, as long as the elements are escaped. The following code defines a default announcement that is created for the list instance that expires the same day it is created.

 <List FeatureId="" Type="104"       Title="Announcements"       Url="$Resources:core,lists_Folder;/$Resources:core,announce_Folder;">   <Data>     <Rows>       <Row>         <Field Name="Title">            $Resources:Litware,DefaultAnnoucementTitle;</Field>         <Field Name="Body">            $Resources:Litware,DefaultAnnoucementBody;</Field>         <Field Name="Expires">&lt;ows:TodayISO/&gt;</Field>       </Row>     </Rows>   </Data> </List>

Within the configuration, you can also specify which features should be a part of this site collection or site. The SiteFeatures node lets you define features to be enabled for the site collection if the site is created as the site collection’s top-level site. For site features, you want to include common infrastructure such as the BasicWebParts feature, as well as any additional infrastructure such as a feature that installs your company’s custom .webpart Web Part entries in the Web Part gallery.

For features scoped to the site collection (Scope="Site"), you want to reference any custom features that are logically part of the site definition. The following code defines the basic Web Part feature that installs WSS Web Part entries in the site collection Web Part gallery and also the Team Collaboration feature that includes the basic WSS lists. Note that this feature does not create instances of the lists, but only enables their future creation on the site level.

 <SiteFeatures>   <!-- The Basic Web Parts feature installs the WSS Web Part entries. -->   <Feature ID="" /> </SiteFeatures> <WebFeatures>   <!-- The Team Collaboration feature includes the basic site lists. -->   <Feature ID="" /> </WebFeatures>

Configuration Modules

Modules are referenced in the configuration section to specify creation upon a specific configuration. They are not defined within the configuration, however, which means that several configurations can share the same modules. You can have references to as many modules as you like. For example, to include a single file Module named “Default” in the site configuration, simply reference the module in the configuration as follows:

 <Configuration  Name="Default">     <Modules>         <Module Name="Default" />     </Modules> </Configuration>

Modules

We initially introduced Module elements in Chapter 3, “Pages and Design.” As you remember, a Module element is a defined file set with nested File elements that are used to provision page instances from page templates. A Module element was also used in Chapter 4, “Web Parts,” to demonstrate a feature that copies .webpart and .dwp files into the Web Part gallery. In addition to provisioning pages and Web Part description files, a Module element can also be used to provision many other types of files as well such as documents, images, and Cascading Style Sheet (CSS) files.

Because WSS 2.0 did not provide support for features, modules could be included only in site definitions. Therefore, modules were added to site definitions anytime there was a requirement to provision an .aspx page or copy a .dwp file into the Web Part gallery. With the introduction of features in WSS 3.0, it doesn’t make sense to include the same number of modules inside a site definition. It’s better to maintain the majority of your modules inside features instead. However, there are still times when you should use a module inside a site definition, such as when you need to provision a page instance named default.aspx from a custom page template to provide the home page for a new site.

As you remember from Chapter 3, the File element within a Module element provides the flexibility to prepopulate Web Part instances within a Web Part page as part of the provisioning process. You can also specify an alternate location for module files either from another installed site definition or from a feature. The following module specifies the home page from the STS site definition and specifies which list view Web Parts should be instantiated on the page.

 <Module Name="Default" Url="" SetupPath="sitetemplates\sts">  <File Url="default.aspx" NavBarHome="True" Type="Ghostable">     <View List="$Resources:core,lists_Folder;/ $Resources:core,announce_Folder;" BaseView WebPartZone WebPartOrder="0" />     <View List="Lists/Vendors" BaseView WebPartZone WebPartOrder="1" />     <View List="Lists/Customers" BaseView WebPartZone WebPartOrder="2" />   </File> </Module>

Alternatively, you could also specify a page deployed in any folder under the path \\Program Files\Common Files\Microsoft Shared\web server extensions\12. Note that the referenced file does not need to be part of a feature or site definition, although you might want to make it part of a packaged feature that is part of a WSS solution package. The following Module element specifies Page01.aspx from the CustomSitePages feature (see Chapter 3) to be instantiated as “default.aspx” within the site.

 <Module Name="Default" Url="" SetupPath="features\customsitepages">   <File Url="default.aspx"     NavBarHome="True"     Type="Ghostable"     Path="PageTemplates\Page01.aspx" /> </Module>

The most common use of the site definition module is to use either the pages defined in STS or custom pages that are defined in a feature or are unique to the site definition. In the latter case, you would simply include the page in the root of the site definition and would not specify the SetupPath attribute of the Module element. You would not rename the file by using the Url attribute of the File element.

Web Template Files

The last component of the site definition is the WEBTEMP file. The WEBTEMP file references configurations in the site definition’s ONET.xml file. Each site definition solution you create should have its own WEBTEMP file, with the following naming convention: WEBTEMP.[solution].xml The WEBTEMP file has one Template node per site definition and a Configuration node for each configuration.

 <Templates xmlns:ows="Microsoft SharePoint" >   <Template Name="LitwareCustomer" >     <Configuration                  Hidden="FALSE"         Title="Litware Marketplace Site"         Description="Create a Litware Marketplace site."         ImageUrl="/_layouts/images/litware/LITWARE_PREV.PNG"         DisplayCategory="Litware"         RootWebOnly="false"         SubWebOnly="false" />   </Template> </Templates>

Earlier in the chapter, we mentioned that it is actually the configuration and not the site definition itself that provides a creatable site template. The configuration defines a Hidden attribute that WSS uses to determine whether it should be shown to users on the standard WSS application pages used to create new sites. The Title and Description attributes are important for those configurations that will be presented to users as creatable site templates. The ImageUrl attribute can used to reference a graphic image that is shown to the user when the configuration is selected.

The DisplayCategory attribute allows you to add a custom configuration to one of the existing tabs already used by WSS, such as Collaboration or Meetings. MOSS adds two additional tabs of its own, Enterprise and Publishing. Assigning a unique value to the DisplayCategory attribute causes WSS to create a new tab to display your configuration to users, as with the Litware tab shown in Figure 9-2.

Figure 9-2: Configurations with a Hidden attribute value of false are shown to users as creatable site templates.

Finally, note that a Configuration element can contain two other attributes, RootWebOnly and SubWebOnly. Add the RootWebOnly attribute and assign it a value of true if you want to create a configuration that can be used only to create the top-level site within a site collection. Add the SubWebOnly attribute and assign it a value of true if you want to create a configuration that can be used only to create child sites within a site collection. For obvious reasons, both of these attributes cannot be assigned a value of true within the same configuration. When you use these attributes and assign a value of true, WSS ensures that the configuration is shown to users only at the appropriate times.

Accessing CAML Schema Through the URL Protocol

You can access the site definition project schema (localized ONET.xml file) for any WSS site for which you are an administrator by using the site-relative URL _vti_bin/ owssvr.dll?Cmd=GetProjSchema. When you access this URL, you are viewing a cached version of the parsed site definition, which contains the runtime values for the resource strings. You can also use this URL endpoint to access other CAML definitions, such as list schema, or to access list data. For more information, see the Software Development Kit (SDK) topic “Using the URL Protocol.”

Adding a Site Provisioning Provider

WSS supports a component type known as a Site Provisioning Provider that can be configured to execute custom code during the site creation process. This makes it possible to add custom provisioning code to a site definition that complements CAML-based provisioning instructions by using the WSS object model to create site elements such as new pages, navigation menu items, and security groups. A Site Provisioning Provider can also be used to create portal-style sites that have a predefined hierarchy of child sites.

To create a Site Provisioning Provider, you must create a class that inherits from the SPWebProvisioningProvider class. This class must be compiled into an assembly DLL with a strong name and installed in the Global Assembly Cache (GAC) before it can be used. A site definition can reference a Site Provisioning Provider class from inside a configuration within the Web template file. The following example of the Web template file named WEBTEMP .LitwarePortal.xml is included in the sample code for this chapter within a Visual Studio project named LitwarePortal.

 <Templates xmlns:ows="Microsoft SharePoint" >   <Template Name="LITWAREPORTAL" >     <Configuration          Title="Litware Portal (LITWAREPORTAL#0)"         Hidden="TRUE" />     <Configuration          Title="Litware Portal"         Hidden="FALSE"         ImageUrl="/_layouts/images/litware/LITWARE_PREV.PNG"         Description="Use this site template for a site with subsite."         DisplayCategory="Litware"         RootWebOnly="true"         ProvisionAssembly="LitwarePortal, [full 4-part assembly name]"         Provision         ProvisionData="Litware Portal Site" />   </Template> </Templates>

As you can see, there are two different configurations of the LitwarePortal site definition. The first configuration, named LITWAREPORTAL#0, is hidden and does not have an associated Site Provisioning Provider. However, the second configuration, named LITWAREPORTAL#1, is shown to users and is defined with a ProvisionAssembly attribute and a ProvisionClass attribute to reference a specific Site Provisioning Provider class. A third optional attribute, named ProvisionData, can be used to pass string data from the Web template file to the Site Provisioning Provider component.

Within the Site Provisioning Provider, you can override the Provision method to handle the site creation. The Provision method passes a single parameter of type SPWebProvisioningProperties that provides you with access to the SPWeb object for the site being created as well as for the string-based provisioning data passed from the Web template file. Within this Provision method, you should call the ApplyWebTemplate method and pass a specific site definition configuration to process the CAML-based provisioning instructions. The following code is a starting point for creating a Site Provisioning Provider.

 using System; using Microsoft.SharePoint; namespace LitwarePortal {   public class ProvisioningProvider : SPWebProvisioningProvider {     public override void Provision(SPWebProvisioningProperties properties){       // apply template using a configuration       properties.Web.ApplyWebTemplate("LITWAREPORTAL#0");       // TODO: add extra code here to customize the new site.     }   } }

Note in this example that the Site Provisioning Provider is configured to run on the configuration named LITWAREPORTAL#1, yet the call to ApplyWebTemplate is made using LITWAREPORTAL#0. This is important. You should never call ApplyWebTemplate on a configuration that has an associated Site Provisioning Provider. If you do, your code will be called recursively, resulting in an infinite loop of calls to ApplyWebTemplate. Instead, you should call ApplyWebTemplate on a configuration such as LITWAREPORTAL#0 that does not have an associated Site Provisioning Provider class. Therefore, site definitions that have Site Provisioning Providers must be created with at least two configurations, as in the LitwarePortal project example.

Another tricky aspect to writing a Site Provisioning Provider has to do with changing the security context before you begin to program against the new site using the WSS object model. After calling ApplyWebTemplate, you need to make a call to the RunWithElevatedPrivileges method to switch the code’s execution context so that it runs as the SHAREPOINT\system account. Chapter 10, “Application Security,” discusses the advanced security concepts involved with this example. At that point, we will cover the details associated with a call to RunWithElevatedPrivileges. For now, let us simply show you the code inside the Provision method of a Site Provisioning Provider that is written against the WSS object model to change the Title of the site and create two child sites below it.

 public override void Provision(SPWebProvisioningProperties properties) {   // apply template using a configuration   properties.Web.ApplyWebTemplate("LITWAREPORTAL#0");   // elevate privileges before programming against site   SPSecurity.RunWithElevatedPrivileges(delegate() {     using (SPSite siteCollection = new SPSite(properties.Web.Site.ID)) {       using (SPWeb site = siteCollection.OpenWeb(properties.Web.ID)) {         // update site properties         site.Title = properties.Data;         site.Update();         // create child sites using Blank Site template         site.Webs.Add("Child1", "Child Site 1", "",                        1033, "STS#1", false, false);         site.Webs.Add("Child2", "Child Site 2", "",                        1033, "STS#1", false, false);       }     }   }); }