Custom Field Types
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.
As you store your business information in Windows SharePoint Services 3.0, you may encounter instances where your important business data does not conform to the field types included in Windows SharePoint Services, or situations where you want to further customize those general field types. Windows SharePoint Services enables you to create custom field types. These custom fields can include custom data validation and custom field rendering. You can also customize the way that variable properties of your custom field types are processed and rendered when users set property variables and create new columns that are based on your custom field type.
Note
In Windows SharePoint Services 3.0, columns based on custom field types do not appear in Datasheet view and are not included when you export a list to a Microsoft Excel worksheet.
Creating Custom Field Types
There are different requirements for creating custom field types, depending on whether your custom field type is simple or more complex.
Minimum Requirements for any Custom Field Type
To create a custom field type, you must always create, at a minimum, a field type definition and a field class, as described below.
A field type definition. This field type definition is an XML file that contains the information that Windows SharePoint Services needs to correctly render the field, including its column header, on list view pages (such as AllItems.aspx). It is typically also used to render the field on the view list item page (DispForm.aspx) and sometimes it is used to render the field on the New or Edit (list item) pages. It can also declare and define special variable properties of the field type whose values will be set whenever a column is created based on the field type. Most importantly, it contains information about the assembly that includes the compiled field type.
For more information about field type definitions, see Custom Field Type Definition and Patterns of Custom Field Rendering.
A field class. This is a class whose instances can represent particular fields that are based on your custom field type. This class must inherit from SPField or one of the classes in Windows SharePoint Services that derive from it. The class is compiled into a strong-named assembly and you deploy it to the global assembly cache. In the context of a list view, an SPField object represents a column and its properties, such as whether it can be sorted. In the context of the Display, New, and Edit modes, an SPField object represents a particular field of a list item — a cell in the table that constitutes the list — and the value of that cell in the content database.
Optionally, this class can contain custom data validation for your field type. For more information about custom validation, see Custom Field Data Validation.
For more information about custom field classes, see Custom Field Classes.
Other Development that May Be Required
For all but the simplest custom field types, you will usually need to create one or more of the following entities in addition to the minimum actions described in the preceding section:
A rendering control class. This is a class that can be used, in conjunction with a rendering template (see below), to render your fields in New mode or Edit mode, or, less commonly, in Display mode. This class must inherit from BaseFieldControl or one of the classes in Windows SharePoint Services that derive from it. This class is compiled into the same assembly as the field class.
For more information about rendering controls, see Field Rendering Controls and Patterns of Custom Field Rendering.
A rendering template. The rendering template is defined in an .ascx file located in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\ControlTemplates.
This template is used in conjunction with the CreateChildControls method of a rendering control class, to render a field in New, Edit, or Display mode.
For more information about rendering templates, see Field Rendering Templates and Patterns of Custom Field Rendering.
A custom value class or structure. If you are creating a custom field class that requires a special data structure for the field data, you can create a value class (or structure) to contain your field data.
For more information about creating custom value classes, see Custom Field Value Classes.
An editing control for the variable properties of the field type. All field types require a name, a data type, a description, and other common properties; but many field types also have properties that are relevant only to fields of that particular type. These variable properties are set by users in the UI when they create a new column that is based on the field type. Usually, an element in the field type definition (see above) determines how these property setting controls are rendered. But sometimes a special editing control is required. Such a control is defined in an .ascx file that usually has a code-behind file that contains its logic. Creating a special editing control is recommended if you need to perform custom functions, such as complicated computational logic, looking up values from data sources, or custom data validation of the values that a user might choose when configuring a new column.
Note
An editing control for variable properties should not be confused with the rendering template .ascx file described above. The rendering template renders a field and its value on a page for creating, editing, or displaying a particular list item from an existing list, which normally already has its columns defined. The editing control for variable properties, by contrast, renders certain properties of the field type when a column is being created based on that type.
For more information about custom field type rendering and editing controls for variable properties, see Custom Field Type Property Rendering and Editor Controls for Field Type Properties.
See Also
Tasks
Walkthrough: Creating a Custom Field Type
Concepts
Custom Field Type Property Rendering