Share via

Introduction to Templates and Definitions

  • Article

Microsoft Windows SharePoint Services is designed as a platform to support different types of sites. SharePoint Team Services 1.0 from Microsoft included only one definition for instantiating sites, the "Team Site," but Windows SharePoint Services extends the template architecture so that multiple site definitions and templates can be used in a deployment. Site definitions consist of multiple XML files located in the file system of a front-end Web server. Custom templates are created through the user interface or through the object model and are stored in the database, providing a means for reusing customized lists and sites.

Custom Templates

A custom template is a customization applied to a site definition. When a user customizes a site or list in the user interface, the custom template consists of the difference between the original state of the site or list as determined by its definition and the state of the site when the custom template is generated. Custom templates remain tied to a particular site definition (for example, the one for a SharePoint site or a Meeting Workspace site), so that if the site definition is not present or is changed, the custom template will not work.

A custom template is persisted as a file with an .stp extension, which is actually a .cab file that can be renamed with the .cab file extension and opened in Windows Explorer. This file includes one Manifest.xml file in Collaborative Application Markup Language (CAML) that the server generates as a subset of the Microsoft SharePoint Migration Tool (Smigrate.exe) manifest file format.

Custom templates include both list templates and site templates.

List templates contain the files, views, fields, Web Parts, and, optionally, the content that is associated with a list. Users create list templates on the Save as Template page for a list or through code that uses the SaveAsTemplate method of the SPList class. When saved, list templates are stored in the List Template Gallery of the top-level site in a site collection, where they become available to all sites in the site collection that derive from the same site definition and language as the site on which the list was originally created. To make a list template available to a site in another site collection, download the template from its current gallery and then upload it to the gallery of the new site collection.

Site templates contain the same type of data as list templates, but site templates include data for the entire site. Like list templates, site templates may also include the content of the site.

Note  The maximum size for the content is 10 megabytes (MB).

Users create site templates on the Save Site as Template page or through code that uses the SaveAsTemplate method of the SPWeb class. When saved, site templates are stored in the Site Template Gallery of the top-level site in a site collection, where they become available for subsite creation on all sites in the site collection. Similarly to list templates, site templates can be downloaded and moved to other site collection galleries. Unlike list templates, however, site templates can also be moved into the Central Site Template Gallery, where they become available for top-level site creation in Self-Service Site Creation in addition to subsite creation. To add a site template to the gallery from the command line, download the site template from the gallery, run stsadm.exe -o addtemplate -filename Template_File_Name -title Template_Title [-description Template_Description], and reset Internet Information Services (IIS). In code, use the AddCustomGlobalWebTemplate method of the SPGlobalAdmin class to add a site template to the gallery.

Site templates can include list templates. When a top-level site is saved as a template with content, it includes any list templates that are in the List Template Gallery for the site collection.

Site Definitions

A site definition defines a unique type of SharePoint site. Natively installed definitions in Windows SharePoint Services include the STS type, which defines the Team Site, Blank Site, and Document Workspace configurations, and the MPS type, which defines the Basic Meeting Workspace, Blank Meeting Workspace, Decision Meeting Workspace, Social Meeting Workspace, and Multipage Meeting Workspace configurations. Each site definition emerges through a combination of multiple files that are placed in the Local_Drive:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ subdirectories on one or more front-end Web servers during installation of Windows SharePoint Services. Site definition files include core schema XML files, .aspx pages, document template files (.dot, .htm, and so on), and content files (.gif, .doc, and so on).

Ghosting

Site definition files are cached in memory on the server at process startup of Microsoft Internet Information Services (IIS), which improves scalability and performance by reducing unnecessary data storage or retrieval, and by allowing uncustomized pages to be reused across sites. The information contained in these files is pulled from the cache at run time. Pages and list schemas are read from the site definition files but appear to be actual files within a site, which is why these files are referred to as "ghosted." Ghosted pages are therefore pages whose actual content does not reside in the database but on disk, although a row for each page can be found in the database containing a column value that points to the page source in the file system. New Web Part Pages are also ghosted.

When site pages are customized, excluding browser-based customizations such as modifications to Web Parts, the pages become "unghosted" and their contents are stored in the database. Windows SharePoint Services does not natively provide a means for "re-ghosting" pages. In addition, uploaded .aspx files are considered unghosted automatically. The contents of unghosted pages are routed through the Safe Mode parser, which prevents server-side code from executing, and which depends entirely on the Safe Controls list specified in the web.config file of the wwwroot directory to determine which controls can be rendered at run time.

