Custom Multicolumn Field Classes
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.
Windows SharePoint Services 3.0 contains a class, SPFieldMultiColumn, that emulates a field containing multiple values. In actuality, the class contains a single string value, in which the values of the various "columns" are separated by special delimiter characters. The class contains members that enable you to manipulate the class as if it contained multiple columns; for example, setting the number of "columns", and setting or retrieving the individual "column" values.
Classes derived from the SPFieldMultiColumn class, by default, inherit these members. In addition, derived classes can also take advantage of the Collaborative Application Markup Language (CAML) rendering patterns defined in the SPFieldMultiColumn class field definition XML. These rendering patterns are for display and header views of multicolumn data.
Note
In Windows SharePoint Services 3.0, data for SPFieldMultiColumn fields is stored in the content database as a non-sortable SQL data type. For that reason, columns based on the SPFieldMultiColumn field type or on custom field types derived from it are not sortable. However, you can overcome this limitation by using Custom Related Fields.
For more information about field definition XML and render patterns, see Custom Field Type Definition.
Accessing Data Values For SPFieldMultiColumn Objects
The SPFieldMultiColumn class contains a class, SPFieldMultiColumnValue, which represents the actual "column" values in the SPFieldMultiColumn object. The SPFieldMultiColumnValue class includes an index that developers should use to access the value of a specific "column", rather than directly parsing the results of the SPFieldMultiColumn.ToString method.
SPFieldMultiColumnValue Class Constructors
The SPFieldMultiColumnValue class includes three constructor methods. Developers can decide which constructor to use based on the following behavior:
SPFieldMultiColumnValue() Creates a new SPFieldMultiColumnValue object, without a set number of "columns". The developer can then use the SPFieldMultiColumnValue.Add method to append any number of "columns" of data necessary onto the object.
SPFieldMultiColumnValue(Int32) Creates a new SPFieldMultiColumnValue object with the specified number of "columns." Developers can then use the Item property to get and set the value of a specific "column."
SPFieldMultiColumnValue(String) Creates a new SPFieldMultiColumnValue object, using the passed-in string argument to determine the number of "columns" and the value in each. The string argument must begin and end with the delimiter characters ";#" and it must separate each field with them as well.
For example, suppose you call this constructor, passing the following string:
";#column one value;#column two value;#column three value;#"The constructor creates a new SPFieldMultiColumnValue object with three "columns" of data. The first contains "column one value"; the second, "column two value"; and the third, "column three value".
Developers can then use the Item property to get and set the value of a specific "column".
This constructor is useful when reading the string from a database or other data source where the column values are stored with the delimiting characters already in place.
Writing Values from the SPFieldMultiColumnValue Class
Conceptually, the final SPFieldMultiColumnValue constructor performs the opposite function of the M:Microsoft.SharePoint.SPFieldMultiColumnValue.ToString method. The M:Microsoft.SharePoint.SPFieldMultiColumnValue.ToString method generates a string, complete with delimiting characters for "column" separation, from the SPFieldMultiColumnValue object. This method is useful when writing the "column" values to a database or other data source where the "column" values are stored as a string, with the delimiting characters already in place.