7. SharePoint 2007 Deployment: List Instance Features

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

The feature manifest file contains the generic information about the feature package, and the element manifest files contain the information about each specific type of element that makes up the feature. Since I already explained all the possible contents of the feature manifest file in the above mentioned post, I will focus this one the element manifest that allows the creation of list instances in a SharePoint site.
You can then place these two 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 Instances

A list instance is a list created by using a list template (as defined in my previous post SharePoint 2007 Deployment: List Template Features). When creating a list this way, you can override some of the list properties set in the template, and you can include data rows that will also be created as list items in the list.

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 instance elements can only be deployed to Web Site scopes, since it creates a list in a specific web site.

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 Instance Feature"
         Description="Adds a List to the Web Site."
         Scope="Web"
         Version="1.0.0.0">
    <ElementManifests>
        <ElementManifest Location="ListInstance.xml"/>
    </ElementManifests>
</Feature>

Notes about this feature manifest:

• The title of the feature is My List Instance Feature.
• It will be deployed as a Web Site feature, since it's Scope value is Web.
• It references a single element manifest file: ListInstance.xml.

Element Manifest

The element manifest file can have any name you wish (in this example it's called ListInstance.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 <ListInstance> element which is used to deploy Lists to SharePoint web sites.

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <ListInstance
           FeatureId="5DFD12AF-D0AA-4c63-8FB8-C49DB1191083"
           Title="My List"
           Description="List created with a feature."
           Id="1036"
           TemplateType="100"
           Url="Lists/MyList">
    </ListInstance>           
</Elements>

This examples creates a list named My List with the URL Lists/MyList. Here is a short explanation of the attributes of the <ListInstance> element:

• FeatureId - (optional) The GUID of the feature where the list template was defined. If this attribute is not present, SharePoint will assume that the list template was defined in this feature.
• Title - (required) Title of the list.
• Description - (optional) Description for the list.
• Id - (required) Unique integer identifier for this list instance. It must be unique across this feature.
• TemplateType - (required) The integer identifier of the list template. This attribute must map to the Type attribute of the list template definition (in the ListTemplate element).
• Url - (required) Site-relative URL where the list will created.

Other Attributes

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

• OnQuickLaunch - (optional) True if you want the list to be displayed in the QuickLaunch menu (local navigation).
• QuickLaunchUrl - (optional) Specifies the URL of the view page to open for the list through QuickLaunch navigation.
• RootWebOnly - (optional) True if the list is only created in the root web site of the site collection.

Including Data

When using this type of feature element, you can specify a set of items that will be included when the list is created. For that you must insert a <Data> element inside the <ListInstance> element, as shown below.

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <ListInstance
           FeatureId="5DFD12AF-D0AA-4c63-8FB8-C49DB1191083"
           Title="My List"
           Description="List created with a feature."
           Id="1036"
           TemplateType="100"
           Url="Lists/MyList">
        <Data>
            <Rows>
                <Row>
                    <Field Name="Title">Item 1</Field>
                    <Field Name="CustomField">Custom Data</Field>
                </Row>
                <Row>
                    <Field Name="Title">Item 2</Field>
                    <Field Name="CustomField">New Custom Data</Field>
                </Row>
            </Rows>
        </Data>
    </ListInstance>           
</Elements>

This example shows how to add two list items to the list instance. For each of the list items, two fields are updated: Title and CustomField.