Wednesday, 27 July 2011

6.SharePoint 2007 Deployment: List Template Features ant Types of list

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:
  • The feature manifest file (which must be named feature.xml)
  • One or more element manifest 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:
  • Using a feature, just as described in this post.
  • Using the SharePoint interface
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:
  • The title of the feature is My List Template Feature.
  • It will be deployed as a Web Site feature, since it's Scope value is Web.
  • It references a single element manifest file: MyListTemplate.xml.
  • It references an element file, schema.xml, which is the file that contains the list definition and must be located in a subfolder with the name of the list template (MyListTemplate in this case).

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:
  • FeatureId - (optional) The GUID of the feature in which this list template is defined. This is an optional attribute but it's useful to include it since each list template is uniquely identified by is Type inside a specific Feature.
  • BaseType - (required) Specifies the base type, or default schema, for lists created using this template. Like I mentioned in a previous post (WSS Tip #16: List Base Types) this attribute can have one of five possible values:
    • 0 (Generic List)
    • 1 (Document Library)
    • 3 (Discussion Forum)
    • 4 (Survey)
    • 5 (Issues List)
  • Category - (optional) Specifies which category a list created from this template belongs to. It can assume one of the following values:
    • Libraries
    • Communications
    • Tracking
    • Custom Lists
  • Name - (required) Specifies the internal name of the list definition. No spaces or special characters can be used. This name is also used to find the folder that contains the schema.xml file that has the list definition.
  • DisplayName - (required) Specifies the name of the list template that will be shown to the user in the Create screen.
  • Description - (optional) Specifies the description of the list template.
  • DisableAttachments - (optional) Specifies if the list created with this template allows items to have attachments. Default value is FALSE (the items are allowed to have attachments).
  • DisallowContentTypes - (optional) Specifies if the list created with this template can manage content types, allowing items of multiple content types in the same list. Default value is TRUE (content type management not allowed).
  • EnableModeration - (optional) Specifies if the list created with this template will have content approval enabled, which means all items must be approved before they are published. Default value is FALSE (no content approval required).
  • FolderCreation - (optional) Specifies if the list created with this template allows the user to create folders, showing the New Folder option in the New button. Default value depends on the type of list. For custom lists, the default value is FALSE (folder creation is not allowed) but for document libraries, the default value is TRUE (folder creation is allowed).
  • Hidden - (optional) Specifies if the list template is hidden, which means it will not appear as an option on the Create page. Default value is FALSE (list template is not hidden).
  • HiddenList - (optional) Specifies if the list created with this template will be hidden. Do not confuse with the previous option which refers to the list template and not the list created with it. Default value is FALSE (list will not be hidden).
  • OnQuickLaunch - (optional) Specifies if the list created with this template will be displayed in the local navigation menu (quicklaunch). Default value is TRUE (list will be displayed on quicklaunch).
  • SecurityBits - (required) Defines the item-level permissions for the list created with this template. This attribute is a 2-digit string where the first digit controls the read access, and the second digit controls the edit access. For read access, the digit can be:
    • 1: Users can read all items
    • 2: Users can read only their own items
For edit access, the digit can be:
    • 1: Users can edit all items
    • 2: Users can edit only their own items
    • 4: Users cannot edit items
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.
  • Sequence - (optional) Specifies the order of the list template in the Create page. If this attribute is not set, the list template will be placed last in the list of templates (together with other templates that also haven't defined their sequence).
  • Type - (optional) This attribute uniquely identifies this list template within the feature that contains it. SharePoint defines a set of list types which are used in the out-of-the-box list templates:
    • 100: Generic List
    • 101: Document Library
    • 102: Survey
    • 103: Links List
    • 104: Announcements List
    • 105: Contacts List
    • 106: Events List
    • 107: Tasks List
    • 108: Discussion Board
    • 109: Picture Library
    • 110: Data Source Gallery
    • 111: Site Template Gallery
    • 113: Web Part Gallery
    • 114: List Template Gallery
    • 115: XML Form Library
    • 120: Custom Grid for a List
    • 200: Meeting Series List
    • 201: Meeting Agenda List
    • 202: Meeting Attendees List
    • 204: Meeting Decisions List
    • 207: Meeting Objectives List
    • 210: Meeting Text Box
    • 211: Meeting Things to Bring List
    • 212: Meeting Workspace Pages List
    • 300: Portal Sites List
    • 1100: Issue Tracking
    • 2002: Personal Document Library
    • 2003: Private Document Library
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.
  • VersioningEnabled - (optional) Specifies if the lists created with this template support versioning of their items. Default value is FALSE (item version is not enabled).
 Other Attributes
There are some less used attributes that one can use in the <ListTemplate> element, which are listed below:
  • AllowDeletion - (optional) Specifies if the lists created with this template can be deleted. Default value is TRUE (lists can be deleted).
  • AllowEveryoneViewItems (optional)
  • AlwaysIncludeContent - (optional) Specifies if the contents are included by default, when lists created with this template are Saved as Templates. Default value is FALSE (content is not included, by default).
  • CacheSchema (optional)
  • Catalog - (optional) Specifies if the list definition is for a site gallery, list gallery or web part gallery. Default value is FALSE (list is not a gallery).
  • Default - (optional) Specifies if new SharePoint sites will include this list. Default value is FALSE (lists are not included in new sites).
  • DontSaveInTemplate - (optional) Specifies if a list created with this template should be included when the site that contains it is Saved as Template. Default value is FALSE (list is included in custom site template).
  • EditPage - (optional) Specifies the path to a custom application page (/_layouts) to use when editing list properties for list created with this template.
  • Image - (optional) Specifies the path to an image that represents the type of list defined by this template.
  • NewPage - (optional) Specifies the path to a custom application page (/_layouts) to use when creating a new list based on this template.
  • NoCrawl - (optional) Specifies if this list should be crawled and displayed in search results. Default value is FALSE (list is crawled).
  • RootWebOnly - (optional, deprecated) Specifies that the lists created with this template can only exist in the root web site of a site collection. Default value is FALSE (lists can exist on any web site).
  • SetupPath - (optional) Specifies the path to a folder in the Windows SharePoint Services setup directory (C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE) that contains a file to include in the template.
  • SyncType (optional)
  • Unique - (optional) Specifies that this template can only be used to create lists during site creation, and not through the Create page or the SharePoint object model. Setting this attribute to TRUE has the effect of hiding the list template from the Create page and the list created with it from the web site lists. Default value is FALSE (lists can be created in the interface and through the object model).
  • UseRootFolderForNavigation (optional)

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:
  • Default - Contains the default form definitions used in lists created through the list definition.
  • ContentTypes - Contains references to content types to associate with list created through the list definition.
  • DefaultDescription - Sets the default description that appears in the title area of list views.
  • DocumentLibraryTemplate - Specifies which file servers as the template document for items of a document library.
  • Fields - Contains the field definitions for that belong to the list template.
  • Forms - Contains the collection of forms used for lists create through the list definition.
  • Toolbar - Contains the configuration for the toolbar used in the list views in list created through the list definition.
  • Views - Contains the definition of the views used in a list created from this template.
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:
  • You don't need to specify fields that were already defined in the base list.
  • You must specify all other fields, even those that belong to a content type already associated with the template (via ContentTypes 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.
Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)