How to: Create a Custom Site Definition and Configuration

Article
10/20/2016

Applies to: SharePoint Foundation 2010

There is no procedural code involved in creating a custom site definition. It is an entirely declarative development task. Primarily, it involves adding Collaborative Application Markup Language (CAML) markup to two critical files: a WebTemp*.xml file and an Onet.xml file. In some scenarios, you also create one or more custom site pages. If you want to ensure that your custom site type is ready for globalization, you can also use of one or more resource (.resx) files.

Sometimes a custom site type is a recombination of built-in lists types, content types, column types, and other Features that is different from any built-in site type. But more often, if your Microsoft SharePoint Foundation solution requires a new site type, it probably also involves one or more custom content types, custom field types, custom list types, custom Web Parts, custom mobile Web Part adapters, custom document templates, and so on. You should do all these kinds of subsidiary development projects first so that you can refer to these elements in the markup of your custom site definition.

To set up the project

In Microsoft Visual Studio, create a Site Definition project from the SharePoint | 2010 section of project templates. Make it a farm solution, not a sandboxed solution. Give it a name that will also function as the internal name of the site definition. Users do not see this name. By convention, site definitions are named using all uppercase letters and contain no spaces or other characters. If you will have more than one configuration in your site definition, consider that this term functions as the name of a family of custom site types, so it should be appropriate for that role. In this topic, the name RESEARCH is used for an ongoing example.

Note

The Visual Studio Site Definition project, and this documentation, generally assume that you will have only one site definition; that is, one Template element in your WebTemp*.xml file; although, again, you can have multiple custom site types, that is, multiple configurations, within the site definition. However, you can have more than one site definition in the same WebTemp*.xml file. In that case, you may want to give your project an even more generic name; for example, the name of your company. Also, if you have multiple site definitions in the same WebTemp*.xml file, you must add separate Onet.xml files to your Visual Studio project for each site definition and repeat the procedure under "To configure an Onet.xml file" for every site definition, because each must have its own Onet.xml file. You must also ensure that the solution package deploys each of them to its own subdirectory of %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates. Each such subdirectory must have the same name as the Name attribute of the corresponding Template element in the WebTemp*.xml file.
There is usually no code in a site definition project, and there should be no assembly. However, by default, Visual Studio always compiles an assembly anyway with every project. The assembly contains no classes if there is no code in the project, but Visual Studio, again by default, deploys it with the solution package. This means that a pointless assembly is added to the global assembly cache. So unless you add elements to your project that are compiled into an assembly, you should disable this default Visual Studio behavior. Otherwise, your solution will deploy a pointless assembly that may confuse farm administrators or anyone who is debugging a SharePoint deployment. Select the project name in Solution Explorer. A Properties window opens. Set the Include Assembly in Package property to false.

To configure a WebTemp*.xml file

Open the WebTemp*.xml file in Solution Explorer. In the ongoing example, this is the WebTemp_RESEARCH.xml file.

Tip

It can be useful to have the built-in WebTemp.xml file open as a model while you perform this procedure. It is located at %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\lcid\XML, where lcid is the numeric ID of a language/culture, such as 1033 for English. The file you are creating will be merged with the built-in file. Do not change the built-in file. The name of your custom file must match the pattern WebTemp*.xml.
Change the ID attribute of the Template element to a value of 10000 or more. This ensures that your ID will not conflict with future site definitions produced by Microsoft. If there are other custom site definitions on your target farm, make sure that each one has a unique ID.
There is a default Configuration element in the Template element. If your site definition is to have more than one configuration—that is, if it represents a family of related site types—copy the Configuration element so that there is one for every custom site type you need in the family. In the ongoing example, there will be two configurations. For more information about when you should have multiple configurations in a single site definition, see Deciding Between Multiple Definitions or Multiple Configurations.
Leave the ID attribute of the original Configuration element at 0, but renumber the copies you made in order beginning with 1.
Change the Title attribute and the Description attribute for each Configuration element to values appropriate to your custom site configurations. These names and descriptions will appear in the user interface (UI) when users create new websites.
If you have a custom image that you want to appear in the UI as a symbol of your custom site type when users are creating sites from your custom site configurations, change the value of the ImageUrl attributes as needed.
Change the DisplayCategory value of each Configuration element as needed. This value sets the name of the category under which the site configuration appears in the UI when a user is creating a website. In many cases, it is appropriate to use the same string as you used for the Name attribute of the Template element. Another possibility is to use your company name. You can also use either of the built-in strings "Collaboration" or "Meetings". We recommend that you not use "Custom". The "Custom" category, by default, contains web templates rather than site definition configurations, and administrators may prefer to maintain that pattern.
The Hidden attribute should have the value FALSE in all the Configuration elements.

