This documentation is archived and is not being maintained.

Field Rendering Templates

Windows SharePoint Services 3

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.

A field rendering template is a RenderingTemplate object that is defined as a RenderingTemplate element in an .ascx file in the folder C:\program files\common files\microsoft shared\web server extensions\12\template\controltemplates. It is used in conjunction with the CreateChildControls method of a rendering control class to render a field in New or Edit modes, and sometimes in Display mode.

A RenderingTemplate object is a kind of hybrid Control-ITemplate object. It derives from Control and adds just one new member: a RenderingTemplate() property that holds an ITemplate object. This makes it possible for a rendering control (derived from TemplateBasedControl) to reference ITemplate objects indirectly by referencing a RenderingTemplate object by the rendering template's ID property (ID). The rendering control can do this by using one or more of several String properties it has, such as TemplateName, which can hold the ID of a rendering template.

Every field rendering control has at least one field rendering template associated with it. At render-time, Windows SharePoint Services 3.0 looks up the needed template by searching the IDs of all the controls declared in .ascx files in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\CONTROLTEMPLATES (all of which load when the Web application starts).

You have a wide variety of options for fine-grained control of how your custom fields are rendered using field rendering templates. This topic describes only the most common configuration. For more information about other rendering options, see Patterns of Custom Field Rendering.

The pattern of field rendering configuration that you will find yourself using most often as you develop custom field types has these characteristics:

  • The rendering control is associated with only one rendering template and the control uses its TemplateName property to specify template's ID.

  • This one template provides most of the field rendering in the New and Edit modes. (Rendering in Display mode is most commonly handled by a RenderPattern defined in a field definition.)

  • The rendering control's CreateChildControls method assigns default values to the rendering control's child controls in New mode. It assigns the field's current values to the child controls in Edit mode. (It does nothing in Display mode.) It might also do other "final polish" rendering work such as assigning a CSS class to a child Label control.

  • Validation logic is implemented by the field rendering control's Validate, IsValid, and ErrorMessage members, and by the underlying field type's GetValidatedString method. (Validate might be called by CreateChildControls.)

BaseFieldControl inherits from TemplateBasedControl and from FieldMetadata 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 additional patterns of field rendering, see Patterns of Custom Field Rendering.