How to: Create a Field Rendering Control

Last modified: April 05, 2010

Applies to: SharePoint Foundation 2010

A rendering control class can be used, in conjunction with one or more rendering templates, to render your custom fields in New, Edit, or Display mode.

A rendering control class must inherit from BaseFieldControl or one of the classes in Microsoft SharePoint Foundation that derive from it. This class is compiled into the same assembly as the custom field class.

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

field_type_name FieldControl

Examples of properly named field control classes are, TargetDateFieldControl and RegularExpressionFieldControl. (The BaseFieldControl-derived classes that ship with SharePoint Foundation were created before this naming convention was determined and they follow the pattern field_type_nameField such as the DateTimeField.)

An object instantiating a rendering control holds, in its Field property, a reference to the field object that it renders. The latter holds a reference to its rendering control in its FieldRenderingControl property. 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 UI.

Every rendering control has at least one rendering template associated with it. A RenderingTemplate object is defined as a RenderingTemplate element in an .ascx file in the folder %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\controltemplates. The rendering template is referenced by its ID value in the rendering control object's TemplateName property or DisplayTemplateName property.

Note Note

BaseFieldControl inherits, from TemplateBasedControl, members that enable it to be linked to multiple rendering templates and to switch between them based on the rendering context.

For more information about rendering templates, see How to: Create Field Rendering Templates.

A rendering control class overrides the CreateChildControls method that it inherits from Control. Since the rendering template is doing most of the rendering work, the CreateChildControls method has much less to do than it would in a classic ASP.NET control class. Typically, it provides only a final polish to the child controls. For example, it might assign a default value to a child control in New mode or assign the field's current value to a child control in Display and Edit modes. It is not likely that your overrides of CreateChildControls will contain a lot of new operators creating child controls (which may come as a surprise if you have a background in ASP.NET programming).

Data validation logic is sometimes included in CreateChildControls. For more information about custom field data validation, see Custom Field Data Validation.