Blog IT

SharePoint 2007 Deployment: List Template Features

André Vala

Summary

This post is about developing features to create list templates in a SharePoint site. Check the first post SharePoint 2007 Deployment: Overview for an introduction and the series index.

Package Structure

As I mentioned previously in the post SharePoint 2007 Deployment: Creating and Using Features, to build a feature you need to create the following files:

Additionally, a list template must include a third file, called schema.xml, that contains the list definition. This file must be placed in a subfolder with the same name of the list template that is being defined.

You can then place these three files inside a Solution following the instructions in the post SharePoint 2007 Deployment: Creating Solutions, to provide an easy way to deploy the feature (or upgrade it).

List Templates

A list template is a reusable definition of a SharePoint list that is used to create lists. You can create list templates in one of two ways:

To create a list template using the SharePoint interface, you only need to access the list's settings screen, and click on Save As Template. This will save the list template as a .stp file in the List Templates Gallery. This gallery stores only the custom list templates created through the SharePoint interface.

One additional note about list templates stored as .stp files is that they don't store a complete list definition (like the feature does) but rather a set of customizations performed on an existing list definition. This means that, although you can copy the file and deployed it to a different SharePoint farm, you must ensure that the original list definition that was customized to create the template also exists in the destination farm.

Allowed Scopes

The scopes to which a feature can be deployed, are dictated by the types of elements included in it. A feature with list template elements can only be deployed to Site Collection or Web Site scopes.

Feature Manifest

I will only present a simple feature manifest, since the additional options were presented in the above mentioned post.

<?xml version="1.0" encoding="utf-8" ?>
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
         Id="5DFD12AF-D0AA-4c63-8FB8-C49DB1191083"
         Title="My List Template Feature"
         Description="Adds my My List Template."
         Scope="Web"
         Version="1.0.0.0">
    <ElementManifests>
        <ElementManifest Location="MyListTemplate.xml" />
        <ElementFile Location="MyListTemplate\schema.xml" />
    </ElementManifests>
</Feature>

Notes about this feature manifest:

Element Manifest

