Using Custom Field Types and Field Controls

  • Article
Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Fields in SharePoint are metadata elements that can be added as columns to a SharePoint list. There are 32 different of field types in Windows SharePoint Services 3.0. For example, there is the SPFIeldAllDayEvent class. This is a Boolean field that represents an all-day activity without a start or an end time. Custom field types are necessary when the application data does not conform to one of these default types. You may also need custom field types in the following situations:

  • The default validation rules are not applicable.
  • The field requires custom logic.
  • The field requires custom rendering.

For more information about standard SharePoint field types, see SPFieldClass (Microsoft.SharePoint) on MSDN.

The Difficulty Level Field

The Training Course Management system uses one custom field type named CourseDifficultyLevelField. It corresponds to the Difficulty Level column in the list of training courses that is displayed on the user's dashboard. The CourseDifficultyLevelField is set to a numerical value between 0 and 5. This is represented on the Web page by a series of green or gray squares. While users are in the Edit and New modes for the list, they can set the Course Difficulty Level field by clicking on the squares.

Figure 1 illustrates the training course list with the Difficulty Level column set to different values for two courses.

Ff648469.difficulty_control(en-us,PandP.10).png

Figure 1
Course difficulty field control

The Course Difficulty Level Field Class

Custom field types require two components. One is the custom field class. A custom field class must derive either from the SPField class or a subclass of SPField. For example, the Training Management application's CourseDifficultyLevelField class derives from the SPFieldNumber class. It overrides the FieldRenderingControl property and the GetValidatedString method. The FieldRenderingControl property instantiates the custom field control. The following code demonstrates how to override the FieldRenderingControl property.

public override BaseFieldControl FieldRenderingControl
{
    [SharePointPermission(SecurityAction.LinkDemand, ObjectModel = true)]
    get
    {
        BaseFieldControl fieldControl = new CourseDifficultyLevelFieldControl();
        fieldControl.FieldName = this.InternalName;

        return fieldControl;
    }
}

The GetValidatedString method validates that the value of the CourseDifficultyLevelField is a number between 0 and 5. This is demonstrated in the following code.

[SharePointPermission(SecurityAction.LinkDemand, ObjectModel = true)]
public override string GetValidatedString(object value)
{
    string difficultyLevel = value.ToString();
    short difficultyLevelValue = Int16.Parse(difficultyLevel);
    if (difficultyLevelValue < 0 || difficultyLevelValue > 5)
    {
        throw new SPFieldValidationException("Invalid difficulty level. Difficulty level must be between 0 and 5.");
    }

    return difficultyLevel;
}

For more information about the SPField class, see SPField Class (Microsoft.SharePoint) on MSDN.

The CourseDifficultyLevelField Definition

The field type definition is an XML file (fldtypes_CourseDifficultyLevel.xml) that describes the assembly that contains the custom field class and any custom rendering instructions. All custom field type definition files start with the text fldtypes_ and are deployed to the Templates/xml folder in the SharePoint 12 hive. The CourseDifficultyLevelField definition contains a custom RenderPattern element for custom rendering. This element displays a series of squares that correspond to the difficulty level value specified in the custom field. For more information about patterns of custom field rendering, see Patterns of Custom Field Rendering on MSDN. The following code is a partial example of how to use the RenderPattern element.

<RenderPattern Name="DisplayPattern">
  <HTML>
    <![CDATA[<div align='right'>]]>
  </HTML>
  <Switch>
    <Expr>
      <Column />
    </Expr>
    <Case Value="1">
      <HTML>
        <![CDATA[<img src='/_layouts/images/trainingmanagement/level1.gif' />]]>
        <![CDATA[<img src='/_layouts/images/trainingmanagement/level0.gif' />]]>
        <![CDATA[<img src='/_layouts/images/trainingmanagement/level0.gif' />]]>
        <![CDATA[<img src='/_layouts/images/trainingmanagement/level0.gif' />]]>
        <![CDATA[<img src='/_layouts/images/trainingmanagement/level0.gif' />]]>
      </HTML>
    </Case>
...
  </Switch>
  <HTML>
    <![CDATA[</div>]]>
  </HTML>
</RenderPattern>

The Course Difficulty Level Field Control

A custom field rendering control can render custom field types in the New and Edit modes.

Figure 2 illustrates the field rendering control as it appears in Edit mode.

Ff648469.new_course_desc_difficulty(en-us,PandP.10).png

Figure 2
Field rendering control in Edit mode

A custom field rendering control must derive from the BaseFieldControl class or a subclass of the BaseFieldControl class. The CourseDifficultyLevelFieldControl class derives from the BaseFieldControl class and overrides the CreateChildControls, UpdateFieldValueInItem, and RenderFieldForDisplay methods. The CreateChildControls method adds a series of ImageButton controls that display images of green or gray squares. Users can click on the squares to specify a difficulty level for a course. The UpdateFieldValueInItem method fires during a post back. This is typically when the value of the data held in the field is updated. The RenderFieldForDisplay method is only used to render the control in the Display mode.

For more information about the BaseFieldControl class, see BaseFieldControl Class (Microsoft.SharePoint.WebControls) on MSDN. For more information about custom field types and custom field rendering controls, see Custom Field Types on MSDN.

Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Footer image

To provide feedback, get assistance, or download additional, please visit the SharePoint Guidance Community Web site.

Copyright © 2008 by Microsoft Corporation. All rights reserved.