How to: Create a Custom Field Class

  • Article

Applies to: SharePoint Foundation 2010

To create a custom field type class, you must derive a class from either the SPField class or one of the classes listed in the table below, which all derive from the SPField class.

Note

There are other field type classes (classes whose names follow the pattern SPField*), but these are processed in special ways by Microsoft SharePoint Foundation and deriving new classes from them is not supported.

We recommend that you use the following naming convention when you create custom field classes that are derived, directly or indirectly, from the SPField class:

field_type_nameField

Examples of properly named classes are TargetDateField and RegularExpressionField. (The SPField-derived classes that ship with SharePoint Foundation were created before this naming convention was determined and they follow the pattern SPFieldfield_type_name such as the SPFieldDateTime.)

Custom Field Classes Can Be Derived From the Following SPField Class Members

Custom field type classes that do not inherit directly from the SPField class must be derived from one of the following classes.

Class

Description

SPFieldBoolean

Represents a Boolean field type.

SPFieldChoice

Represents a choice field type.

SPFieldCurrency

Represents a currency field type.

SPFieldDateTime

Represents a date-time field type.

SPFieldLookup

Represents a lookup field. The field value for an SPFieldLookup object is contained in an SPFieldLookupValue object.

SPFieldMultiChoice

Represents a multichoice field type. The field value for an SPFieldMultiChoice object is contained in an SPFieldMultiChoiceValue object.

SPFieldMultiColumn

Represents a multicolumn field type. The field value for an SPFieldMultiColumn object is contained in an SPFieldMultiColumnValue object.

SPFieldMultiLineText

Represents a multiline text field type.

SPFieldNumber

Represents a number field type.

SPFieldRatingScale

Represents a ratings field type. The field value for an SPFieldRatingScale object is contained in an SPFieldRatingScaleValue object.

SPFieldText

Represents a single line text field type.

SPFieldUrl

Represents a URL field type. The field value for an SPFieldUrl object is contained in an SPFieldUrlValue object.

SPFieldUser

Represents a SharePoint Foundation user.

Note

For more information about creating custom field value classes, see How to: Create a Custom Field Value Class.

Specifying Custom Field Behavior

After you choose the field class from which you want to derive your custom field type, you can select the members of that class that you want to override. Because most of the properties and behaviors that make a field type unique are contained in its class, there is a rich set of override semantics available simply by choosing which SPField-derived class your new implementation will override.

For example, the SPField class contains the following members whose implementation can be overridden, if necessary, when developing custom field types.

Note

For most of the members listed in this section, the default implementation of the SPField class is not intended to do useful work; for example, GetFieldValue simply returns what was passed to it, and GetValidatedString simply calls the ToString method of the value class (which does not contain any validation logic). For this reason, if your custom field type class is derived directly from SPField, then you must provide overrides for any of these members that you need to use for its intended purpose.

SPField Class Members that Frequently Need to Be Overridden

SPField Class Members

Description

FieldRenderingControl

Returns a control that can be used to render the field in the Display, Edit, and New forms, and any pages that use field controls. An object instantiating a rendering control holds, in its Field property, a reference back to the field object that it renders. As these reciprocal references suggest, the two objects are partners. The SPField-derived object handles interaction with the content database, while the BaseFieldControl-derived rendering control handles interaction with users and the rendering of the field in the user interface (UI). Note, however, that it is not necessary to render a custom field with a rendering control: it can also be rendered with a RenderPattern defined in a field definition, in which case the FieldRenderingControl property can be null. The most common pattern is to use a rendering control to render the field in the New and Edit modes and use a render pattern to render it in Display mode.

When you do use a rendering control, then your custom field class must override the FieldRenderingControl property get accessor with the following standard pattern of code:

public override BaseFieldControl FieldRenderingControl
{
    [SharePointPermission(SecurityAction.LinkDemand, ObjectModel = true)]
    get 
    {
        BaseFieldControl fieldControl = new field_type_nameFieldControl();
        fieldControl.FieldName = this.InternalName;
        return fieldControl;
    }
}
Public Overrides ReadOnly Property FieldRenderingControl() As BaseFieldControl
    <SharePointPermission(SecurityAction.LinkDemand, ObjectModel := True)> _
    Get
        Dim fieldControl As BaseFieldControl = New field_type_nameFieldControl()
        fieldControl.FieldName = Me.InternalName
        Return fieldControl
    End Get
End Property

The permission attribute ensures that only code with permission to use the SharePoint Foundation object model can read the property. The line assigning the field object's internal name to the FieldName property also sets the Field property to the field object. This ensures that your field_type_nameFieldControl knows what object it is rendering.

FieldRenderingMobileControl

Returns a control can be used to render the field in the Display, Edit, and New forms in mobile applications.

GetFieldValueForEdit

Returns the field value to be rendered in Edit mode. This method is used for the Edit and New forms.

GetValidatedString

When overridden in a derived class, returns the validated field value. Override this method for custom validation and data serialization logic. (The base method provides no validation logic and many of the SharePoint Foundation classes that derive from it do not either.) This method may in turn use the ToString method of the field value object to convert the field value object into a string. The typical override should:

  • Throw an SPFieldValidationException when the value the user has given to the field is not valid, or if the value is null and the field is required. This exception is caught by the by SharePoint Foundation if the user attempts to save an invalid value. For example, the New form remains open and the Message property of the exception is used to place an error message beside the invalid field.

  • Call the base GetValidatedString if and only if the value passes your custom validation.

See Custom Field Data Validation for more information and a sample of an overridden GetValidatedString

OnAdded

Override to specify custom field type logic after a field is added to a list.

OnUpdated

Override to specify custom field type logic after a field is updated.

OnDeleting

Override to specify custom field type logic before a field is deleted from a list.

SPField Class Members that Are Frequently Overridden When a Complex Custom Data Type Is Used

There are also several members of the SPField class that you are likely to override when the field type requires a complex custom data type that is different from that of the parent field type. You define such custom data types with custom field value classes. For more information, see How to: Create a Custom Field Value Class. (You may also need to override these members in other situations, even when you are not creating custom data types.)

SPField Class Members

Description

DefaultValue

Returns, as a string, a default value that can be used for the field when a particular list item has no value in the field.

DefaultValueTyped

Returns a default value that can be used for the field when a particular list item has no value in the field.

FieldValueType

Returns the field value type.

GetFieldValue

Returns the field value as an object.

GetFieldValueAsText

Returns the field data value as a string.

GetFieldValueAsHtml

Returns the field data value as a string, formatted as HTML. This HTML-formatted field value is most often used to render the field value directly on a page. For example, it is used on the version history page of a list item. However, this HTML-formatted field value is not used on the Display form. Field rendering for the Display form is typically rendered from the Collaborative Application Markup Language (CAML) DisplayPattern element in the field type's fldtype*.xml file.

GetValidatedString

See the Note in the section Specifying Custom Field Behavior.

PreviewValueTyped

Returns a preview value of field data, for a design time view of the field control in Display and Edit mode.

See Also

Tasks

Walkthrough: Creating a Custom Field Type

Concepts

How to: Create a Custom Field Type

Custom Field Types

Custom Field Data Validation

How to: Create a Custom Field Value Class