The element manifest file can have any name you wish (in this example it's called MyListTemplate.xml), but it's root element must be <Elements>. Inside this root element, you can place any number of feature element descriptions. In this example I will present the use of the <ListTemplate> element which is used to deploy List Templates.

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <ListTemplate
        FeatureId="5DFD12AF-D0AA-4c63-8FB8-C49DB1191083"
        BaseType="0"
        Category="Custom Lists"
        Name="MyListTemplate"
        DisplayName="My List Template"
        Description="My Custom List Template."
        DisableAttachments="TRUE"
        DisallowContentTypes="TRUE"
        EnableModeration="FALSE"
        FolderCreation="FALSE"
        Hidden="FALSE"
        HiddenList="FALSE"
        OnQuickLaunch="TRUE"
        SecurityBits="11"        
        Sequence="500"
        Type="100"
        VersioningEnabled="FALSE">
    </ListTemplate>
</Elements>

This example creates a list template named MyListTemplate which is based on the Custom List template. Here is a short explanation of the attributes of the <ListTemplate> element:

For edit access, the digit can be:

A notes about this attribute: a user with Manage Lists permission can always read and edit all items, regardless of the value of this attribute.

This attribute might be important if you want to define event handlers that are attached to a specific type of list. I will talk about that scenario on one of the next posts in this series.

 Other Attributes

There are some less used attributes that one can use in the <ListTemplate> element, which are listed below:

List Definition File (schema.xml)

The list definition file (named schema.xml) is included in the feature using an ElementFile tag. Note that this file must be located in a subfolder with the same name as the list template being defined (in this example, MyListTemplate).

This file can be quite large and overwhelmingly complex, since it contains CAML and HTML embedded in the XML. The best strategy to built it is to copy an existing one and making only the necessary changes (which are only a few lines).

For this example, I will use the list definition file from the Custom List template which can be found in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\CustomList\CustList\schema.xml.

List Element

The first thing you must change is the attribute values in the List element. The original file has the following attributes for the main element:

<List xmlns:ows="Microsoft SharePoint" 
      Title="Basic List" 
      FolderCreation="FALSE" 
      Direction="$Resources:Direction;" 
      Url="Lists/Basic List" 
      BaseType="0">

For this example, I will change the above snippet to the one shown below:

<List xmlns:ows="Microsoft SharePoint"
      Title="My List"
      FolderCreation="FALSE"
      Direction="$Resources:Direction;"
      Url="Lists/MyList"
      BaseType="0">

Most of these attributes can be overridden when creating a list based on this template, but it's always a good practice to set the correct display name (Title attribute), default URL (Url attribute) and list base type (BaseType attribute). There are several optional attributes that you can specify to set additional configuration for the list template. For the sake of simplicity, I will not list them in this post.

The List element can have two child elements: Data and Metadata.

Data Element

The Data element is optional and is used to specify a set of rows that will be included in every list created with this template. Below is a sample snippet of this element.

<Data>
    <Rows>
        <Row>
            <Field Name="Title">My Item Title</Field>
            <Field Name="Body">Welcome to my custom list.</Field>
            <Field Name="Country">Portugal</Field>
        </Row>
    </Rows>
</Data>

In the above sample, I'm assuming that the list contains (at least) three fields (named Title, Body and Country, respectively) and I'm setting their values for a single row.

Metada Element

The Metadata element holds the definition of the list. It can have several child elements:

Most lists will only need a subset of these, and I will show only three of them, which are the ones that must be changed in this example: ContentTypes, Fields and Views.

ContentTypes Element

The ContentTypes element specifies which content types will be associated with the lists created with this template. Each content type is referred through a ContentTypeRef child element as shown below.

<ContentTypes>
    <ContentTypeRef ID="0x0100C5647A362F236548B218C15302286758">
        <Folder TargetName="MyContentType" />
    </ContentTypeRef>
    <ContentTypeRef ID="0x0120" />
</ContentTypes>

The ContentTypeRef element has a required attribute ID, that specifies the ID of the referred content type. The Folder child element is optional, and is used to specify the relative folder path (inside the list's root folder) for the content type's resource folder. Most of the times, it's value is the name of the content type.

Fields Element

The Fields element is used to list the fields that should be included in the list. Two important notes about this element:

<Fields>
    <Field 
        Type="Text"
        DisplayName="Body"
        ID="{b402db15-ee44-4ec4-89e3-23e10a8fc64c}"
        SourceId="0x0100C5647A362F236548B218C15302286758" 
        StaticName="Body"
        Name="Body" />
    <Field
        Type="Text"
        DisplayName="Country"
        Required="FALSE"
        MaxLength="255"
        Group="My Fields"
        ID="{f402db10-eb44-4ba4-20f3-73e13e8fe42c}"
        SourceId="0x0100C5647A362F236548B218C15302286758"
        StaticName="Country"
        Name="Country" />
</Fields>

In the above sample, I defined two fields (Body and Country). I didn't define the Title field because it is already defined in the base list. The attributes of the Field element are the same that were explained in the post SharePoint 2007 Deployment: Site Column Features.

Views Element

The Views element is used to specify the views that will be used in the lists created through this list template. It has a View child element for each view to be created, which is a rather complex element, with several possible attributes and child elements. Most of the times, you'll only need to edit the ViewFields and the Query child elements of the View element, as shown in the sample below.

<Views>
    <View BaseViewID="0" 
          Type="HTML" 
          WebPartZoneID="Main" 
          DisplayName="My View" 
          DefaultView="TRUE" 
          SetupPath="pages\viewpage.aspx" 
          ImageUrl="/_layouts/images/generic.png" 
          Url="AllItems.aspx">
        (...)
        <ViewFields>
            <FieldRef Name="Attachments" />
            <FieldRef Name="LinkTitle" />
            <FieldRef Name="Body" />
            <FieldRef Name="Country" />
        </ViewFields>
        <Query>
            <OrderBy>
                <FieldRef Name="Title">
                </FieldRef>
            </OrderBy>
        </Query>
    </View>
</Views>

In the above sample, the defined view is called My View and contains four fields: Attachments, LinkTitle, Body and Country, and the items are ordered using the Title field.