For more information about customizing the WebTemp*.xml file, see Understanding WebTemp*.xml Files and Templates Element (Site).

The following is an example of a custom WebTemp_RESEARCH.xml file. The file uses two Configuration elements to define different site definition configurations, one for a Research Collaboration site and the other for a Research Document Workspace site. Both of the site definitions will appear in a category called "Research & Development" in the UI.

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

Note

In the Microsoft SharePoint Foundation object model, a site definition configuration and its parent site definition are represented by a Microsoft.SharePoint.SPWebTemplate object. The Name property of that object concatenates the definition name and the configuration ID with a "#" symbol in between them. So, the two site definition configurations in the previous example would be named "RESEARCH#0" and "RESEARCH#1".

To configure an Onet.xml file

Open the Onet.xml file in Solution Explorer.
Since you chose to create a site definition instead of a web template, you need to do at least one of the following bulleted items, which cannot be done with web templates. (For more information about whether to create a custom site definition or a web template, see Deciding Between Custom Web Templates and Custom Site Definitions.)
- Register a custom email footer that will appear in email messages that are sent from websites that are created from your custom site definition. Do this by adding a ServerEmailFooter element as a child of the Project element. For more information, see ServerEmailFooter Element (Site).
- Configure your custom site type to use a custom file dialog post processor or a custom external security provider. Do this by adding a Components element as a child of the Project element. For more information, see Components Element (Site) and the topics for its child elements.
- Register a custom document type for use in the document libraries of websites that are created from your custom site definition. Do this by following these steps.
  1. Add a DocumentTemplates element as a child of the Project element, and add a DocumentTemplate element as a child of the DocumentTemplates element.
  2. Set the Path attribute of the DocumentTemplate element to the same name as you used for the value of the Name attribute of the Template element in your custom WebTemp*.xml file. To continue the example, you would use "RESEARCH".
  3. Set the Type attribute of the DocumentTemplate element to a value of 10000 or greater to ensure that it does not conflict with future document templates created by Microsoft.
  4. Set the DisplayName attribute and the Description attribute of the DocumentTemplate element to appropriate values.
  5. Add and set the other possible attributes of the DocumentTemplate element as needed. For more information, see How to: Add a Document Template, File Type, and Editing Application to a Site Definition, DocumentTemplate Element (Site), and DocumentTemplates Element (Site).
  6. Add a child DocumentTemplateFiles element to the new DocumentTemplate element. Then add at least one child DocumentTemplateFile element to it, and set its attributes. For more information, see How to: Add a Document Template, File Type, and Editing Application to a Site Definition and DocumentTemplateFile Element (Site).
  Repeat the previous steps for each custom document template that is a part of your custom site definition. Each DocumentTemplate element must be given a different Type attribute value. You will register any built-in document templates for your custom site type in a later step.
