Custom Field Type Property Rendering
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.
Many characteristics of field types are universal; for example, all field types have a property that allows them to be sorted, which can be set to true or false. But custom field types often have variable properties that only make sense given the intended purpose and the underlying data type of the field type. Consider, for example, a regular expression field type whose values are strings that match a specified regular expression. But the particular regular expression that needs to be matched will vary from one column to another. For this reason, it must be set by users when they create a column based on the field type on the New Site Column, Change Site Column, Create Column, and Change Column pages.
Two Ways to Render Field Properties
Windows SharePoint Services 3.0 provides two ways for you to render the variable field properties of your custom field type on these pages:
Define the properties of the field type using Collaborative Application Markup Language (CAML) markup in the PropertySchema Element (Field Types) of the field type definition. Windows SharePoint Services then automatically displays the field properties, as defined, in the Additional Column Settings section of the New Site Column, Change Site Column, Create Column, and Change Column pages.
Create an editor user control (.ascx file) that displays the field properties and enables setting the properties to particular values when a column based on the field type is created. Windows SharePoint Services then hosts this control in the pages mentioned above.
This topic discusses the advantages and limitations of each approach.
Note
With two exceptions, neither of these methods is used to render, on the New Site Column, Change Site Column, Create Column, and Change Column pages, the variable properties of the field types that ship with Windows SharePoint Services 3.0. Instead, rendering is hard-coded markup on the page file (such as FldNew.aspx) itself. (The exceptions are the Lookup and User field types which both use an editor control.) For this reason, a custom field class can not inherit any information about rendering the properties of the field type in the Windows SharePoint Services 3.0 class from which it inherits (except, possibly, if it inherits from the Lookup or User field types). For example, if you derive a custom field type from the SPFieldText class, your new custom field type does not inherit the rendering information for the text box (on the New Site Column, Change Site Column, Create Column, and Change Column pages) where the column creators or column editors specify the maximum length of the field. To render any of the parent class's field type properties, you must specify your own renderings, either with a PropertySchema in the field definition file or by using a field editor user control. (However, you might be able to inherit field property rendering if your custom field class inherits from either the Lookup or User classes. See below.)
Rendering Field Properties by Using the PropertySchema Element
When you create your field type definition in a fldtypes*.xml file, you can define each field type property as a Field element within the PropertySchema element. If you define the field type properties in the PropertySchema element, Windows SharePoint Services automatically renders those properties based on the schema.
The PropertySchema element contains a Fields element, which in turn contains a Field element for each field type property that you want to define. You can use standard Collaborative Application Markup Language (CAML) within each Field element. For more information about custom field types, see Custom Field Type Definition.
Because Windows SharePoint Services automatically handles the rendering of the field type properties, this approach limits you to the rendering options available when using CAML. You cannot specify custom processing or validation handling for your field type properties. For this reason, this approach works best with simple field type properties that do not require complicated processing or validation logic.
Note
It is important to remember that we are not talking about validation of particular values that end-users will give to the field in a particular list item on a particular list. Rather, we are talking about properties of the field (that is, column) set on the New Site Column, Change Site Column, Create Column, and Change Column pages. It is very rare that the values a column creator or column editor might use to set a field property would need validation.
Rendering Field Properties by Using a Field Editor User Control
You can also render the field type properties by authoring an .ascx page to act as a field editor user control. This approach, which is more involved, enables you to write custom data processing logic in the code-behind page of the ASCX control. This approach is recommended if you need to perform custom functions, such as complicated computational logic, look-up of values from data sources, and custom data validation.
You specify the control to use as a field editor control using "FieldEditorUserControl" as the value of the Name attribute of a Field Element (Field Types) in the field type definition XML file. For example:
<Field Name="FieldEditorUserControl">
/_controltemplates/LookupFieldEditor.ascx
</Field>
You can specify only one field editor control for a particular field type class. If you inherit from a field type class that has a field editor user control already specified (such as the Lookup or User field types), and you specify another field editor control in your field type definition, then you do not inherit the field editor user control of the parent class as well. To inherit the parent field type's field editor control, you must either not include the <Field Name="FieldEditorUserControl"> element in your field type definition, or you must specify the very same control as the parent field type's definition specifies.
Note
Your field editor control class cannot inherit from either the LookupFieldEditor or the UserFieldEditor control classes, which are the only two field editor controls that ship with Windows SharePoint Services 3.0. They are not accessible from your code.