Creating Custom Form Templates

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.

The ASP.NET control templates that are defined in \12\TEMPLATE\CONTROLTEMPLATES\DefaultTemplates.ascx determine the layout of Windows SharePoint Services list item forms. These templates can nest controls that in turn use more control templates for form layout definition. The controls can contain HTML markup and Web controls, but not data-bound statements involving <%#...%> syntax. To override a default control template globally on a front-end Web server, you can add a custom .ascx file to the \CONTROLTEMPLATES directory with a control template ID that matches the ID of the existing one in DefaultTemplates.ascx.

Creating Custom Templates

In addition to overriding default templates, you can create your own custom form templates and refer to them by either list type or content type. To register a custom form template by list type, specify the name of the form template through the Template attribute on a <Form> tag in the Schema.xml file of the list definition. For example:

<Forms>
  <Form Type="DisplayForm" Url="DispForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" /> 
  <Form Type="EditForm" Url="EditForm.aspx" SetupPath="pages\form.aspx" Template="MyCustomForm" WebPartZoneID="Main" /> 
  <Form Type="NewForm" Url="NewForm.aspx" SetupPath="pages\form.aspx" Template="MyCustomForm" WebPartZoneID="Main" /> 
</Forms>

To register a custom form template by content type, add a definition such as the following as a child of the <ContentType> tag in your Elements.xml file for the Feature.

<XmlDocuments>
  <XmlDocument NamespaceURI="http://schemas.microsoft.com/sharepoint/v3/contenttype/forms">
    <FormTemplates  xmlns="http://schemas.microsoft.com/sharepoint/v3/contenttype/forms">
      <Display>MyCustomForm</Display>
      <Edit>MyCustomForm</Edit>
      <New>MyCustomForm</New>
    </FormTemplates>
  </XmlDocument>
</XmlDocuments>

In the previous examples, "MyCustomForm" is the ID of a custom control template that you are adding to the \CONTROLTEMPLATES directory.

Template Structure

ASCX-based control templates bring together multiple controls into a nested structure, where the controls themselves consist of templates and can be used to richly extend list item forms.

The document library form template that is defined in \12\TEMPLATE\CONTROLTEMPLATES provides a good example of a control template structure. The following example shows the default control template defined for the document library form.

<SharePoint:RenderingTemplate ID="DocumentLibraryForm" >
  <Template>
    <SharePoint:InformationBar />
      <wssuc:ToolBar CssClass="ms-formtoolbar" id="toolBarTbltop" RightButtonSeparator="&nbsp;" >
        <Template_RightButtons>
          <SharePoint:SaveButton />
          <SharePoint:GoBackButton />
        </Template_RightButtons>
      </wssuc:ToolBar>
    <SharePoint:FormToolBar />
    <SharePoint:FormComponent TemplateName="DocumentLibraryFormCore" />
  </Template>
</SharePoint:RenderingTemplate>

In this example, the document library form template draws together several components to lay out the complete form template. Many of these components derive from the Microsoft.SharePoint.WebControls.FormComponent base class, which itself derives from Microsoft.SharePoint.WebControls.TemplateBasedControl and means that the components can themselves be made into templates.

However, most of the form is actually rendered through a separate template that is defined in DefaultTemplates.ascx whose ID is DocumentLibraryFormCore. This template is further composed of various components, including some table-based HTML structure to help organize the page layout, as shown in this example:

<SharePoint:RenderingTemplate ID="DocumentLibraryFormCore" >
  <Template>
    <TABLE class="ms-formtable" style="margin-top: 8px;" border=0 cellpadding=0 id="formTbl" cellspacing=0 width=100%>
      <SharePoint:ChangeContentType />
      <SharePoint:DocumentLibraryFields />
      <SharePoint:ApprovalStatus />
    </TABLE>
    <SharePoint:WebPartPageMaintenanceMessage />
    <SharePoint:DocumentTransformersInfo />
    <table cellpadding=0 cellspacing=0 width=100%><tr><td class="ms-formline"><IMG SRC="/_layouts/images/blank.gif" width=1 height=1 alt=""></td></tr></table>
    <TABLE cellpadding=0 cellspacing=0 width=100% style="padding-top: 7px"><tr><td width=100%>
      <SharePoint:ItemHiddenVersion />
      <SharePoint:InitContentType />
      <wssuc:ToolBar CssClass="ms-formtoolbar" id="toolBarTbl" RightButtonSeparator="&nbsp;" >
        <Template_Buttons>
          <SharePoint:CreatedModifiedInfo />
        </Template_Buttons>
        <Template_RightButtons>
          <SharePoint:SaveButton />
          <SharePoint:GoBackButton />
        </Template_RightButtons>
      </wssuc:ToolBar>
    </td></tr></TABLE>
  </Template>
</SharePoint:RenderingTemplate>

A key component in the DocumentLibraryFormCore template of this example is the DocumentLibraryFields component, which refers to the Microsoft.SharePoint.WebControls.DocumentLibraryFields control that derives from the Microsoft.SharePoint.WebControls.ListFieldIterator class. The list field iterator contains the logic for laying out fields in a columnar order. However, the ListFieldIterator class only renders controls if they have not been overridden in the templates. Therefore, if you add a field control for a specific field (for example, a control that puts the Title field control in the upper right and the Author field control under it), the iterator does not lay out that control. You can also instead choose to specify your own list field iterator, which derives from the ListFieldIterator class, and provide custom logic for doing field iteration.

You can override the DocumentLibraryForm template and specify a different DocumentLibraryFormCore template. You can then further customize the form template from there, specifying existing controls, or adding references to other custom controls that are defined in an assembly or .ascx file.