This documentation is archived and is not being maintained.

How to: Create a Custom Control for a Form

Windows SharePoint Services 3

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.

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.

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.

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.

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

  1. In Microsoft Visual Studio 2005, click File, point to New, and then click Project.

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

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

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

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

  6. Press CTRL+SHIFT+B to build the solution.

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

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">
    <SharePoint:InformationBar runat="server"/>
    <wssuc:ToolBar CssClass="ms-formtoolbar" id="toolBarTbltop" RightButtonSeparator="&nbsp;" runat="server">
        <SharePoint:SaveButton TabIndex=1 runat="server"/>
        <SharePoint:GoBackButton runat="server"/>
    <SharePoint:FormToolBar runat="server"/>
    <SharePoint:FormComponent TemplateName="CustomDocumentLibraryFormCore" runat="server"/>

<SharePoint:RenderingTemplate ID="CustomDocumentLibraryFormCore" runat="server">
    <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"/>
    <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="">   
    <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">
        <SharePoint:CreatedModifiedInfo runat="server"/>
        <SharePoint:SaveButton runat="server"/>
        <SharePoint:GoBackButton runat="server"/>

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

To create a custom control template file for document libraries

  1. 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=, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
    <%@Register TagPrefix="SharePoint" Assembly="Microsoft.SharePoint, Version=, 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=, Culture=neutral, PublicKeyToken=b23bfc50a92c9e0d" %>
    <%@Register TagPrefix="CustomOverrideControls" Assembly="CustomOverrideControls, Version=, Culture=neutral, PublicKeyToken=b23bfc50a92c9e0d" namespace="CustomOverrideControls"%>
  2. Add a template definition to the .ascx file that overrides a specific default control template, such as the previous example.

  3. Reset Internet Information Services (IIS) for changes to take effect.

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