Using Configurations

Article
03/25/2009

If you are creating a site definition, configurations allow you to specify which lists to include in the creation of a site. Through configurations, you can reuse existing list definitions in the ONET.XML file for a given site definition, which prevents you from having to copy or recode list definitions. You can create multiple configurations in one ONET.XML file, each one enabling the creation of a site with a different set of lists.

Warning It is required that you create a custom site definition by copying an existing site definition, rather than modifying the original files installed with Windows SharePoint Services. Changes that you make to originally installed files may be overwritten when you install updates or service packs for Windows SharePoint Services, or when you upgrade an installation to the next product version. For information on creating a custom site definition, see Creating a Site Definition from an Existing Definition.

To set up a configuration within a site definition, use Configuration elements within a custom WEBTEMP*.XML file and within one or more ONET.XML files that are referenced in the WEBTEMP file. For information on how to create a custom WEBTEMP*.XML file, see Creating a Site Definition from an Existing Definition.

For example, the following WEBTEMP*.XML file uses two configurations to define different configurations for instantiating a site, one for a Research Collaboration site and the other for a Research Document Workspace site. This example involves use of only two configurations within a single site definition, but you can include multiple definitions with different configurations within a single WEBTEMP*.XML file, each one referencing different site definition directories and their respective ONET.XML files.

<?xml version="1.0" encoding="utf-8" ?>
<Templates xmlns:ows="Microsoft SharePoint">
   <Template Name="RESEARCH" ID="95">
      <Configuration ID="0" Title="Research Collaboration site" Type="0" Hidden="FALSE"
         ImageUrl="images/stsprev.jpg" Description="This definition creates a site for the Research
         team to create, organize, and share general information.">
      </Configuration>
      <Configuration ID="1" Title="Research Workspace" Type="0" Hidden="FALSE"
         ImageUrl="images/dwsprev.jpg" Description="This definition creates a site for Research
         team colleagues to work together on specific documents. ">
      </Configuration>
   </Template>
</Templates>

As indicated by the value of the Name attribute in the Template element, this example assumes that a site definition directory called "RESEARCH" exists. If a WEBTEMP*.XML file specifies more than one site definition, the definitions are distinguished by their unique ID values.

Each Configuration element also contains an ID attribute, which references a specific configuration defined in the ONET.XML file. The combination of this ID and the value of the Name attribute in the Template element provides a reference to the contents of a specific Configuration element in a specific ONET.XML file. In the example, the Name attribute contains RESEARCH and the ID attributes contain 0 and 1, which reference the RESEARCH site definition and configurations with IDs of 0 or 1 in ONET.XML.

In the ONET.XML file, each configuration defines a specific type of site that can be created from the site definition. All configurations within this file share a set of available list definitions, document templates, navigation areas, base list types, and modules that are defined within the file. You can add a reference to a list that is defined in ONET.XML by adding a List element to the collection of lists specified within a Configuration element. For example, if you define a list type named "My_Custom_List" in ONET.XML with a Type attribute of 143, then you can add <List Title="My_Custom_List" Type="143" Url="Lists/My_Custom_List" /> to make the list part of the configuration. The following example shows the arrangement of configurations in an ONET.XML file for a specific WEBTEMP*.XML file:

<Configurations>
    <Configuration ID="0" Name="Default">
       <Lists>
          <List Title="My_Custom_List" Type="143" Url="Lists/My_Custom_List" />
          <List Title="Shared Documents"  Url="Shared Documents"  QuickLaunchUrl="Shared Documents/Forms/AllItems.aspx"
             Type="101" />
          <List Title="General Discussion" Url="Lists/General Discussion" QuickLaunchUrl="Lists/General Discussion/AllItems.aspx"
             Type="108" />
          <List Title="Announcements" Type="104" Url="Lists/Announcements" />
          <List Title="Links" Type="103" Url="Lists/Links" />
          <List Title="Contacts" Url="Lists/Contacts" QuickLaunchUrl="Lists/Contacts/AllItems.aspx" Type="105" />
          <List Title="Events" Type="106" Url="Lists/Events" />
          <List Title="Tasks" Url="Lists/Tasks" QuickLaunchUrl="Lists/Tasks/AllItems.aspx" Type="107" />
          <List Title="Site Template Catalog" Type="111" Url="_catalogs/wt" RootWebOnly="TRUE" />
          <List Title="Web Part Catalog" Type="113" Url="_catalogs/wp" RootWebOnly="TRUE" />
          <List Title="List Template Catalog" Type="114" Url="_catalogs/lt" RootWebOnly="TRUE" />
       </Lists>
       <Modules>
          <Module Name="Default"/>
          <Module Name="WebPartPopulation"/>
       </Modules>
    </Configuration>
    <Configuration ID="1" Name="DWS">
       <Lists>
          <List Title="Shared Documents" Type="101" />
          <List Title="Image Library" Type="109" />
          <List Title="General Discussion" Url="Lists/General Discussion"
             QuickLaunchUrl="Lists/General Discussion/AllItems.aspx" Type="108" />
          <List Title="Announcements" Type="104" Url="Lists/Announcements" />
          <List Title="Contacts" Url="Lists/Contacts" QuickLaunchUrl="Lists/Contacts/AllItems.aspx"
             Type="105" />
          <List Title="Links" Type="103" Url="Lists/Links" />
          <List Title="Events" Url="Lists/Events" QuickLaunchUrl="Lists/Events/AllItems.aspx"
             Type="106" />
          <List Title="Tasks" Type="107" />
          <List Title="Site Template Catalog" Type="111" Url="_catalogs/wt" RootWebOnly="TRUE" />
          <List Title="Web Part Catalog" Type="113" Url="_catalogs/wp" RootWebOnly="TRUE" />
          <List Title="List Template Catalog" Type="114" Url="_catalogs/lt" RootWebOnly="TRUE" />
       </Lists>
       <Modules>
          <Module Name="DWS"/>
          <Module Name="WebPartPopulation"/>
       </Modules>
    </Configuration>
 </Configurations>

The value of the ID attribute for each Configuration element corresponds to the IDs specified in the WEBTEMP*.XML file for configurations. In this example, the default site is a Research Collaboration site (0), and not a Research Document Workspace site (1). The Type attribute for each List element references a list type defined in ONET.XML. The Url attribute contains the URL for the folder containing the list definition for each list, which includes the ASPX files, SCHEMA.XML, and any related files. When specified, the QuickLaunchUrl attribute contains the full path to the AllItems.aspx file for a list, which displays the list in the Quick Launch area.

Using Configurations

Additional resources