Custom Field Type Property Rendering
Applies to: SharePoint Foundation 2010
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. 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.
Rendering Field Properties
You can define the rendering of a field type properties by authoring an .ascx page to act as a field editor user control. This enables you to write custom data processing logic in the code-behind page of the ASCX control, 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
With two exceptions editor controls are not 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 SharePoint Foundation. (Neither is the legacy method of rendering field type properties, described in the section below, used.) 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 cannot inherit any information about rendering the properties of the field type in the SharePoint Foundation 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 rendering with a field editor user control.
Aside from the question of whether a custom field type class can inherit rendering information from its parent class, there is the question of whether the editor control itself can inherit from one of the built-in editor controls. The answer is 'no'. 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 SharePoint Foundation. They are not accessible from your code.
Rendering Field Properties by Using the PropertySchema Element
In earlier versions of SharePoint Foundation developers did not always use ASCX editor controls to render field type properties. This section describes an alternate method. This information is provided solely to assist you in debugging a custom field type that was originally developed against an earlier version of the SharePoint Foundation platform and that uses the older method to render field type properties. Although this method still works and legacy custom fields render properly, we recommend that you not use this method for any new custom field projects. Using it may decrease the chance that your custom field type will be compatible with future versions of SharePoint Foundation.
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, SharePoint Foundation 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 How to: Create a Custom Field Type Definition.
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 worked best with simple field type properties that did 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.
See Also
Concepts
How to: Create a Custom Field Class