SharePoint Site Definitions: Why You Need Them and How to Use Them

The site definition process in SharePoint is complex, but very flexible. Techniques such as "ghosting" can save you a lot of server space and beef up performance. But you need to understand when and how to use site definitions in order to avoid unintended consequences down the line.

by Robert Bogue

harePoint makes developing templates easy. You simply create a site the way that you want it and then save it as a template, quickly and easily freezing the site setup into a reusable stamp that you can then use to create other sites. However, user templates in SharePoint can lead to performance problems and may not be the best approach if you're trying to create a set of reusable templates for an entire organization. Instead, you should use site definitions to create templates that form the basis for creating new sites. The site definitions approach doesn't suffer from the same limitations as user templates.

Understanding Ghosting and Unghosting
Before diving into site definitions it's important to understand one of the inner workings of SharePoint. When you create a new site, SharePoint doesn't really copy the pages for that site— default.aspx and so on—into a new database table or directory. These files exist once and only once on each of the front end Web servers. Instead, SharePoint creates a reference to those files in the database tables that define the new site, a process called "ghosting." The outcome is that the site appears to have its own unique pages, but the pages are actually shared across all sites that use the same definition.

This has two distinct advantages over copying the files to each site individually when the site is created. First, it saves space. If you have a thousand sites, rather than having a thousand copies of a file you still have only one. Second, it improves performance. Instead of having to load and cache a thousand pages from the database, the server needs to cache only one copy from the file system, which can improve performance by freeing cache memory for other purposes. Loading the file from the Web server's local file system improves performance by eliminating the overhead of the database call and the network traffic to the database.

One interesting benefit of this approach is that when you make a change to one file on the file system, that change takes effect across all the sites that have been created. All in all, the process of ghosting is a huge benefit to SharePoint. However, there are some limitations.

SharePoint can't ghost every page. Some operations, such as editing a page in FrontPage, cause SharePoint to "unghost" dependent pages for the site. Because ghosting requires all ghosted pages to be exactly the same across all the sites that share them, SharePoint unghosts, or creates a copy of the page in the database, whenever a ghosted page changes, for example, when someone performs an edit operation on the page. Unghosting lets users customize their own sites without impacting other users who might be using the same file. Unfortunately however, unghosting also has a negative performance impact, and makes global changes, such as applying corporate branding to the entire collection of sites far more difficult. Unghosting is the primary reason why efforts to leverage the power of site definitions to change the branding of an entire site may not work as intended.

Exploring Site Definitions
Site definitions are the foundation on which all sites and user templates are built. They consist of a set of files found in the C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\TEMPLATE directory. For English sites you'll find the templates under the 1033 directory. This is the first evidence of a multi-lingual design for SharePoint. The 1033 number in the directory name corresponds to the US English locale ID.

Underneath this directory you'll find at least three sub-directories: XML, STS, and MPS. Except for the XML directory, each directory represents a different site definition. SharePoint stores all the files that make up the site definition in the STS and MPS directories. The XML directory contains one or more files that match the filename pattern WEBTEMP*.XML. These files list the site definitions. For example, the base WEBTEMP.XML file lists both the STS and MPS site definitions. If you install SharePoint Portal server you'll also have a WEBTEMPSPS.XML file, which contains all the site definitions for SharePoint Portal Server.

Each WEBTEMP*.XML file has a simple format that starts with a Templates tag containing a nested set of child Template tags. Each Template tag contains a set of Configuration tags. This structure lets you specify new site definitions, each of which can have an initial configuration. The template defines the look and feel while the configuration defines the initial configuration of lists and Web Parts. This becomes obvious when you view the WEBTEMP.XML file shown in Listing 1.

In the WEBTEMP.XML file in Listing 1, the Team Site, Blank Site, and Document Workspace sites all share the STS site definition, but the configuration referenced for each is different. The Configuration ID refers to a set of instructions in the ONET.XML file which, along with several other files and folders, compose a site definition.

