Understanding Onet.xml Files
Applies to: SharePoint Foundation 2010
When Microsoft SharePoint Foundation is installed, several Onet.xml files are installed—one in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\GLOBAL\XML that applies globally to the deployment, and several in different folders within %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates. Each file in the latter group corresponds to a site definition that is included with SharePoint Foundation. They include, for example, Blog sites, the Central Administration site, Meeting Workspace sites, and team SharePoint sites. Only the last two of these families contain more than one site definition configuration.
The global Onet.xml file defines list templates for hidden lists, list base types, a default definition configuration, and modules that apply globally to the deployment. Each Onet.xml file in a subdirectory of the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates directory can define navigational areas, list templates, document templates, configurations, modules, components, and server email footers that are used in the site definition to which it corresponds.
Note
An Onet.xml is also part of a web template. Some Collaborative Application Markup Language (CAML) elements that are possible in the Onet.xml files of site definitions cannot be in the Onet.xml files that are part of web templates—for example, the DocumentTemplates element.
Functions of Onet.xml
Depending on where an Onet.xml file is located and whether it is part of a site definition or a web template, the markup in the file does some or all of the following:
Specifies the web-scoped and site collection-scoped Features that are built-in to websites that are created from the site definition or web template.
Specifies the list types, pages, files, and Web Parts that are built-in to websites that are created from the site definition or web template.
Defines the top and side navigation areas that appear on the home page and in list views for a site definition.
Specifies the list definitions that are used in each site definition and whether they are available for creating lists in the user interface (UI).
Specifies document templates that are available in the site definition for creating document library lists in the UI, and specifies the files that are used in the document templates.
Defines the base list types from which default SharePoint Foundation lists are derived. (Only the global Onet.xml file serves this function. You cannot define new base list types.)
Specifies SharePoint Foundation components.
Defines the footer section used in server email.
Web Site Definition Tasks with a Custom Onet.xml
You can perform the following kinds of tasks in a custom Onet.xml file that is used for either a custom site definition or a custom web template:
Specify an alternative cascading style sheet (CSS) file, JavaScript file, or ASPX header file for a site definition.
Modify navigation areas for the home page and list pages.
Add a new list definition as an option in the UI.
Define one configuration for the site definition or web template, specifying the lists, modules, files, and Web Parts that are included when the configuration is instantiated.
Specify Features to be included automatically with websites that are created from the site definition or web template.
You can perform the following kinds of tasks in a custom Onet.xml file that is used for a custom site definition, but not in one that is used for a custom web template:
Add a document template for creating document libraries.
Define more than one configuration for a site definition, specifying the lists, modules, files, and Web Parts that are included when the configuration is instantiated.
Define a custom footer for email messages that are sent from websites that are based on the site definition.
Define custom components, such as a file dialog box post processor, for websites that are based on the site definition.
Warning
You cannot create new base list types in either a site definition or a web template. The base types that are defined in the global Onet.xml file are the only base types that are supported.
Warning
We do not support making changes to an originally installed Onet.xml file. Changing this file can break existing sites. Also, when you install updates or service packs for SharePoint Foundation, or when you upgrade an installation to the next product version, there may be a new version of the Microsoft-supplied file, and installation cannot merge your changes with the new version. If you want a site type that is similar to a built-in site type, and you cannot use a web template, create a new site definition with its own Onet.xml file; do not modify the original file. For more information, see How to: Create a Custom Site Definition and Configuration. For more information about when you cannot use a web template, see Deciding Between Custom Web Templates and Custom Site Definitions.
File Format
The following sections define the various elements of the Onet.xml file.
Project Element
The top-level Project element specifies a default name for sites that are created through any of the site configurations in the site definition. It also specifies the directory that contains subfolders in which the files for each list definition reside.
Note
Unless indicated otherwise, excerpts used in the following examples are taken from the Onet.xml file for the STS site definition.
<Project
Title="$Resources:core,onet_TeamWebSite;"
Revision="2"
ListDir="$Resources:core,lists_Folder;"
xmlns:ows="Microsoft SharePoint"
UIVersion="4">
Note
In all the examples in this topic, the strings that begin with "$Resources" are constants that are defined in a .resx file. For example, "$Resources:onet_TeamWebSite" is defined in the core.resx file as "Team Site". When you create a custom Onet.xml file, you can use literal strings.
This element can also have several other attributes. For more information, see Project Element (Site).
The Project element does not contain any attribute that identifies the site definition that it defines. Each Onet.xml file is associated with a site definition by virtue of the directory path in where it resides, which (except for the global Onet.xml) is %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates\site_type\XML\, where site_type is the name of the site definition, such as STS or MPS. The Onet.xml file for a web template is associated with the template by virtue of being in the .wsp package for the web template.
NavBars Element
The NavBars element contains definitions for the top navigation area that is displayed on the home page or in list views, and definitions for the side navigation area that is displayed on the home page.
Note
A NavBar is not necessarily a toolbar. For example, it can be a tree of links.
<NavBars>
<NavBar
Name="$Resources:core,category_Top;"
Separator="&nbsp;&nbsp;&nbsp;"
Body="<a ID='onettopnavbar#LABEL_ID#' href='#URL#' accesskey='J'>#LABEL#</a>"
ID="1002" />
<NavBar
Name="$Resources:core,category_Documents;"
Prefix="<table border='0' cellpadding='4' cellspacing='0'>"
Body="<tr><td><table border='0' cellpadding='0' cellspacing='0'><tr><td><img src='/_layouts/images/blank.gif' id='100' alt='' border='0'>&nbsp;</td><td valign='top'><a id='onetleftnavbar#LABEL_ID#' href='#URL#'>#LABEL#</td></tr></table></td></tr>"
Suffix="</table>"
ID="1004" />
...
</NavBars>
A NavBarLink element defines links for the top or side navigational area, and an entire NavBar section groups new links in the side area. Each NavBar element specifies a display name and a unique ID for the navigation bar, and it defines how to display the navigation bar.
For information about customizing the navigation areas on SharePoint Foundation pages, see Website Navigation.
ListTemplates Element
The ListTemplates section specifies the list definitions that are part of a site definition. This markup is still supported only for backward compatibility. New custom list types should be defined as Features. The following example is taken from the Onet.xml file for the Meetings Workspace site definition.
<ListTemplates>
<ListTemplate
Name="meetings"
DisplayName="$Resources:xml_onet_mwsidmeetingDisp;"
Type="200"
BaseType="0"
Unique="TRUE"
Hidden="TRUE"
HiddenList="TRUE"
DontSaveInTemplate="TRUE"
SecurityBits="11"
Description="$Resources:xml_onet_mwsidmeetingDesc;"
Image="/_layouts/images/itevent.gif">
</ListTemplate>
<ListTemplate
Name="agenda"
DisplayName="$Resources:xml_onet_mwsidagendaDisp;"
Type="201"
BaseType="0"
FolderCreation="FALSE"
DisallowContentTypes="TRUE"
SecurityBits="11"
Description="$Resources:xml_onet_mwsidagendaDesc"
Image="/_layouts/images/itagnda.gif">
</ListTemplate>
...
</ListTemplates>
Each ListTemplate element specifies an internal name that identifies the list definition. The ListTemplate element also specifies a display name for the list definition and whether the option to add a link on the Quick Launch bar appears selected by default in the list-creation UI. In addition, this element specifies the description of the list definition and the path to the image that represents the list definition, both of which are displayed in the list-creation UI. If Hidden="TRUE" is specified, the list definition does not appear as an option in the list-creation UI.
The ListTemplate element has two attributes for type: Type and BaseType. The Type attribute specifies a unique identifier for the list definition, and the BaseType attribute identifies the base list type for the list definition and corresponds to the Type value that is specified for one of the base list types that are defined in the global Onet.xml file.
For more information about creating new list types, see How to: Create a Custom List Definition.
DocumentTemplates Element
The DocumentTemplates section defines the document templates that are listed in the UI for creating a document library. This markup is still supported only for backward compatibility. You should define new document types as content types. For more information, see the Content Types section of this SDK.
<DocumentTemplates>
...
<DocumentTemplate
Path="STS"
DisplayName="$Resources:core,doctemp_Word;"
Type="121"
Default="TRUE"
Description="$Resources:core,doctemp_Word_Desc;">
<DocumentTemplateFiles>
<DocumentTemplateFile
Name="doctemp\word\wdtmpl.dotx"
TargetName="Forms/template.dotx"
Default="TRUE" />
</DocumentTemplateFiles>
</DocumentTemplate>
...
</DocumentTemplates>
Each DocumentTemplate element specifies a display name, a unique identifier, and a description for the document template. If Default is set to TRUE, the template is the default template selected for document libraries that are created in sites based one of the configurations in the site definition. Despite its singular name, a DocumentTemplate element actually can contain a collection of DocumentTemplateFile elements. The Name attribute of each DocumentTemplateFile element specifies the relative path to a local file that serves as the template. The TargetName attribute specifies the destination URL of the template file when a document library is created. The Default attribute specifies whether the file is the default template file.
Note
An Onet.xml file in a web template cannot have a DocumentTemplate element.
For a development task that involves document templates, see How to: Add a Document Template, File Type, and Editing Application to a Site Definition.
BaseTypes Element
The BaseTypes element of the global Onet.xml file is used during site or list creation to define the basic list types on which all list definitions in SharePoint Foundation are based. Each list template that is specified in the list templates section is identified with one of the base types: Generic List, Document Library, Discussion Forum, Vote or Survey, or Issues List.
Note
In SharePoint Foundation the BaseTypes section is implemented only in the global Onet.xml file, from which the following example is taken.
<BaseTypes>
<BaseType
Title="Generic List"
Image="/_layouts/images/itgen.gif"
Type="0">
<MetaData>
<Fields>
<Field
ID="{1d22ea11-1e32-424e-89ab-9fedbadb6ce1}"
ColName="tp_ID"
RowOrdinal="0"
ReadOnly="TRUE"
Type="Counter"
Name="ID"
PrimaryKey="TRUE"
DisplayName="$Resources:core,ID"
SourceID="https://schemas.microsoft.com/sharepoint/v3"
StaticName="ID">
</Field>
<Field
ID="{03e45e84-1992-4d42-9116-26f756012634}"
RowOrdinal="0"
Type="ContentTypeId"
Sealed="TRUE"
ReadOnly="TRUE"
Hidden="TRUE"
DisplayName="$Resources:core,Content_Type_ID;"
Name="ContentTypeId"
DisplaceOnUpgrade="TRUE"
SourceID="https://schemas.microsoft.com/sharepoint/v3"
StaticName="ContentTypeId"
ColName="tp_ContentTypeId">
</Field>
...
</Fields>
</MetaData>
</BaseType>
...
</BaseTypes>
Each BaseType element specifies the fields used in lists that are derived from the base type. The Type attribute of each Field element identifies the field with a field type that is defined in FldTypes.xml.
Warning
Do not modify the contents of the global Onet.xml; doing so can break the installation. Base list types cannot be added. For information about how to add a list definition, see How to: Create a Custom List Definition.
Configurations Element
Each Configuration element in the Configurations section specifies the lists, modules, and Features that are created by default when the site definition configuration or web template is instantiated.
<Configurations>
...
<Configuration
ID="0"
Name="Default">
<Lists>
<List
FeatureId="00BFEA71-E717-4E80-AA17-D0C71B360101"
Type="101"
Title="$Resources:core,shareddocuments_Title;"
Url="$Resources:core,shareddocuments_Folder;"
QuickLaunchUrl="$Resources:core,shareddocuments_Folder;/Forms/AllItems.aspx" />
...
</Lists>
<Modules>
<Module
Name="Default" />
</Modules>
<SiteFeatures>
<Feature
ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />
<Feature
ID="FDE5D850-671E-4143-950A-87B473922DC7" />
</SiteFeatures>
<WebFeatures>
<Feature
ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" />
<Feature
ID="F41CC668-37E5-4743-B4A8-74D1DB3FD8A4" />
</WebFeatures>
</Configuration>
...
</Configurations>
The ID attribute identifies the configuration (uniquely, relative to the other configurations, if any, within the Configurations element). If the Onet.xml file is part of a site definition, the ID value corresponds to the ID attribute of a Configuration element in a WebTemp*.xml file. (Web templates do not have WebTemp*.xml files.)
Each List element specifies the title of the list definition and the URL for where to create the list. You can use the QuickLaunchUrl attribute to set the URL of the view page to use when adding a link in the Quick Launch to a list that is created from the list definition. The value of the Type attribute corresponds to the Type attribute of a template in the list templates section. Each Module element specifies the name of a module that is defined in the modules section.
The SiteFeatures element and the WebFeatures element contain references to site collection and site-scoped Features to include in the site definition.
For post-processing capabilities, use an ExecuteUrl element within a Configuration element to specify the URL that is called following instantiation of the site.
For more information about definition configurations, see How to: Create a Custom Site Definition and Configuration.
Modules Element
The Modules collection specifies a pool of modules. Any module in the pool can be referenced by a configuration if the module should be included in websites that are created from the configuration. Each Module element in turn specifies one or more files to include, often for Web Parts, which are cached in memory on the front-end web server along with the schema files. You can use the Url attribute of the Module element to provision a folder as part of the site definition. This markup is supported only for backward compatibility. New modules should be incorporated into Features.
<Modules>
<Modules>
<Module
Name="Default"
Url=""
Path="">
<File
Url="default.aspx"
NavBarHome="True">
<View
List="$Resources:core,lists_Folder;
/$Resources:core,announce_Folder;"
BaseViewID="0"
WebPartZoneID="Left" />
<View
List="$Resources:core,lists_Folder;
/$Resources:core,calendar_Folder;"
BaseViewID="0"
RecurrenceRowset="TRUE"
WebPartZoneID="Left"
WebPartOrder="2" />
<AllUsersWebPart
WebPartZoneID="Right"
WebPartOrder="1"><![CDATA[<WebPart
xmlns="https://schemas.microsoft.com/WebPart/v2"
xmlns:iwp="https://schemas.microsoft.com
/WebPart/v2/Image">
<Assembly>Microsoft.SharePoint, Version=12.0.0.0,
Culture=neutral,
PublicKeyToken=71e9bce111e9429c</Assembly>
<TypeName>Microsoft.SharePoint.WebPartPages.ImageWebPart
</TypeName>
<FrameType>None</FrameType>
<Title>$Resources:wp_SiteImage;</Title>
<iwp:ImageLink>/_layouts/images/homepage.gif
</iwp:ImageLink>
<iwp:AlternativeText>$Resources:core,sitelogo_wss;
</iwp:AlternativeText>
</WebPart>]]>
</AllUsersWebPart>
<View
List="$Resources:core,lists_Folder;
/$Resources:core,links_Folder;"
BaseViewID="0"
WebPartZoneID="Right"
WebPartOrder="2" />
<NavBarPage
Name="$Resources:core,nav_Home;"
ID="1002"
Position="Start" />
<NavBarPage
Name="$Resources:core,nav_Home;"
ID="0"
Position="Start" />
</File>
</Module>
...
</Modules>
The Module element specifies a name for the module, which corresponds to a module name that is specified within a configuration in Onet.xml.
The Url attribute of each File element in a module specifies the name of a file to create when a site is created. When the module includes a single file, such as default.aspx, NavBarHome="TRUE" specifies that the file will serve as the destination page for the Home link in navigation bars. The File element for default.aspx also specifies the Web Parts to include on the home page and information about the home page for other pages that link to it.
A Module element can only be in an Onet.xml file that is part of a site definition, not in an Onet.xml file that is part of a web template.
For more information about using modules in SharePoint Foundation, see How to: Provision a File.
Components Element
The Components element specifies components to include in sites that are created through the definition.
<Components>
<FileDialogPostProcessor ID="BDEADEE4-C265-11d0-BCED-00A0C90AB50F" />
</Components>
A Components element can only be included in an Onet.xml file that is part of a site definition, not in an Onet.xml file that is part of a web template.
ServerEmailFooter Element
The ServerEmailFooter element specifies the footer section used in email that is sent from the server.
<ServerEmailFooter>$Resources:ServerEmailFooter;</ServerEmailFooter>
A ServerEmailFooter element can only be included in an Onet.xml file that is part of a site definition, not in an Onet.xml file that is part of a web template.