Form and Field Controls
Last modified: April 09, 2010
Applies to: SharePoint Foundation 2010
A Microsoft SharePoint Foundation form consists of ASP.NET controls that define the form and also the fields and other elements in the form. SharePoint controls follow a control hierarchy in which there is a base control that all controls derive from.
The controls that are used in SharePoint forms are defined within the Microsoft.SharePoint.WebControls namespace, and they support all SharePoint Foundation form functionality. This namespace provides, for example, a control that renders fields based on the list schema, controls for all the default SharePoint field types, controls for the toolbar, header, and footer, and a control for the list. You can reuse existing controls, or extend controls for specific functionality.
Figure 1 shows the hierarchy of common controls that are used in forms and their fields.
Figure 1. Common form and field controls
You can create custom field controls that inherit the basic field functionality of SharePoint Foundation controls but that modify the way fields are rendered. A custom field control inherits from Microsoft.SharePoint.WebControls.BaseFieldControl, so that it does not need to re-implement core field functionality to customize field rendering. You can just insert an existing field control on the form page and set properties on the control, or you can create a code-behind class that adds the control.
When you programmatically create a field control through code behind, you must create the control during the initialization stage of the page life cycle (Page_Init). Otherwise, because ASP.NET loads the view state before the load stage, the field control does not receive updated user input when it is created.
The following example illustrates how to call Page_Init.
SharePoint Foundation supports three different ways to determine which control template to use in rendering a form:
Setting it programmatically for the control
Setting it in the instance of the control by setting a template attribute
Defining the template in the markup of the control
Conditional rendering of forms and fields through control templates or code behind involves using, for example, the Template and AlternateTemplate properties and other members inherited from Microsoft.SharePoint.WebControls.TemplateBasedControl. You can create forms that select the templates used to render controls and that display fields differently depending on the permission level of users.
SharePoint Foundation does not use the .NET validation controls. Default fields provided in the Microsoft.SharePoint.WebControls namespace inherit from BaseFieldControl, which implements the System.Web.UI.IValidator interface and overrides its Validate method. Server-side validation in SharePoint forms is not limited to the field control level but can also be performed programmatically in code that uses the object model.
The list schema or content type determines the order of fields as they are displayed in a list form. The Microsoft.SharePoint.WebControls.ListFieldIterator repeater control within a form follows the field order defined in the list schema file (Schema.xml). The field order defined in the schema determines the order for all three form control modes (new, edit, and display).
You can use FormField controls to produce a fixed layout of specific fields, and use the ListFieldIterator control to render remaining fields. The FormField control instantiates a type-specific field control based on the field schema. Therefore, to add a field control within a form, use FormField instead of a type-specific field control. As an example, if you use a type-specific field control such as TextField on a particular Text field, but the field type is later changed to another data type, such as Number, field rendering will fail because the field control (TextField) will not match the field type. However, using a FormField
control will instantiate the correct control and field rendering will not fail.
The CompositeField control is useful because its default control template includes several field controls. The CompositeField control uses FieldLabel to render the file name, FormField to display data, and FieldDescription to display a description for the field. In addition, the CompositeField control includes the AppendOnlyHistory control to display an AppendOnly multiline Text field, which remains hidden in other scenarios.
The following example shows the control template defined in DefaultTemplates.ascx for the CompositeField control.
<SharePoint:RenderingTemplate ID="CompositeField" runat="server"> <Template> <TD nowrap="true" valign="top" width="190px" class="ms-formlabel"><H3 class="ms-standardheader"> <SharePoint:FieldLabel runat="server"/> </H3></TD> <TD valign="top" class="ms-formbody" width="400px"> <SharePoint:FormField runat="server"/> <SharePoint:FieldDescription runat="server"/> <SharePoint:AppendOnlyHistory runat="server"/> </TD> </Template> </SharePoint:RenderingTemplate>
You can create a custom list field iterator template that includes a custom composite field control, as in the following example:
<SharePoint:RenderingTemplate ID="CustomListFieldIterator" runat="server"> <Template> <TR> <SharePoint:CompositeField Template="CustomCompositeField" runat="server"/> </TR> </Template> </SharePoint:RenderingTemplate>