Set the following attributes of the Project element to appropriate values. (Only Title and ListDir are required, and the ListDir value can be an empty string.)
1. ListDir
2. Revision
3. SiteLogoUrl
4. SiteLogoDescription
5. Title
Do not use the UIVersion attribute. For more information about these attributes, see Project Element (Site).
If there are any built-in document templates that you want to register for use on your custom sites, you can do so by following these steps.
1. If you did not already do so in an earlier step, add a DocumentTemplates element as a child of the Project element.
2. Copy DocumentTemplate elements as needed from the Onet.xml file for the standard team site, located at %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATES\SiteTemplates\sts\XML, and paste them into your DocumentTemplates element.
Add Configuration elements to the Configurations element so that there are exactly the same number of Configuration elements as there are in the custom WebTemp*.xml file that you created in the previous procedure.
Set the ID attribute of each Configuration element to consecutive numbers beginning with 0. When you are making all additional changes to the Configuration elements, remember that the configuration in the Onet.xml file specifies the details of the configuration in the WebTemp*.xml file that has the same ID number. So in the continuing example, configuration 0 in the Onet.xml file gives the details of the Research Collaboration site configuration in WebTemp_Research.xml, and configuration 1 specifies the details of the Research Document Workspace configuration.
Set the Name attribute of each Configuration element. It is not necessary that the Name attribute value match the Title attribute value of the corresponding configuration in the WebTemp*.xml file. By convention, the former is an acronym of the latter. In the continuing example, you give the names "RC" and "RDW" to configurations 0 and 1, respectively.
In each Configuration element, add child List elements to the Lists element as needed to ensure that each website that is created from one of your configurations is automatically created with the lists you want. (If the Lists element is initially an empty-element tag, <Lists />, split it into start and end tags: <Lists></Lists>.)

For any of the built-in list types, copy the List element from one of the built-in Onet.xml files in descendent folders of %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates. For your custom list types, you must construct a List element. For example, if you define a list type named "My_Custom_List" with a Type attribute of 10001, you can add <List Title="My_Custom_List" Type="10001" Url="Lists/My_Custom_List" FeatureId="guid"/> to make the Lists element. The Url attribute contains the URL for the folder that contains 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. For more information about registering a list in a site definition configuration, see List Element (Site) and Building Block: Lists and Document Libraries.
In each Configuration element, add child Module elements in the Modules element as needed to ensure that each website that is created from one of your configurations is automatically created with the files that it needs. Each module that you reference in a configuration must be defined in the main Modules element that is also in the Onet.xml file but is outside the Configurations element. For more information about registering modules in an Onet.xml file, see Module Element (Site) and Modules.

In each Configuration element, add child Feature elements in the SiteFeatures element and WebFeatures element as needed to ensure that each website that is created from one of your configurations is automatically created with the Features it needs and that they are activated. Use the SiteFeatures element to register features that are scoped to the site collection. Use WebFeatures to register features that are scoped to the website. The Features that you register, including custom Features that you create, must already be deployed to a subfolder of %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES at the time a website is created based on your site definition configuration. For example, you could add a content type, as described in How to: Add a Content Type to a Site, or a column type to your configuration, as described in How to: Add a Column to a Site. To register any of the built-in Features that are included with SharePoint Foundation, you can copy Feature elements from the SiteFeatures element and the WebFeatures element in any of the built-in Onet.xml files in descendent folders of %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates. For more information about registering features, see WebFeatures Element (Site), SiteFeatures Element (Site).

The following is an example of a Configurations element that continues the ongoing example.