Dissecting an Individual Site Definition
Site definitions consist of a hierarchy of files and folders that contain some specific entries. Each template requires three directories: DOCTEMP, LISTS, and XML. The XML folder contains the ONET.XML file, which is essential for creating the corresponding site. Although its contents are a bit messy, ONET.XML contains all the major settings that you need for controlling initial site creation. The XML folder also contains a STDVIEW.XML and VWSTYLES.XML, which control the most basic list display control and allow you to adapt list appearance to meet your needs. You can see these basic display types in the list of options displayed when creating a new View—standard, datasheet, and calendar view base types. Additionally, the styles section of the view settings displays the different ways that the fields in the list can be displayed together.

In the DOCTEMP folder you'll find the various template documents for the different kinds of files referred to by the ONET.XML file in the tag. These are the templates that SharePoint uses when you click the New Document button in a document library.

The LISTS folder contains a set of subfolders that correspond to the tags in the ONET.XML file. Each of these folders contains a SCHEMA.XML file that defines the fields, views, and general information about the appearance of the list within the site. The SCHEMA.XML fills essentially the same role as the ONET.XML file except that it operates within the scope of a list rather than a site.

Throughout the folder structure you'll find .aspx files. These are the Web Part pages that SharePoint uses to display your sites. Changes made to these files affect all the sites that still have that page ghosted. In essence a change to one of the .aspx files in the site definition directory can take effect across the entire set of sites created from the definition.

Dissecting the ONET.XML File
Because the ONET.XML file is a core file that tells SharePoint how to configure a newly created site, it's somewhat complicated; however, the major sections in the file are relatively straightforward after you examine them in a logical progression:

• Configurations maps the configurations referred to in the WEBTEMP*.XML file in the XML directory off of the locale ID folder. The configuration section tells SharePoint what things to include in a configuration including lists (ListTemplates), Web Parts, and Web Part pages (Modules).
• ListTemplates creates the templates for lists to be used by the configurations. It leverages the BaseTypes section to control the basic fields and other detail information, and describes global settings for the list, including its ID, descriptive text, and an image.
• BaseTypes defines the fields and views for a created list. The ListTemplates section uses the BaseTypes section to create a completely formed list.
• DocumentTemplates provide users with a list of document templates from which they can select the default document template for a Document Library when creating a document library list.
• Modules describes the files to be added to the SharePoint site and how those files should be configured. In SharePoint every Web Part page is a file. Because of this the modules section describes what Web Parts to display on a file. It also controls the appearance of the navigation bar on those pages.
• NavBars describes how the navigation bar should look. The navigation bar is the area at the top of the page that typically displays home, documents, lists, etc. This section controls the appearance of the navigation bar for all sites derived from this site definition.

While a detailed exploration of the ONET.XML file is beyond the scope of the article, here's a typical customization sequence so you can see how the process works and some of the places where the file can be modified.

Installing Your Own Site Definition
The first step in customizing a site definition is to install it into SharePoint. You start this process by copying an existing site definition and placing it into another directory. You can use any of the existing site definitions as your starting point. For demonstration purposes, copy the STS site definition folder structure to a new DEVX folder. Doing that gives you a new site definition based on the contents of the DEVX directory.

Next, connect the DEVX site definition to SharePoint by copying the WEBTEMP.XML file located in the TEMPLATE\\XML directory to a file named WEBTEMPDEVX.XML. Open the file and delete any unnecessary tags. For this example, remove the tag whose Name attribute value is "MPS." Change the Name attribute of the remaining tag from STS to DEVX, and change the ID attribute of the tag so that it is unique—generally numbers above 10000 will be safe. Finally, modify each of the Title attributes of the configuration tags so that you can easily determine which site definitions the file contains. The resulting WEBTEMPDEVX.XML file should look something like Listing 2.

The final step is to perform an IIS reset so that SharePoint "sees" the new site definition. After restarting IIS you can create a new site and see your new site definitions. Note that your new site will look exactly like an out-of-the-box Windows SharePoint Services site.

