Wednesday, 27 July 2011

4.SharePoint 2007 Deployment: Site Column Features

Summary

This post is about developing features to create site columns 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
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 site columns 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).

Site Columns

Just to keep everything clear, I'm going to give a brief explanation about the concept of site columns. Site columns are reusable column definitions, which means that they are exactly the same as a regular list column but do not belong to any single list. A site column exists in the context of a web site (organized in groups, in the site column gallery) and can be used in lists and content types in that web site or its child web sites.
One can create new site columns or edit the existing ones following the steps below:
  • Site Actions (press the button)
  • Site Settings
  • Site Columns (in the Galleries option group)

Allowed Scopes

The scopes to which a feature can be deployed, are dictated by the types of elements included in it. A feature with site column 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 Site Columns Feature"
         Description="Adds My Site Columns."
         Scope="Site"
         Version="1.0.0.0">
    <ElementManifests>
        <ElementManifest Location="SiteColumns.xml"/>
    </ElementManifests>
</Feature>
Notes about this feature manifest:
  • The title of the feature is My Site Columns Feature.
  • It will be deployed as a Site Collection feature, since it's Scope value is Site.
  • It references a single element manifest file: SiteColumns.xml.

Element Manifest

The element manifest file can have any name you wish (in this example it's called SiteColumns.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 <Field> element which is used to deploy Site Columns.
Since the <Field> element can have a very large number of attributes I will only show a subset with the most common ones.
<Elements xmlns = "http://schemas.microsoft.com/sharepoint/">
    <Field 
    ID="{b402db15-ee44-4ec4-89e3-23e10a8fc64c}"
    Type="Text"
    Title="TextField"
    Name="TextField"
    StaticName="TextField"
    DisplayName="TextField"
    Description="My Text Field."
    Required="FALSE" 
    MaxLength="255"
    Hidden="FALSE"
    ReadOnly="FALSE"
    ShowInDisplayForm="TRUE"
    ShowInEditForm="TRUE"
    ShowInListSettings="TRUE"
    ShowInNewForm="TRUE"
    ShowInVersionHistory="TRUE"
    ShowInViewForms="TRUE"
    Group="Custom Columns">        
    </Field>
</Elements>
This example creates a site column, named TextField, of type Single Line of Text. See below a short explanation of the used attributes:
  • ID - This is the unique identifier of this site column. It will be used to reference this site column when including it in a content type or attaching it to a list.
  • Type - This attribute specifies the type of data stored in the site column. It can have one of the following values:
    • AllDayEvent: All day event flag, used in calendar lists.
    • Attachments: Stores the URL of attachments.
    • Boolean: Specifies a Yes/No field.
    • Calculated: Specifies that this field's value is calculated based on other columns' values.
    • Choice: Specifies a Choice (menu to choose from) field with a pre-defined set of values.
    • Computed: Specifies a field whose value depends on another field's value.
    • ContentTypeId: Contains a Content Type ID value.
    • Counter: Used to hold the internal ID's for each item.
    • Currency: Specifies a field that stores a currency value (its format depends on the locale).
    • DateTime: Specifies a Date and Time field.
    • File: Contains a file (used in document libraries).
    • GridChoice: Specifies a rating scale (used in surveys).
    • Guid: Specifies a field that holds a unique identifier.
    • Integer: Specifies a number field that holds integer values only.
    • Lookup: Specifies a Lookup field, which is similar to the Choice field except the available choices are retrieved from another list.
    • LookupMulti: Specifies a Lookup field that allows multiple selections.
    • ModStat: Specifies a field that contains content approval status.
    • MultiChoice: Specifies a Choice field that allows multiple selections.
    • Note: Specifies a Multiple Lines of Text field.
    • Number: Specifies a Number field, that can hold floating-point values.
    • PageSeparator: Specifies a page separator (used in surveys).
    • Recurrence: Used to mark an event as recurrent in a calendar list.
    • Text: Specifies a Single Line of Text field.
    • ThreadIndex: Specifies the correlation ID in a threaded conversation (used in discussion lists).
    • Threading: Used in the creation and display of threaded discussion-like views.
    • URL: Specifies a Hyperlink or Picture field.
    • User: Specifies a Person or Group field.
    • UserMulti: Specifies a Person or Group field that allows multiple selections.
    • WorkflowEventType: Contains the type of workflow history event (used in workflow history list).
    • WorkflowStatus: Contains the workflow status (used in lists that have associated workflows).
  • Title - This is the name of the field shown in the interface, and it can be changed by the user.
  • Name - (optional) This is the internal name of the field, and is guaranteed to never change during the lifetime of the field. It is automatically generated from the display name of the field, and the spaces and special characters are escaped.
  • StaticName - (optional) This is automatically set to the same value as the internal name, but can be changed programmatically (not through the interface though).
  • DisplayName - (optional) This is the same as the Title property.
  • Description - (optional) This is the description for the field. SharePoint displays this text in new/edit forms below the data entry control.
  • Required - (optional) Specifies if the field is mandatory. Default value is FALSE.
  • MaxLength - (optional) Specifies the maximum number of characters allowed for this field.
  • Hidden - (optional) Specifies that the field should be completely hidden from the interface. If TRUE, this field will not be shown on views or forms. Default value is FALSE.
  • ReadOnly - (optional) Specifies that the field should be read-only, which means it appears in views but will be hidden from new/edit forms. Default value is FALSE.
  • ShowInDisplayForm - (optional) Specifies that the field should be shown in display forms. Default value is TRUE.
  • ShowInEditForm - (optional) Specifies that the field should be shown in edit forms. Default value is TRUE.
  • ShowInListSettings - (optional) Specifies that the field should be shown in the list settings screen. Default value is TRUE.
  • ShowInNewForm - (optional) Specifies that the field should be shown in new forms. Default value is TRUE.
  • ShowInVersionHistory - (optional) Specifies that the field should be shown in the version history of an item. Default value is TRUE.
  • ShowInViewForms - (optional) Specifies that the field should be shown in view forms. Default value is TRUE.
  • Group - (optional) Specifies the name of the group that contains the site column.

Additional Samples

Because there are so many types of fields, I will include some additional samples and notes to show some of the other attributes used to specify a field.

The Choice Field

<Field 
    ID="{538c71e4-8650-4ce7-b021-920effa66346}"
    Type="Choice"
    Name="Publishing_x0020_Status"
    StaticName="Publishing_x0020_Status"
    DisplayName="Publishing Status"
    Required="FALSE"  
    Format="Dropdown"
    FillInChoice="FALSE"
    Group="Custom Columns">
        <Default>Not Published</Default>
        <CHOICES>
            <CHOICE>Not Published</CHOICE>
            <CHOICE>Pending</CHOICE>
            <CHOICE>Published</CHOICE>
            <CHOICE>Error</CHOICE>
        </CHOICES>
    </Field>
The Choice field has a few specific issues that are worth mentioning:
  • The Type attribute must be set to Choice.
  • The Format attribute is used for several purposes, but in choice fields, it defines the type of control used to select the option. Possible values are Dropdown (default) and RadioButtons.
  • The attribute FillInChoice specifies if the user can add choices to the column.
  • The <Default> child element specifies which of the choices is pre-selected in the control as default.
  • The <CHOICES> child element contains all the possible value options, each in its own <CHOICE> child element. Beware that you must use capital letters for these elements, otherwise the field will not contain any of the choices.

The Multiple Lines of Text Field

<Field 
    ID="{5b79f1f1-b14f-489b-9bd5-a76897db93b9}"
    Type="Note"
    Name="My_x0020_Comments"
    StaticName="My_x0020_Comments"
    DisplayName="My Comments"
    Required="FALSE"
    UnlimitedLengthInDocumentLibrary="TRUE"
    NumLines="10"
    RichText="FALSE"
    Sortable="FALSE"
    Group="Custom Columns">
  </Field>
The Multiple Lines of Text field also has some specific attributes:
  • The Type attribute must be set to Note.
  • The UnlimitedLengthInDocumentLibrary attribute specifies that there will be no limitation to the contents of this field when used in document libraries.
  • The NumLines attribute defines the number of lines shown in the data entry control (textarea HTML control).
  • The RichText attribute specifies if the field accepts formatted text or only plain text.
  • The Sortable attribute specifies if the field can be used to sort a list. Note fields always have the Sortable attribute set to FALSE.

The Number Field

<Field
    ID="{5b7934e1-b14f-489b-9bd5-a76837da92b4}"
    Type="Number"
    Name="My_x0020_Number"
    StaticName="My_x0020_Number"
    DisplayName="My Number"
    Required="FALSE"
    Min="0"
    Max="100"
    Decimals="0"
    Percentage="FALSE"
    Group="Custom Columns">
  </Field>
The Number field has the following additional attributes:
  • The Type attribute must be set to Number.
  • The Min and Max attributes specify the minimum and maximum values that this field can contain. Both attributes are optional.
  • The Decimals attribute specifies the number of decimal places of the number stored in the field.
  • The Percentage attribute specifies if the number is to be shown as a percentage. Default value is FALSE.

The Lookup Field

The Lookup field is the only field type that cannot be created with a simple feature such as this one. The cause for this is the fact that this type of field references a column of a list using the list's ID, and a list's ID is dynamically generated when a list is created.
This means that there is no way one can predict what will be the ID of the list referenced by the Lookup field when the feature is developed. This value is only known when the feature is activated in a specific web site.
For that reason, the steps to create a feature for this type of site column will be the subject of one of the next posts of the series.
Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)