<Configurations>
  <Configuration ID="0" Name="RC">
    <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" /> 
      <List FeatureId="00BFEA71-6A49-43FA-B535-D15C05500108" 
        Type="108" Title="$Resources:core,discussions_Title;" 
        Url="$Resources:core,lists_Folder;/$Resources:core,discussions_Folder;" 
        QuickLaunchUrl="$Resources:core,lists_Folder;/$Resources:core,discussions_Folder;/AllItems.aspx" 
        EmailAlias="$Resources:core,discussions_EmailAlias;" /> 
      <List FeatureId="00BFEA71-D1CE-42de-9C63-A44004CE0104" 
        Type="104" Title="$Resources:core,announceList;" 
        Url="$Resources:core,lists_Folder;/$Resources:core,announce_Folder;">
        <Data>
          <Rows>
            <Row>
              <Field Name="Title">$Resources:onetid11;</Field> 
              <Field Name="Body">$Resources:onetid12;</Field> 
              <Field Name="Expires"><ows:TodayISO/></Field> 
            </Row>
          </Rows>
        </Data>
      </List>
      <List FeatureId="00BFEA71-2062-426C-90BF-714C59600103" 
        Type="103" Title="$Resources:core,linksList;" 
        Url="$Resources:core,lists_Folder;/$Resources:core,links_Folder;" /> 
      <List FeatureId="00BFEA71-EC85-4903-972D-EBE475780106" 
        Type="106" Title="$Resources:core,calendarList;" 
        Url="$Resources:core,lists_Folder;/$Resources:core,calendar_Folder;" 
        QuickLaunchUrl="$Resources:core,lists_Folder;/$Resources:core,calendar_Folder;/Calendar.aspx" 
        EmailAlias="$Resources:core,calendar_EmailAlias;" /> 
      <List FeatureId="00BFEA71-A83E-497E-9BA0-7A5C597D0107" 
        Type="107" Title="$Resources:core,taskList;" 
        Url="$Resources:core,lists_Folder;/$Resources:core,tasks_Folder;" 
        QuickLaunchUrl="$Resources:core,lists_Folder;/$Resources:core,tasks_Folder;/AllItems.aspx" /> 
    </Lists>
    <Modules>
      <Module Name="Default" /> 
    </Modules>
    <SiteFeatures>
      <Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" /> 
    </SiteFeatures>
    <WebFeatures>
      <Feature ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" /> 
    </WebFeatures>
  </Configuration>
  <Configuration ID="1" Name="RDW">
    <Lists>
      <List FeatureId="00BFEA71-E717-4E80-AA17-D0C71B360101" 
        Type="101" Title="$Resources:core,shareddocuments_Title;" 
        Url="$Resources:core,shareddocuments_Folder;" /> 
      <List FeatureId="00BFEA71-6A49-43FA-B535-D15C05500108" 
        Type="108" Title="$Resources:core,discussions_Title;" 
        Url="$Resources:core,lists_Folder;/$Resources:core,discussions_Folder;" 
        QuickLaunchUrl="$Resources:core,lists_Folder;/$Resources:core,discussions_Folder;" /> 
      <List FeatureId="00BFEA71-D1CE-42de-9C63-A44004CE0104" 
        Type="104" Title="$Resources:core,announceList;" 
        Url="$Resources:core,lists_Folder;/$Resources:core,announce_Folder;">
        <Data>
          <Rows>
            <Row>
              <Field Name="Title">$Resources:onetid11;</Field> 
              <Field Name="Body">$Resources:onetid12;</Field> 
              <Field Name="Expires"><ows:TodayISO/></Field> 
            </Row>
          </Rows>
        </Data>
      </List>
      <List FeatureId="00BFEA71-2062-426C-90BF-714C59600103" 
        Type="103" Title="$Resources:core,linksList;" 
        Url="$Resources:core,lists_Folder;/$Resources:core,links_Folder;" /> 
      <List FeatureId="00BFEA71-EC85-4903-972D-EBE475780106" 
        Type="106" Title="$Resources:core,calendarList;" 
        Url="$Resources:core,lists_Folder;/$Resources:core,calendar_Folder;" 
        QuickLaunchUrl="$Resources:core,lists_Folder;/$Resources:core,calendar_Folder;/Calendar.aspx" /> 
      <List FeatureId="00BFEA71-A83E-497E-9BA0-7A5C597D0107" 
        Type="107" Title="$Resources:core,taskList;" 
        Url="$Resources:core,lists_Folder;/$Resources:core,tasks_Folder;" /> 
    </Lists>
    <Modules>
      <Module Name="DWS" /> 
    </Modules>
    <SiteFeatures>
      <Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" /> 
    </SiteFeatures>
    <WebFeatures>
      <Feature ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" /> 
    </WebFeatures>
  </Configuration>
</Configurations>

