Form and Field Controls

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

Extending 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.

Page Initialization

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.

Public Sub New()
    AddHandler Me.Init, AddressOf Page_Init
End Sub
Private Sub Page_Init(sender As Object, e As System.EventArgs)
    ... 'Add field control to the page control tree.
End Sub

public EditMetadata(): base()
{
    this.Init += new EventHandler(Page_Init);
}
private void Page_Init(object sender, System.EventArgs e)
{
    ... //Add field control to the page control tree.
}

Conditional Rendering

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.

Validation

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.

Field Order

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).

FormField Control

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.

CompositeField Control

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>