How to: Create Field Rendering Templates
Applies to: SharePoint Foundation 2010
A field rendering template is a RenderingTemplate object that is defined as a RenderingTemplate element in an .ascx file in the folder %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\controltemplates. It is used in conjunction with the CreateChildControls method of a rendering control class to render a field in New, Edit, or Display modes.
Relation of Rendering Templates to Rendering Controls
A RenderingTemplate object is a kind of hybrid Control-ITemplate object. It derives from Control and adds just one new member: a Template 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.
The Rendering Template System
Every field rendering control has at least one field rendering template associated with it. At render-time, SharePoint Foundation looks up the needed template by searching the IDs of all the controls declared in .ascx files in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\CONTROLTEMPLATES (all of which load when the Web application starts).
Field Rendering Configuration
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 two rendering templates and the control uses its TemplateName and DisplayTemplateName properties to specify their IDs.
One template provides most of the field rendering in the New and Edit modes. The other provides most of the field rendering in Display mode.
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 and 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.
Scenarios Requiring Multiple Rendering Templates
In addition to Template, TemplateName, DisplayTemplate, and DisplayTemplateName; you can also work with AlternateTemplate, AlternateTemplateName.
Use an alternate template to render your custom field in any page context in which the main template does not meet your requirements. Some examples are listed here:
If the field is required on some lists but not on others, you can have an alternate template that is just like the main one except that it adds an indicator, say, a red asterisk, that the field is required on specific lists. Then have the get accessor of ControlTemplate check the Required property of the underlying field and return either Template or AlternateTemplate as appropriate.
If you plan to use many custom field types that will render almost identically, you may be able to achieve better code reuse by creating separate templates for use in New and Edit modes. The former would assign default values to child objects and the latter would assign current values. This would enable you to avoid repeating the assignment logic in the CreateChildControls method of every one of the custom field type classes. Again, the get accessor of ControlTemplate would determine which template is used based on the control mode.
Using an alternate template can also be useful when your field needs special rendering on certain Web sites, site collections, or Web applications. Consider, for example, a Web site designed for people with a visual impairment, such as color blindness. The get accessor of ControlTemplate can examine the value of RenderContext to see if the special template is needed and return the appropriate template.
For custom field types that inherit from SPFieldNumber and that sometimes, but not always, need to be rendered as percentages, having two different rendering templates can be a great development time saver. Override the get accessor of ControlTemplate to respond to the value of the SPFieldNumber.ShowAsPercentage property.
Adding More Template Associations
You can, of course, add more rendering template associations to the field rendering control that you derive from BaseFieldControl. We recommend that you follow this pattern:
Create a new private field of type ITemplate.
Create a new public property as a wrapper around the private field and give it a name such as circumstanceTemplate, where circumstance identifies the circumstance in which you anticipate using the template.
Create a second public property that returns a String and name it circumstanceTemplateName.
The get accessor for circumstanceTemplate should return the private field only if the latter is not null. Otherwise, it should return the ITemplate that is named by circumstanceTemplateName. Use the GetTemplateByName() method to do this.
Override the get accessor of ControlTemplate to return circumstanceTemplate whenever circumstance is true.
Using Web Custom Controls as Templates
Your custom field rendering control will also inherit two special ITemplate properties: CustomTemplate and CustomAlternateTemplate. These two properties are marked with the [PersistenceMode(PersistenceMode.InnerProperty)] attribute. This means that the ITemplate objects that they return are compiled and they persist inside the field rendering control as nested tags. There are several advantages to using precompiled templates; for example, they can be added to a page in a visual designer such as SharePoint Designer or Visual Studio by dragging and dropping them from the designer toolbox. But there are disadvantages as well. For more information about Web user controls and custom Web controls, see Web User Controls and Web Custom Controls and PersistenceModeAttribute.
See Also
Tasks
Walkthrough: Creating a Custom Field Type
Concepts
How to: Create a Custom Field Class
How to: Create a Custom Field Value Class
How to: Create a Custom Field Type Definition
Custom Field Type Property Rendering
How to: Create an Editor Control for a Field Type Property