How to: Create a Custom Control for a Form
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.
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.
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" >
<Template>
<SharePoint:InformationBar />
<wssuc:ToolBar CssClass="ms-formtoolbar" id="toolBarTbltop" RightButtonSeparator=" " >
<Template_RightButtons>
<SharePoint:SaveButton TabIndex=1 />
<SharePoint:GoBackButton />
</Template_RightButtons>
</wssuc:ToolBar>
<SharePoint:FormToolBar />
<SharePoint:FormComponent TemplateName="CustomDocumentLibraryFormCore" />
</Template>
</SharePoint:RenderingTemplate>
<SharePoint:RenderingTemplate ID="CustomDocumentLibraryFormCore" >
<Template>
<TABLE class="ms-formtable" style="margin-top: 8px;" border=0 cellpadding=0 id="formTbl" cellspacing=0 width=100%>
<SharePoint:ChangeContentType />
<SharePoint:DocumentLibraryFields TemplateName="CustomFileFormFields" />
<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=" " >
<Template_Buttons>
<SharePoint:CreatedModifiedInfo />
</Template_Buttons>
<Template_RightButtons>
<SharePoint:SaveButton />
<SharePoint:GoBackButton />
</Template_RightButtons>
</wssuc:ToolBar>
</td></tr></TABLE>
</Template>
</SharePoint:RenderingTemplate>
<SharePoint:RenderingTemplate ID="CustomFileFormFields" >
<Template>
<CustomOverrideControls:CustomListFieldIterator />
</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.