If you want a specific page to open automatically for users who create a site from your site definition configuration, add an ExecuteUrl element to the Configuration element. Typically, this element is used to open a specific custom application page that you have created on which the user can set certain options relevant to your custom site type. For more information about this element, see ExecuteUrl Element (Site). For more information about custom application pages, see Application _layouts Page Type.
Add child NavBar elements in the NavBars element to customize the navigation areas of pages in the websites that are created from your custom site definition. Often the easiest way to do this is to copy NavBar elements from one of the built-in Onet.xml files in descendent folders of %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates. (The NavBars element applies to websites based on any of the configurations in the site definition.) For more information about this markup, see NavBar Element (Site).
Some of the venerable list types that appear on meeting or blog sites were created before the introduction of Features to SharePoint Foundation. These list types are specified in ListTemplate elements in the Onet.xml files for the MPS and BLOG site definitions. If you need any of these list types in your custom site definition, add a ListTemplates element as a child of the Project element, and then copy into it the needed ListTemplate elements from the MPS and BLOG Onet.xml files. (Do not add any custom ListTemplate elements. Instead create custom lists as Features and reference the Feature in a List element child of a Lists element in the Configuration element, as described in an earlier step.) For more information about the list template markup, see ListTemplate Element (Site).
Add child Module elements in the main Modules element directly under the Project element to ensure that each time a website of your custom type is created, it is automatically provisioned with the files and "all user" Web Parts that it needs. Any new module that you add must be referenced in a secondary Modules element that is inside a Configuration element. If a Module is not referenced inside at least one configuration, it is not used. To register any of the built-in modules that are included with SharePoint Foundation, you can copy the corresponding Module element from one of the built-in Onet.xml files in descendent folders of %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\SiteTemplates. For more information about the modules markup, see Modules Element (Site).
If you want pages on websites that are created from your definition to have a specific custom header area, set the AlternateHeader attribute of the Project element. For more information, see Project Element (Site).
If you want pages on websites that are created from your definition to have custom ECMAScript (JavaScript or Microsoft JScript code) functions (such as customizing the Edit menu), set the CustomJSUrl attribute of the Project element. For more information, see Project Element (Site).
If you want to prevent certain kinds of functions in Microsoft SharePoint Designer or other designer applications from working on pages in websites that are created from your definition (such as backup or subsite creation), set the DisableWebDesignFeatures attribute of the Project element. For more information, see Project Element (Site).
You can create custom cascading style sheets (CSS) style definitions to be used by websites that are created from your definition by creating a .css file with a unique name in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS\LCID\STYLES, where LCID is the numeric ID of the language/culture, such as 1033 for English. Copy into this new file the contents of the default .css file specified within .aspx pages of the site definition, and add or update styles in the new .css file. Use the AlternateCSS attribute of the Project element to specify the path to the new .css file. The following is an example.
```
AlternateCSS = 
"/_layouts/[%=System.Threading.Thread.CurrentThread.CurrentUICulture.LCID%]/styles/MyStyles.css">
```

To customize the site’s pages

Double-click the Default.aspx file in Solution Explorer. You can edit it as needed, including pointing it to a custom master page. For more information about customizing site pages, see the Sites and Pages in SharePoint Foundation node.
If websites that are based on your custom site type should have other kinds of pages automatically when the sites are created, add more .aspx pages as needed to the project. To do this, right-click the Site Definition node (not the project name) in Solution Explorer and add a file named custompage.aspx. Adding it in this manner ensures that it is registered in the package manifest and deployed to the correct location when your solution is deployed.
If you include a custom master page as part of your solution, it is important that you add it to the project in the correct way, so that the solution manifest deploys it to the correct location. Right-click the project name in Solution Explorer (not the Site Definition node), point to Add, and then select SharePoint Mapped Folder.
In the Add SharePoint Mapped Folder dialog box, select TEMPLATE\GLOBAL, and then click OK.
In Solution Explorer, right-click the GLOBAL node, and add a new file with the file name extension .master. This creates the new file in the GLOBAL node and registers it in the solution package manifest.
Open the new master page and add markup. For more information about custom master pages, see Master Pages.

To deploy and test the site definition

On the Build menu, select Deploy Solution. This automatically deploys all the files to their appropriate locations, and recycles the web application.

Tip

If your development environment is a multi-server farm instead of a single-server installation, Visual Studio adds the solution to the farm's solution gallery in the Central Administration application, but it does not deploy it. Deploy it in Central Administration.
Add a site to your development farm based on one of the configurations in your custom site definition configurations. In the UI for new site creation, you should see your new site types. In the ongoing example, you should see Research Collaboration site and Research Document Workspace in a category named Research & Development.

Localizing Custom Site Definitions

For information about how to create localized versions of your custom site definition, see How to: Create Localized Versions of Custom Site Definitions.

Share via