Switch View

How to: Create a Custom Form Contro...

Community Content

In this section

Statistics Annotations (1)

Click here to expand

Language Filter

This page is specific to

The 2007 product release

Other versions are also available for the following:

The 2010 product release

How to: Create a Custom Control for a Form

To customize list item forms, you can extend a default Windows SharePoint Services server control to define your own custom control, and then override an existing default form template with a custom template that references your custom control. You can create a class library that defines a custom class, copy the DLL of your project to the global assembly cache (GAC), and then add an .ascx file containing a custom control template definition that references the DLL to Local_Drive:\\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\CONTROLTEMPLATES.

ListFieldIterator Control

The Microsoft.SharePoint.WebControls.ListFieldIterator control is used to enumerate item fields for display within a form. This control is inserted in list item forms through a series of nested control templates that are defined in \CONTROLTEMPLATES\DefaultTemplates.ascx. The DocumentLibraryForm template lays out the toolbar controls and links for the form, but this template also inserts the DocumentLibraryFormCore template. This template in turn inserts a DocumentLibraryFields control. The default template for the DocumentLibraryFields control is FileFormFields, a control that is defined in DefaultTemplates.ascx that inserts the ListFieldIterator control.

Example

The following example defines a custom list field iterator control that extends the ListFieldIterator class, overriding its IsFieldExcluded method. The example prevents a specific field from being displayed in document library forms to users who are members of a particular group unless they are site administrators.

Visual Basic

Imports System
Imports System.Collections.Generic
Imports System.Text
Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.WebControls

Namespace CustomOverrideControls

   Public Class CustomListFieldIterator
      Inherits ListFieldIterator
      
      Protected Overrides Function IsFieldExcluded(field As SPField) As Boolean
         Dim site As SPWeb = SPContext.Current.Web
         Dim groupId As Integer = site.Groups("ExcludeGroup").ID
         
         If site.IsCurrentUserMemberOfGroup(groupId) AndAlso field.Title = "MySpecialColumn" AndAlso site.CurrentUser.IsSiteAdmin = False Then
            Return True
         End If
         Return MyBase.IsFieldExcluded(field)
      End Function 'IsFieldExcluded
   End Class 'CustomListFieldIterator
End Namespace 'CustomOverrideControls

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;

namespace CustomOverrideControls
{
   public class CustomListFieldIterator : ListFieldIterator
   {
      protected override bool IsFieldExcluded(SPField field)
      {
         SPWeb site = SPContext.Current.Web;
         int groupId = site.Groups["ExcludeGroup"].ID;

         if (site.IsCurrentUserMemberOfGroup(groupId) && field.Title == "MySpecialColumn" && site.CurrentUser.IsSiteAdmin == false)
         {
            return true;
         }
         return base.IsFieldExcluded(field);
      }
   }
}

To create a custom control to extend the list field iterator

In Microsoft Visual Studio 2005, click File, point to New, and then click Project.
In the New Project dialog box, select the language for your project in the Project Types box, select Class Library in the Templates box, type a name and location for building the project, and then click OK.
To add a reference to the Microsoft.SharePoint assembly, right-click the project in Solution Explorer, and on the .NET tab in the Add Reference dialog box, select Windows SharePoint Services, and then click OK.
To give your custom assembly a strong name when you build the project, right-click Properties in Solution Explorer, click Signing, select Sign the assembly, and specify a name for the strong name key file.
Double-click the project .cs or .vb file in Solution Explorer, and add code such as in the previous example to define a class for a custom control that extends a Windows SharePoint Services control.
Press CTRL+SHIFT+B to build the solution.
In Windows Explorer, drag the DLL from your project folder into the GAC.

To implement a custom form control, you must create an .ascx file containing a control template that overrides a default template to insert the custom control in the form page.

Example

The following example defines three nested custom templates for a form. The first template overrides the DocumentLibraryForm template to create a reference to the second template, CustomDocumentLibraryFormCore. This template in turn specifies the third template, CustomFileFormFields, as the defining template for the DocumentLibraryFields control. The third template inserts a custom list field iterator that can be defined in a class library as in the previous example.

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

<SharePoint:RenderingTemplate ID="CustomDocumentLibraryFormCore" runat="server">
  <Template>
    <TABLE class="ms-formtable" style="margin-top: 8px;" border=0 cellpadding=0 id="formTbl" cellspacing=0 width=100%>
      <SharePoint:ChangeContentType runat="server"/>
      <SharePoint:DocumentLibraryFields TemplateName="CustomFileFormFields" runat="server"/>
      <SharePoint:ApprovalStatus runat="server"/>
    </TABLE>
    <SharePoint:WebPartPageMaintenanceMessage runat="server"/>
    <SharePoint:DocumentTransformersInfo runat="server"/>
    <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 runat="server"/>
    <SharePoint:InitContentType runat="server"/>
    <wssuc:ToolBar CssClass="ms-formtoolbar" id="toolBarTbl" RightButtonSeparator="&nbsp;" runat="server">
      <Template_Buttons>
        <SharePoint:CreatedModifiedInfo runat="server"/>
      </Template_Buttons>
      <Template_RightButtons>
        <SharePoint:SaveButton runat="server"/>
        <SharePoint:GoBackButton runat="server"/>
      </Template_RightButtons>
    </wssuc:ToolBar>
    </td></tr></TABLE>
  </Template>
</SharePoint:RenderingTemplate>

<SharePoint:RenderingTemplate ID="CustomFileFormFields" runat="server">
  <Template>
    <CustomOverrideControls:CustomListFieldIterator runat="server"/>
  </Template>
</SharePoint:RenderingTemplate>

To create a custom control template file for document libraries

In a text editor, create an .ascx file containing the necessary directives in \12\TEMPLATE\CONTROLTEMPLATES. The previous example would require directives such as the following to register the assembly and namespace of the custom control.

<%@ Control Language="C#"   %>
<%@Assembly Name="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@Register TagPrefix="SharePoint" Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" namespace="Microsoft.SharePoint.WebControls"%>
<%@ Register TagPrefix="wssuc" TagName="ToolBar" src="/_controltemplates/ToolBar.ascx" %>
<%@ Register TagPrefix="wssuc" TagName="ToolBarButton" src="/_controltemplates/ToolBarButton.ascx" %>
<%@Assembly Name="CustomOverrideControls, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b23bfc50a92c9e0d" %>
<%@Register TagPrefix="CustomOverrideControls" Assembly="CustomOverrideControls, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b23bfc50a92c9e0d" namespace="CustomOverrideControls"%>

Add a template definition to the .ascx file that overrides a specific default control template, such as the previous example.
Reset Internet Information Services (IIS) for changes to take effect.
To test the previous example, create a field through the user interface whose title begins with "z" and navigate to a form for an item in the document library to see the changes.