How to: Create a Custom Field Type
Applies to: SharePoint Foundation 2010
This topic provides an overview of the process of creating a custom field type and defining how it renders on list views and on the Display, New, and Edit forms.
For a concrete example of creating a custom field and defining its rendering, see Walkthrough: Creating a Custom Field Type.
1. Create a Field Type Definition
A field type definition is an XML file that contains the information that Microsoft SharePoint Foundation needs to register the field type and correctly render the field. Most importantly, it contains information about the assembly that includes the compiled field type.
For more information about field type definitions, see How to: Create a Custom Field Type Definition.
2. Create a Field Class
A field class is a class whose instances can represent particular fields that are based on your custom field type. This class must inherit from SPField or one of the classes in SharePoint Foundation that derive from it. The class is compiled into a strong-named assembly, and you deploy it to the global assembly cache. In the context of a list view, an SPField object represents a column and its properties, such as whether it can be sorted. In the context of the Display, New, and Edit modes, an SPField object represents a particular field of a list item—a cell in the table that constitutes the list—and the value of that cell in the content database.
Optionally, this class can contain custom data validation for your field type. For more information about custom validation, see Custom Field Data Validation.
For more information about custom field classes, see How to: Create a Custom Field Class.
3. (Optional) Create a Custom XSLT Style Sheet
The standard way that SharePoint Foundation renders fields on a list view is with XSLT style sheets. By default, the built-in style sheets of SharePoint Foundation simply render the value of the field in plain text. If you want a variant kind of rendering on list views, one basic ingredient of your system for rendering your custom field is a custom XSLT style sheet. You name it on the pattern fldtypes_*.xsl, and deploy it to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS\XSL. Your custom style sheet has priority over the default style sheet.
The header on the top of a column in list views is also rendered by an XSLT style sheet and, again, you would create a new style sheet to override the built-in one if, and only if, you need non-standard rendering the column header for your custom field type.
For more information about creating an XSLT style sheet for your custom field, see How to: Customize the Rendering of a Field on a List View.
Note
If you have a legacy custom field type developed under an earlier version of SharePoint Foundation, and it rendered differently on list views from the default rendering given to it by the XSLT rendering infrastructure, you have the option to turn off XSLT rendering of the field. You do this by adding <Field Name="CAMLRendering">TRUE</Field> as a child of the FieldType element in the fldtypes*.xml file that contains the Collaborative Application Markup Language (CAML) definition of the legacy custom field. Using this option causes the field (and the column header) on list views to be rendered in accordance with RenderPatterns. For more information, see RenderPattern Element (Field Types).
4. Create a Rendering Control Class
A rendering control class is used, in conjunction with a rendering template (see the next section), to render your fields in New mode, Edit mode, or Display mode. This class must inherit from BaseFieldControl or one of the classes in SharePoint Foundation that derive from it. This class is compiled into the same assembly as the field class.
Validation logic is implemented by the field rendering control's Validate, IsValid, and ErrorMessage members, and by the underlying field type's GetValidatedString method. (Validate might be called by CreateChildControls.)
For more information about rendering controls, see How to: Create a Field Rendering Control.
5. Create One or More Rendering Templates
Every field rendering control has at least one field rendering template associated with it to render a field in New, Edit, or Display mode. The association is made by having the field rendering control hold in one of its properties a reference to the ID of the field rendering template. At render-time, SharePoint Foundation looks up the needed template by searching the IDs of all the render templates declared in .ascx files in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\CONTROLTEMPLATES (all of which load when the web application starts). The rendering control's CreateChildControls method often does a "final polish" of the field's rendering, but most of the rendering work is done by the template. Typically the CreateChildControls method assigns default values to the rendering control's child controls in New mode. It assigns the field's current values to the child controls in Edit and Display mode. It might also do other final polish rendering work such as assigning a CSS class to a child Label control.
Typically, you must have two rendering templates: One renders the field in an editable form in New and Edit modes, and the other renders it in a read-only form in Display mode. However, it is possible to have all three modes share the same rendering template or to have a distinct rendering template for each mode. You can even have multiple templates for a given mode, with logic that invokes one or another based on aspects of the context, such as the particular user context or the type of list or site on which the field appears.
For more information about rendering templates, see How to: Create Field Rendering Templates.
A rendering template for the New and Edit modes usually requires interactive controls such as editable text boxes, check boxes, radio buttons, and drop-down list controls as its child controls. But the Display mode normally requires only Label or Literal controls or other static display controls. For this reason, you will probably need to create a different rendering template for Display mode. You specify this template (by ID) in the DisplayTemplateName property. The main template for use outside of Display mode, is specified by the TemplateName() property.
The rendering template that is actually used to render the field in any given context is the one that is returned by the rendering control's ControlTemplate property. The get accessor of that property selects from among the rendering templates associated with the rendering control, using decision criteria such as the following:
The current HTTP context
The control mode
Whether or not the field is required
Whether or not the field, if numerical, should be rendered as a percentage
Whether or not the list item is a folder
You can override this property and have its get accessor check the control mode and return DisplayTemplate when the mode is Display. (Unless it has been explicitly set to some other template, DisplayTemplate returns the template identified by DisplayTemplateName.) Unless you need other decision logic in the get accessor for ControlTemplate, you can have it call the base property's get accessor in New or Edit mode.
Note
An alternative means of designating a rendering template in Display mode is to have the CreateChildControls method assign DisplayTemplateName to TemplateName in Display mode. (Unless it has been overridden, ControlTemplate returns Template and unless the latter's get accessor is overridden, it returns the template identified by TemplateName.) A possible weakness of using the CreateChildControls method in this way is that the method does not run in a context in which the field is not being rendered, such as when, for debugging purposes, you are checking the value of ControlTemplate in the object model.
6. (Optional) Create a Field Value Type
If you are creating a custom field class that requires a special data structure for the field data, you can create a value class (or structure) to contain your field data.
For more information about creating custom value classes, see How to: Create a Custom Field Value Class.
7. (Optional) Create an Editing Control
All field types require a name, a data type, a description, and other common properties; but many field types also have properties that are relevant only to fields of that particular type. Users set these variable properties in the user interface (UI) when they create a new column that is based on the field type. Usually, an element in the field type definition (see earlier in this topic) determines how these property setting controls are rendered. But sometimes a special editing control is required. Such a control is defined in user control; that is, an .ascx file that usually has a code-behind file that contains its logic. Creating a special editing control is recommended if you need to perform custom functions, such as complicated computational logic, looking up values from data sources, or custom data validation of the values that a user might choose when configuring a new column.
Note
An editing control for variable properties should not be confused with the rendering template .ascx files described earlier. The rendering template renders a field and its value on a page for creating, editing, or displaying a particular list item from an existing list, which normally already has its columns defined. The editing control for variable properties, by contrast, renders certain properties of the field type when a column is being created based on that type.
For more information about custom field type rendering and editing controls for variable properties, see Custom Field Type Property Rendering and How to: Create an Editor Control for a Field Type Property.
8. Deploy the Elements
For details about where to deploy the various classes and files that you have created, see Custom Field Types Deployment.
How Field Rendering for Mobile Devices Differs from Field Rendering for Computers
In SharePoint Foundation, field rendering with custom field rendering controls for mobile devices is similar to field rendering with custom field rendering controls for computers. But keep these differences in mind:
Mobile pages are an entirely different set of pages from the regular pages and they reference a different set of RenderingTemplates.
Mobile RenderingTemplates are declared in MobileDefaultTemplates.ascx, not in DefaultTemplates.ascx.
Mobile field rendering controls have their own namespace, Microsoft.SharePoint.MobileControls (instead of Microsoft.SharePoint.WebControls), and they derive from classes in the ASP.NET System.Web.UI.MobileControls, instead of System.Web.UI.WebControls.
The inheritance hierarchy for mobile field rendering controls is somewhat different from that of regular field rendering controls. For example, the functions of the TemplateBasedControl and FormComponent in regular field rendering are combined in the SPMobileComponent class.
Custom field rendering controls that you create for mobile contexts rely more on the CreateChildControls method of the control to render a field, and correspondingly less on the rendering template, than is the case for custom field rendering controls that you create for computer browsers. Moreover, for custom mobile rendering controls, you rarely override the CreateChildControls method itself. Instead, you typically override one or more of four other methods that are called by CreateChildControls:
For more information about mobile page rendering and custom field rendering controls, see Mobile Page Rendering System and Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages.
See Also
Tasks
Walkthrough: Creating a Custom Field Type
Walkthrough: Creating a Custom Field Rendering Control for Mobile Pages
Concepts
How to: Create a Custom Field Class
How to: Create a Custom Field Value Class
How to: Create a Custom Field Type Definition
Custom Field Type Property Rendering
How to: Create an Editor Control for a Field Type Property
How to: Create a Field Rendering Control