How to: Create a Custom Field Value Class
Applies to: SharePoint Foundation 2010
If you create a custom field class that requires a special data structure for the field data, and this structure is not supported by the parent field class from which you are deriving your custom field class, you can create a field value class to contain your field data.
Note
Your custom data type can be a structure — a "struct" — as well as a class; but for the sake of simplicity in instruction, the Microsoft SharePoint Foundation 2010 Software Development Kit (SDK) assumes that a class is always used.
You do not need to derive your custom field value class from any specific class. This is true even for custom field classes that derive from field classes that already have associated field value classes. For example, if you create a custom field class that inherits from the SPFieldMultiColumn class, a field value class for that custom field class does not need to inherit from the SPFieldMultiColumnValue class.
We recommend that you use this naming convention for your custom value classes:
field_type_nameFieldValue
Examples of properly named classes are TargetDateFieldValue and RegularExpressionFieldValue. (The special value classes that ship with SharePoint Foundation were created before this naming convention was determined and they follow the pattern SPFieldfield_type_nameValue such as SPFieldMultiColumnValue.)
Constructors Used With Custom Field Value Classses
A custom field value class must implement at least two constructors, and usually only two. With only rare exceptions, one has no parameters and the other takes a String parameter. The second constructor converts the String to a value of the custom type. If the custom type is complex, then String must have a structure that can be parsed.
If the class is derived from one of the SPFieldfield_type_nameValue classes, then these constructors will usually only call the base constructor. The following is an example of typical value class constructors when the value class derives from another class:
public RegularExpressionFieldValue()
: base() { }
public RegularExpressionFieldValue(string value)
: base(value) { }
Public Sub New()
MyBase.New()
End Sub
Public Sub New(ByVal value As String)
MyBase.New(value)
End Sub
In some cases you may need additional constructors. For example, if your custom type is based on an internal array field, you might want a constructor that uses an Int32 parameter to initialize the size of the array, but not any particular array members. You may also need additional parameters on your two basic constructors. For example, if your custom type's values include a context-relative component, then you may need to add an SPContext parameter or perhaps an SPWeb or SPSite parameter. See the constructors of the SPFieldfield_type_nameValue classes for examples.
Using the [Serializable] Directive
Almost any field value class declaration should have the [Serializable] directive added to it so that its objects can be serialized. This means that you should also add this directive you the declaration of your custom field value class. But do not need to do this when the object values of the class are context-relative in a way that makes it impossible to meaningfully persist and restore the object values. SPFieldLookupValue is an example of a field value class whose declaration does not use the [Serializable] directive: values of that type are always temporary.
When you mark your class with the [Serializable] directive, you should implement the ToString method to convert the field value into a string format that is used for data storage. (But you do not necessarily have to override the method when your class inherits from another field value class.)
Note
The SPFieldfield_type_nameValue classes that can be serialized and that ship with SharePoint Foundation all override the ToString method rather than implement the ISerialization class. We recommend that you follow this pattern: do not implement the ISerialization interface.
For more information about the SerializableAttribute, see SerializableAttribute.
Accessing Custom Field Values from the Custom Field Class
Custom field classes that require custom field value classes will usually need to override one or more of the methods and properties of the SPField class, especially those that read or write the custom field value objects.
Note
For most of these members, the implementation in SPField does nothing useful; for example, GetFieldValue simply returns what was passed to it, and GetValidatedString simply calls the ToString method of the value class (which does not contain any validation logic). For this reason, if your field type class is derived directly from SPField, then you must provide overrides for any of these members that you need to use for its intended purpose. We recommend that, whenever possible, you derive your custom field class from one of the classes that derive from SPField.
DefaultValue Returns, as a string, a default value that can be used for the field when a particular list item has no value in the field.
DefaultValueTyped Returns a default value that can be used for the field when a particular list item has no value in the field.
FieldValueType Returns the field value type.
GetFieldValue Converts the specified string into a field type value object. Your custom field object should return the custom field value object when the M:Microsoft.SharePoint.SPField.GetFieldValue(System.String) method is invoked. SharePoint Foundation returns this field value object when the SPListItem.this["field name"] method is called. Often an override of this method, after verifying that the String is not empty or null, only has to call the constructor of the custom field value class that takes a string parameter (see above).
GetFieldValueAsText Returns the field data value as a string.
GetFieldValueAsHtml Returns the field data value as a string, formatted as HTML. This HTML-formatted field value is most often used to render the field value directly on a page. It is used, for example, on the version history page of a list item. However, this HTML-formatted field value is not used on the Display form. Field rendering for the Display form is typically the same as rendering for list views; that is, it is rendered from the Collaborative Application Markup Language (CAML) DisplayPattern element in the field type's fldtype*.xml file.
GetValidatedString This method validates the field type value object and converts it into a serialized string. In turn, this method may use the ToString method of the field value object to convert the field value object into a string.
PreviewValueTyped Returns a preview value of field data, for a design time view of the field control in Display and Edit mode.
See Also
Tasks
Walkthrough: Creating a Custom Field Type