How to: Create a Custom Control for a Form

  • Article

Applies to: SharePoint Foundation 2010

To customize list item forms, you can extend a default Microsoft SharePoint Foundation 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, add 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 a subfolder within %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\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 the DefaultTemplates.ascx file that is located in the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATES\CONTROLTEMPLATES directory. 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 the DefaultTemplates.ascx file 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.

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

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

  2. In the New Project dialog box, select the language for your project in the Installed Templates box, select Class Library as the project template, 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 Microsoft SharePoint, and then click OK.

  4. To give your custom assembly a strong name when you build the project, right-click the project 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 SharePoint Foundation control.

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

  7. Use gacutil.exe, the command-line utility that is installed with the Microsoft .NET Framework 2.0 Software Development Kit, to copy the project DLL to the Global Assembly Cache (GAC). Type a command like the following at the command prompt: gacutil.exe -if "<Full file system path to DLL>".

To implement a custom form control, you must create an .ascx file that contains a control template that overrides a default template that in turn allows you 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

  1. Create a user control in a SharePoint project as described in How to: Create a User Control for a SharePoint Application Page or Web Part. When you deploy the project, Visual Studio creates a project subfolder in the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATES\CONTROLTEMPLATES directory that contains the.ascx file.

  2. Add a template definition to the .ascx file that overrides a specific default control template, as shown in the previous example.

  3. Reset Internet Information Services (IIS) so that changes can 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.