Core Schema Files

The following table describes prominent XML files that can be modified for a site definition and shows their locations in the file system.

DOCICON.XML WEBTEMP.XML ONET.XML SCHEMA.XML
Maps file ProgIDs and file extensions of document types to specific icons and to controls for opening each type. Specifies configurations for site definitions. Defines the navigation areas, specifies the list definitions available on the Create Page, specifies document templates and their files, defines the base types for lists, and defines configurations and modules for site definitions. Defines the views, forms, toolbar, and special fields in a list definition. Each definition has its own SCHEMA.XML file.
\TEMPLATE\XML \TEMPLATE\1033\XML \TEMPLATE\1033\STS\XML \TEMPLATE\1033\STS\LISTS\List_Definition_Name

Each of these XML files uses Collaborative Application Markup Language (CAML) as the conveyor for defining various aspects of a site, but three of them stand out in relation to customizing site definitions: WEBTEMP.XML, ONET.XML, and SCHEMA.XML.

WEBTEMP.XML specifies which configurations are available for creating sites, but this file can also be modified to hide an existing configuration from the Template Selection page. If you are creating a site definition, instead of editing the original WEBTEMP.XML file, it is required that you create a custom WEBTEMP*.XML file as described in Creating a Site Definition from an Existing Site Definition. Windows SharePoint Services merges the contents of all files that match WEBTEMP*.XML when showing available configurations on the Template Selection page. This makes it easier to install and uninstall site definitions, because their contents do not have to be merged into one WEBTEMP.XML file.

ONET.XML defines the top navigation and Quick Launch areas, specifies which list types are available on the Create Page, specifies document templates and their file types, and defines the base types for lists, which include Generic List, Document Library, Discussion Forum, Vote or Survey, and Issues List. In addition, ONET.XML defines the configurations and modules in the site definition. A configuration specifies the set of lists and modules that are included when a site is created, and a module specifies the file or files to include during site creation and the location where they are stored. For more information about configurations, see Using Configurations and Configuration. For more information about modules, see Using Modules to Add Files to a Site Definition and Module. In ONET.XML, you can reference a list that is defined in a different site definition by adding a ListTemplate element to the ListTemplates section and setting its Path attribute to the name of the directory for the site definition (for example, STS).

SCHEMA.XML defines the views, forms, toolbar, and any special fields for a list type. For examples of creating or customizing list definitions, see Adding a Field to a List Definition and Creating a List Definition for a Custom List.

For more information about the schema files used in a Windows SharePoint Services deployment, see Major Schema Files.

For the following reasons, it is required that you create a new site definition rather than modify an originally installed site definition:

  • Use of repairs and service packs could revert your modifications.
  • Custom templates based on the original site definitions may not work.
  • Site definitions with references to original list definitions may not work.

It is safe, however, to mark configurations as hidden in the original WEBTEMP.XML file by setting the Hidden attribute of the Configuration element to TRUE.

Pros and Cons

Customization of site definitions holds the following advantages over custom templates:

  • Data is stored directly on the Web servers, so performance is typically better.
  • A higher level of list customization is possible through direct editing of a SCHEMA.XML file.
  • Certain kinds of customization to sites or lists require use of site definitions, such as introducing new file types, defining view styles, or modifying the drop-down Edit menu.

Site definition disadvantages include the following:

  • Customization of site definition requires more effort than creating custom templates.
  • It is difficult to edit a site definition after it has been deployed.
  • Doing anything other than adding code can break existing sites.
  • Users cannot apply a SharePoint theme through a site definition.
  • Users cannot create two lists of the same type with different default content.
  • Customizing site definitions requires access to the file system of the front-end Web server.

Custom templates hold the following advantages over customization of site definitions:

  • Custom templates are easy to create.
  • Almost anything that can be done in the user interface can be preserved in the template.
  • Custom templates can be modified without affecting existing sites that have been created from the templates.
  • Custom templates are easy to deploy.

Custom template disadvantages include the following:

  • Custom templates are not created in a development environment.
  • They are less efficient in large-scale environments.
  • If the site definition on which the custom template is based does not exist on the front-end server or servers, the custom template will not work.