Customizing Your Site Definition
Now that you have your own site definition to work from you can customize it to meet your needs. Most people make two basic customizations. First, they customize the ONET.XML file to control how SharePoint creates new sites. Second, they change the .aspx pages to reflect other visual changes. You can make these latter changes at any time, but changes to the ONET.XML file affect only the creation of new sites, and are therefore of limited use after you've already created many sites.

Customizing ONET.XML
One of the most difficult customizations for most people seems to be adding a Web Part to a page. Earlier, I mentioned that the Configurations section of the ONET.XML file matches the configuration options in the WEBTEMP*.XML file. The ONET.XML contains a section for configuration 0—the default. This section creates several lists and then performs the actions listed in two modules. The first module, named Default, adds the default.aspx page. The second adds some Web Parts to the Web Part library—for this customization, you can ignore the second module.

Figure 1. The DEVX Default Template: This shows how a new site built on the modified DEVX Default template looks when you browse to its default.aspx page.

The Default module appears below the configuration section in the modules section and includes the appropriate reference for default.aspx as well as the lists to add to that file (page). The process of adding a new list view Web Part to the page is as simple as adding a new View tag. The List attribute in the View tag must match the ID tag from the tag in the tag from above. You should set the Web Part order so that the Web Part appears in the correct location relative to the other Web Parts in the Web Part zone that you specify. So, to add a new Web Part on the page that displays the task list, the View tag would look like this:

The 107 used in the List attribute matches the Tasks List item from the configuration. A quick IIS reset and you can create a new site based on your revised settings. If you made the changes above and created a new DEVX team site, the tasks list would appear on the default.aspx page under the events as shown in Figure 1.




Customizing the default.aspx File
Customizing default.aspx is in some ways even simpler than customizing the ONET.XML file. You can simply use Notepad to make the changes to the HTML and ASP.NET tags that you want in the file. You can also use FrontPage and edit one of the sites created from the site definition—as long as you select Save As from the file menu when you save the file and save it to another place on your machine and then copy the saved file to the site definition directory manually. This process lets you edit the file visually with FrontPage without disturbing the ghosting process that SharePoint uses.

For example, one quick and easy modification to default.aspx is to change the image that appears above the Quick Launch bar. To change the image, open default.aspx from the site definition in Notepad and search for onetidtpweb1, which is the ID of the image tag in the file (there's nothing special about searching for the tag by ID, it just helps to expedite finding the right spot in the file). In this tag replace home.gif with the name of the replacement image file that you want to use, and change the height and width attributes to match the height and width of your new image. Save the file.

The last step in making the customization is to place the image in the TEMPLATE\IMAGES directory underneath the C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60 directory where all the other SharePoint files reside.

This time, you can see the effect of your changes without resetting IIS; sites created with your new template will reflect the new graphic.

User Templates
Because of the effort that's involved in creating site definitions it's easy to get frustrated and decide to move back to just doing user templates. But then you have to deal with the unghosting and maintenance headaches of managing multiple user templates mentioned at the start of this article. Worse, there's a potentially more important concern if you're going to be managing a large environment.

Sites created with user templates do not maintain any record of the user template used to create them. However, all sites do record which site definition was used to create them. This can become important when you're trying to write utilities that manage large numbers of sites, because there's no way to determine which user template was used to create the site. If you have several well-defined types of sites on your server it may become impossible to write utilities to work on just those sites directly.

User templates are good for prototyping and for smaller SharePoint deployments where the configuration management issues relating to their tendency to allow ghosting and their inability to leave their mark on the sites that are created from them. However, larger environments would be wise to limit the use of user templates where possible.

The site definition process in SharePoint is extremely flexible, however, with that flexibility comes complexity. Site definitions consist of many interrelated files and directories, but after you understand their purposes it's easy to put all the pieces together.

Despite the complexity challenges with site definitions it's important to not slip into the trap of relying on user templates for larger deployments; otherwise, managing sites en mass becomes far more difficult than necessary.