Custom Field Type Definition
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.
A field type definition is an XML file named on the pattern fldtypes*.xml that is deployed to the C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\XML. The field types that ship with Windows SharePoint Services 3.0 are located in the FLDTYPES.XML file. A field definition file contains the information that Windows SharePoint Services needs to correctly render the field, including its column header, on a list view page (such as AllItems.aspx). It also typically provides information used to render the field on the view list item page (such as DispForm.aspx). The name and description of the field type, as it appears on such UI pages as the Customize [list] page, the New Site Column, and the Create Column pages, is also configured in the field type definition. Most importantly, the definition contains information about the assembly that contains the compiled field type.
Most field type properties are required by virtually any field type, such as the name and description properties. But a field type definition can also declare and define special properties of the field type that are relevant only to columns made from fields of that particular type. These are called variable field type properties. The values of these properties are set whenever a column is created based on the field type.
In order to recognize a custom field type, Windows SharePoint Services 3.0 must have a field type definition in a fldtypes*.xml file. You create these files in Microsoft Visual Studio as part of a custom field type project. For example, if you had a field type definition for a field type that defined an American Social Security number, you might name the XML file fldtypes_ssn_MyCompany.xml.
Note
We recommend that you follow a systematic naming pattern and include your company name so that your field definitions in the ... \XML directory can be distinguished easily from those of other solution providers. It is possible to have more than one field definition in the same file (as in the example below) and this can be a sensible policy when you have several field types that you know will always be deployed together. But for the sake of simplicity in instructions, the Windows SharePoint Services 3.0 SDK generally assumes that there is just one custom field type in each custom fldtypes*.xml. The FLDTYPES.XML that ships with Windows SharePoint Services 3.0 has many field type definitions. Modifying that file is not supported.
The following is a list of the elements included the field type definition. Click the element name for detailed information about that element.
The top level container element for the fldtypes*.xml file. |
|
The top level container element for a field type definition. |
|
An element that represents a single characteristic of the field type. |
|
An element that defines variable field type properties. |
|
The top-level container element within a PropertySchema element. |
|
An element that represents a variable property of a custom field type that is set when a column based on the field type is created. |
|
An element that represents the default value of a property of a custom field type. |
|
An element that defines how the field is rendered in certain circumstances. |
Field Types Definition Example
The following example defines two custom field types.
<?xml version="1.0" encoding="utf-8" ?>
<FieldTypes>
<FieldType>
<Field Name="TypeName">SocialSecurityNumber</Field>
<Field Name="ParentType">Text</Field>
<Field Name="TypeDisplayName">Social Security Number</Field>
<Field Name="TypeShortDescription">Social Security Number (123456789, 123-45-6789)
</Field>
<Field Name="AllowBaseTypeRendering">TRUE</Field>
<Field Name="FieldTypeClass">
AdventureWorks.FieldTypes.SSNField, AdventureWorks.FieldTypes,
Version=1.0.0.0,Culture=neutral,PublicKeyToken=90734cc53324b79c
</Field>
<RenderPattern Name="DisplayPattern">
<Column HTMLEncode="TRUE" />
<Column HTMLEncode="TRUE" UseRelatedField="TRUE"/>
</RenderPattern>
</FieldType>
<FieldType>
<Field Name="TypeName">USAddress</Field>
<Field Name="ParentType">MultiColumn</Field>
<Field Name="TypeDisplayName">US Address</Field>
<Field Name="TypeShortDescription">US Address(12345 NE 123 St. Redmond, WA 98052)
</Field>
<Field Name="UserCreatable">TRUE</Field>
<Field Name="FieldTypeClass">
AdventureWorks.FieldTypes.USAddressField, AdventureWorks.FieldTypes,
Version=1.0.0.0,Culture=neutral,PublicKeyToken=90734cc53324b79c
</Field>
<PropertySchema>
<Fields>
<Field Name="DefaultCity" DisplayName="Default City"
MaxLength="50" DisplaySize="15" Type="Text">
<Default>Redmond</Default>
</Field>
<Field Name="DefaultState" DisplayName="Default State"
MaxLength="2" DisplaySize="2" Type="Text">
<Default>WA</Default>
</Field>
<Field Name="DefaultZip" DisplayName="Default Zip" MaxLength="5"
DisplaySize="5" Type="Text">
<Default>98052</Default>
</Field>
</Fields>
</PropertySchema>
<RenderPattern Name="DisplayPattern">
<Switch>
<Expr><Column/></Expr>
<Case Value="">
</Case>
<Default>
<Column SubColumnNumber="0" HTMLEncode="TRUE"/>
<HTML><![CDATA[<BR>]]></HTML>
<Column SubColumnNumber="1" HTMLEncode="TRUE"/>
<HTML><![CDATA[, ]]></HTML>
<Column SubColumnNumber="2" HTMLEncode="TRUE"/>
<HTML><![CDATA[ ]]></HTML>
<Column SubColumnNumber="3" HTMLEncode="TRUE"/>
</Default>
</Switch>
</RenderPattern>
</FieldType>
</FieldTypes>
Field Type Definitions in the Object Model
After you deploy a field type solution, you can access the field type definition in the Windows SharePoint Services 3.0 object model as an SPFieldTypeDefinition object. Most of the settings you define in the field type definition XML are represented as read-only members of the SPFieldTypeDefinition class. Most of the properties of this class have the same name as the corresponding setting in the fldtypes*.xml file. See Field Element (Field Types) for details of the exceptions.
The RenderPattern element is not accessible through SPFieldTypeDefinition. The PropertySchema element is readable in the PropertySchema property as an XML string.
See Also
Tasks
Walkthrough: Creating a Custom Field Type