Field Element
The Field element defines the internal data types used in the SharePoint team Web site list infrastructure. A field is basically a column or attribute of information that a user can add to a list.
Syntax
<Field
AllowMultiVote = "TRUE" | "FALSE"
AuthoringInfo = "Text"
BaseType = "Integer" | "Text"
ColName = "Text"
Commas = "TRUE" | "FALSE"
Decimals = "Integer"
Description = "Text"
DisplayName = "Text"
DisplayNameSrcField = "Text"
Div = "Number"
Filterable = "TRUE" | "FALSE"
Format = "Text" | "Dropdown" | "RadioButtons"
FromBaseType = "TRUE" | "FALSE"
Hidden = "TRUE" | "FALSE"
JoinColName = "Text"
LCID = "Integer"
LinkType = "Hyperlink" | "Image"
List = "Text"
Max = "Number"
MaxLength = "Integer"
Min = "Number"
Mult = "Number"
Name = "Text"
NegativeFormat = "MinusSign" | "Parens"
NumLines = "Integer"
Percentage = "TRUE" | "FALSE"
PrimaryKey = "TRUE" | "FALSE"
ReadOnly = "TRUE" | "FALSE"
Required = "TRUE" | "FALSE"
ShowField = "Text" | "Choice" | "Counter"
ShowInFileDlg = "TRUE" | "FALSE"
ShowInNewForm = "TRUE" | "FALSE"
Sortable = "TRUE" | "FALSE"
StorageTZ = "UTC" | "Abstract"
StripWS = "TRUE" | "FALSE"
TextOnly = "TRUE" | "FALSE"
Type = "Data Type">
</Field>
Attributes
| Name | Description |
|---|---|
| AllowMultiVote | Optional Boolean. TRUE if multiple responses are allowed in a survey. |
| AuthoringInfo | Optional Text. A descriptive string that is displayed in the field editing pages to identify the field and its purpose (for example, the LinkTitle field has the authoring info "(link to item)"). This attribute is usually used if a field of the same name exists for another purpose. |
| BaseType | Optional. The BaseType attribute can be set to Integer, which stores values as integers, or to Text (default), which stores values as text. Note that it is illegal to create integer base-type choice fields. |
| ColName | Optional Text. An internal attribute that defines the mapping of the field to the physical storage name for this field. It needs to be a valid name in the underlying database and must exactly match the name used in the database table. If not specified, the server generates a column name that does not collide with any existing column names and that contains no illegal characters for Microsoft SQL Server. |
| Commas | Optional Boolean. TRUE if commas are used to separate thousands. |
| Decimals | Optional Integer. Determines the number of decimals to display. The value displayed is rounded up to the display precision (e.g., 1.05 is displayed as 1.1 when rounded to one decimal place). |
| Description | Optional Text. Provides the description that is shown in the edit form for a list if a field description is specified. By default, fields in SharePoint Team Services do not have descriptions. |
| DisplayName | Optional Text. The displayed name for a field. It has no restrictions as to text size, use of spaces, etc. The display name is editable by the user and can change after initial field creation. This name is used as a column heading when the field is displayed in a table view, but as a form label when the field is displayed in a form. The <FieldName/> tag returns the display name if given; otherwise, it defaults to the Name attribute. |
| DisplayNameSrcField | Optional Text. Used generally for a computed field that needs the same name as another field. If the source field is modified and the display name is changed by a user, then the display name of this field will also change. This string refers to the name of the other field. |
| Div | Optional Number. A scale factor used to divide before displaying the number. The display number is N * Mult / Div (rounded up to the number specified by Decimals). |
| Filterable | Optional Boolean. TRUE if the field can be filtered. |
| Format | Optional Text. Specifies the formatting to be used for numerical values.
For date/time fields, the following values are possible:
|
| FromBaseType | Optional Boolean. Setting this attribute for a field in the SCHEMA.XML file for a list marks the field as irremovable in the field editing page. |
| Hidden | Optional Boolean. If TRUE, the field is not shown in a Fields element enumeration and will not appear in auto-generated forms. |
| JoinColName | Optional Text. This attribute is only defined for Lookup fields. It is much like ColName, except it denotes the name of the column that is used in the SQL join between the local and foreign lists. Ordinarily, this value should not be customized. It is currently only used in the Field schema of certain built-in and base type fields to denote lookups into the URLs (DocMd) table, which is joined on the UrlID column. |
| LCID | Optional Integer.The LCID attribute can be used to specify the country/region whose currency format is being used. For example, 1033 for the United States.
Two special cases involve the Euro symbol format. If LCID = -1 (0xFFFFFFF), the Euro symbol is added as a prefix to the number. If LCID = -2 (0xFFFFFFE), the Euro symbol is added as a suffix to the number. The number of decimal digits is 2, although this can be overridden by the Decimals attribute of the field. The Euro currency symbol is equal to 0x20AC in UCS-2. |
| LinkType | Optional. The LinkType attribute can be set to Hyperlink (default), which displays the URL as a normal <A> tag, or to Image, which displays the URL as <IMG SRC=URL ALT=Description>. |
| List | Optional Text. Indicates the internal list name of the foreign list in the List of Lists database table. Stored values are the foreign keys that map to the ID field in the foreign list. |
| Max | Optional Number.Specifies the maximum value allowed for the field. |
| MaxLength | Optional Integer. Specifies the maximum number of characters allowed in a field value. Edit forms are adjusted to enforce this value, which is validated on the client. If the user attempts to enter more than the number of characters set by MaxLength, an error message appears. |
| Min | Optional Number.Specifies the minimum value allowed for the field. |
| Mult | Optional Number. A scale factor used to multiply before displaying a number. |
| Name | Optional Text. The name of a field. This is the internal name of a field and is guaranteed never to change for the lifetime of the field definition. It must be unique with respect to the set of fields in a list. The name is auto-generated based on the user-defined name for a field. |
| NegativeFormat | Optional. Specifies how to indicate negative values. Can be set to one of the following values:
|
| NumLines | Optional Integer. Recommends the number of lines (rows) to display in a TEXTAREA block during editing. This is merely a client UI hint there is no enforced limitation on the number of lines of text that can be edited. |
| Percentage | Optional Boolean. TRUE if the value is displayed as a percentage (number multiplied by 100 with a percent sign (%) appended). |
| ReadOnly | Optional Boolean. If TRUE, a read-only field cannot be updated via posting and is not presented with an editable UI in Edit-mode forms. |
| Required | Optional Boolean. If TRUE, the field must not have an empty value assigned to it. If a non-empty field value is not given in a form post, either the standard required-field text, or an explicitly specified message (i.e., via <ErrorText> tags), is displayed in the error form. This validation is handled by the client only (the database always allows NULL for all user-defined fields). |
| ShowField | Optional. The ShowField attribute can be set to the field name to display. By default, a hyperlinked text from the Title field of the record in the external list is displayed. But the ShowField attribute can be used to override that and display another field from the external list.
The following data types are allowed as targets of a ShowField attribute: Text, Choice, and Counter. |
| ShowInFileDlg | Optional Boolean. This attribute is valid only for fields within document library schemas. If FALSE, the field will not show up in the property dialog box for saving forms that appears when saving from client applications. For example, the Title field has this attribute because this is set directly in the document being saved to the document library. |
| ShowInNewForm | Optional Boolean. If FALSE, the field will not show up in a Fields enumeration when the display mode is set to New. Fields with this setting will not show up in the default New Item page for a given list. In particular, this is used to hide fields on the document library upload document page. |
| Sortable | Optional Boolean. TRUE if values in the field can be sorted. |
| StorageTZ | Specifies how date/time values are stored. When StorageTZ is set to UTC, the date/time is handled as UTC. To denote that a date/time value refers to "abstract" time, meaning that the date/time is stored in the database as entered by the user without conversion or storage of the local time zone, simply omit the StorageTZ attribute. |
| StripWS | Optional Boolean. TRUE if white space is removed from the beginning and end of field values. |
| TextOnly | Optional Boolean. If TRUE, the field can only contain Text values. |
| Type | Optional. The data type of the field. The types listed in the following table are available.
BooleanUsed to store a TRUE/FALSE value (stored in the database as 0 or 1). This field is sortable and groupable.
ChoiceAllows the user to specify a predetermined set of values that can be used to enter data into the field. The Choice and Lookup attributes are the most important fields for sorting and grouping. The BaseType and EditFormat attributes can be used for choice fields. This field is sortable and groupable. When a value is given for a choice option, then that value is used as the submitted value for the field selection. When no value is given, that choice is submitted as the text value of the choice. In all cases, the text value of the choice is what is displayed in the UI (drop-down list or radio button text). The order in which choices appear in the editing UI is always the order that items are specified within the CHOICES element.
CounterGenerally only used for the internal ID field. Its integer value is set automatically to be unique with respect to every other item in the current list. The Counter type is always read-only and cannot be set via a form post. This field is sortable but not groupable.
CurrencyAllows for a currency value to be entered. Each currency field is tied to a specific locales currency. In all other respects, it is treated like the Number field type. Use the LCID attribute to indicate a currency of a specific locale. The Decimals, Max, and Min attributes can be used for currency types. This field is sortable and groupable.
DateTimeAllows for storage of a fully qualified date or time of day. Use the Format attribute to specify date formatting, and the StorageTZ attribute to determine how date/time values are stored. This field is sortable and groupable. For Display mode, the order of date formatting derives from the regional settings (M/D/Y or D/M/Y). In Edit mode (or in New mode for Default element value), date/times are rendered in universal format: M/D/Y hh:mm am/pm.
IntegerAllows for positive or negative integer values. The Commas and NegativeFormat attributes are used to specify integer formatting.
LookupBehaves very similarly to a choice field, except that the available options come from another list rather than being a hard-coded selection of values. The List and ShowField attributes can be used for Lookup fields. This field is sortable and groupable. For sorting and grouping, use the DisplayField value (Title, by default) rather than the foreign key stored in the list.
NoteAllows users to enter multiple lines of text. This field is neither sortable nor groupable. All text is defined to be straight ASCII without HTML markup. Anything that looks like HTML markup or a URL is just quoted (e.g., Server.HTMLEncode) to look like straight text. The control for editing this format is a simple TEXTAREA block. Use the NumLines attribute to specify the number of lines to display.
NumberAllows for a floating point number to be entered. This field is sortable and groupable. Numbers entered are parsed according to the current locale settings for decimal points and thousand separators. Negative numbers can be indicated by wrapping them in parentheses or by using a negative symbol.The following attributes can be used in conjunction with the Number attribute in order to specify number formatting: Decimals, Div, Max, Min, Mult, Percentage.
TextA single line of text entered in an edit box. This field is sortable and groupable. Use the MaxLength attribute to set a maximum number of characters allowed.
ThreadingThe Threading field type is used in the creation and display of threaded discussion-like views. Any list can contain a threading column, but a special UI is generated when it is used (it is never displayed as a standard editable field in a form nor as a normal column in a view). If a sort is performed on a threading field, a pre-order traversal of all the records in a parent-child relationship is returned. This is accomplished by saving the concatenation of the creation date and ID number of all the parent records of a particular record.
URLUsed to create a freeform hyperlink.A URL field is displayed as
<A HREF="URL">Description</A>. If no description is given, it is displayed as <A HREF="URL">URL</A>.The URL text is itself stored in the URLs (DocMd) table, which stores all the URLs in SharePoint databases on the server. This is done so that any URLs that are local on the server can be updated via link fix-up when their destination moves.When a record with a URL field contained within it is deleted, the corresponding referenced record from the URL table is also deleted.This field is sortable and groupable (the sort is defined according to the textual description rather than the contents of the URL if no description is given, it sorts the same as blank). When Type is URL, the LinkType attribute can be used to specify the type of link.
|
| Boolean | Used to store a TRUE/FALSE value (stored in the database as 0 or 1). This field is sortable and groupable. |
| Choice | Allows the user to specify a predetermined set of values that can be used to enter data into the field. The Choice and Lookup attributes are the most important fields for sorting and grouping. The BaseType and EditFormat attributes can be used for choice fields. This field is sortable and groupable. When a value is given for a choice option, then that value is used as the submitted value for the field selection. When no value is given, that choice is submitted as the text value of the choice. In all cases, the text value of the choice is what is displayed in the UI (drop-down list or radio button text). The order in which choices appear in the editing UI is always the order that items are specified within the CHOICES element. |
| Counter | Generally only used for the internal ID field. Its integer value is set automatically to be unique with respect to every other item in the current list. The Counter type is always read-only and cannot be set via a form post. This field is sortable but not groupable. |
| Currency | Allows for a currency value to be entered. Each currency field is tied to a specific locales currency. In all other respects, it is treated like the Number field type. Use the LCID attribute to indicate a currency of a specific locale. The Decimals, Max, and Min attributes can be used for currency types. This field is sortable and groupable. |
| DateTime | Allows for storage of a fully qualified date or time of day. Use the Format attribute to specify date formatting, and the StorageTZ attribute to determine how date/time values are stored. This field is sortable and groupable. For Display mode, the order of date formatting derives from the regional settings (M/D/Y or D/M/Y). In Edit mode (or in New mode for Default element value), date/times are rendered in universal format: M/D/Y hh:mm am/pm. |
| Integer | Allows for positive or negative integer values. The Commas and NegativeFormat attributes are used to specify integer formatting. |
| Lookup | Behaves very similarly to a choice field, except that the available options come from another list rather than being a hard-coded selection of values. The List and ShowField attributes can be used for Lookup fields. This field is sortable and groupable. For sorting and grouping, use the DisplayField value (Title, by default) rather than the foreign key stored in the list. |
| Note | Allows users to enter multiple lines of text. This field is neither sortable nor groupable. All text is defined to be straight ASCII without HTML markup. Anything that looks like HTML markup or a URL is just quoted (e.g., Server.HTMLEncode) to look like straight text. The control for editing this format is a simple TEXTAREA block. Use the NumLines attribute to specify the number of lines to display. |
| Number | Allows for a floating point number to be entered. This field is sortable and groupable. Numbers entered are parsed according to the current locale settings for decimal points and thousand separators. Negative numbers can be indicated by wrapping them in parentheses or by using a negative symbol.The following attributes can be used in conjunction with the Number attribute in order to specify number formatting: Decimals, Div, Max, Min, Mult, Percentage. |
| Text | A single line of text entered in an edit box. This field is sortable and groupable. Use the MaxLength attribute to set a maximum number of characters allowed. |
| Threading | The Threading field type is used in the creation and display of threaded discussion-like views. Any list can contain a threading column, but a special UI is generated when it is used (it is never displayed as a standard editable field in a form nor as a normal column in a view). If a sort is performed on a threading field, a pre-order traversal of all the records in a parent-child relationship is returned. This is accomplished by saving the concatenation of the creation date and ID number of all the parent records of a particular record. |
| URL | Used to create a freeform hyperlink.A URL field is displayed as <A HREF="URL">Description</A>. If no description is given, it is displayed as <A HREF="URL">URL</A>.The URL text is itself stored in the URLs (DocMd) table, which stores all the URLs in SharePoint databases on the server. This is done so that any URLs that are local on the server can be updated via link fix-up when their destination moves.When a record with a URL field contained within it is deleted, the corresponding referenced record from the URL table is also deleted.This field is sortable and groupable (the sort is defined according to the textual description rather than the contents of the URL if no description is given, it sorts the same as blank). When Type is URL, the LinkType attribute can be used to specify the type of link. |
Related Elements
| Parent Elements | Child Elements |
|---|---|
| Case, Default, Expr, Expr2, Fields, ListFormBody, ListFormButtons, ListFormOpening, Row, SetVar, ViewBody | CHOICES, Default, DisplayPattern, FieldRefs |
Remarks
Fields can be referenced from View definitions as well as from expressions stored in pages (via CAML) and in computed field rendering elements. The syntax for referencing a field is <Field Name="FieldName"/>.
By default, the field is rendered with the default attributes for that field definition as specified in the table above. Any of the field attributes can be overridden in the CAML markup of the FieldRef attribute, which will override the definition given for the field itself (the Type attribute cannot be changed for a field).
<Property Select="DisplayName"/> can be used to display the user-defined display name of a field.
Within a Fields element enumeration, the Name attribute can be omitted. The code <ows:Property Select=DisplayName/>: <ows:Field/> will produce a string with the user name of a field, followed by a colon, space, and the value (or edit control, depending on the current display mode).
For some field references, the raw data stored for the field can be accessed by using <Column/>.
Some properties of fields from forms and from certain aspects of the authoring UI can be rendered through the Property element, for example, <Property Select=Description/> or <Property Select=Type/>. These elements simply retrieve the value of any field attribute or child element (Property) by name.
In addition to the preceding types, the following predefined fields are used with the Field element.
| Name | Description |
|---|---|
| Created | A DateTime field specifying the time that the item was created (in UTC). |
| CreatedBy | A Lookup field on the People table indicating the user that created the item. |
| Edit | A computed field (with no additional schema) that contains a hyperlink to the edit form for an item. This field references the edit form page for the item and the ID field to identify it. |
| ID | The ID field is a Counter field type that is associated with every item in every list. The ID uniquely identifies the list item in URLs and in POST forms when editing. A value of New for an ID field in the Cmd=Save verb will create a new item rather than edit a current item. |
| Modified | A DateTime field specifying the time that the item was last modified (in UTC). The Modified time is used as a sort of Version field as well. The last modification date of an item is always posted when an existing item is being edited. If it does not match the current modification date, the server fails the edit and returns an error to the user, providing a link to the current data on the server (which opens in a new window) so that posted values can be copied from the old form into the new one. |
| ModifiedBy | A Lookup field on the People table indicating the user that last modified the item. |
| Title | The generic display name of every item. It may have a different display name in different lists, but the same internal field name of Title. The Title is the default text to display for Lookup fields to lists. |
| LinkTitle | A computed field that displays hyperlinks to items, containing the title texts and generating URLs (and new icon references) to the items. There is no additional storage for this field; it relies on the ID and Title fields for rendering of its UI. |
Note The fields returned in a Fields enumeration are affected by the display mode. Fields that are marked with the Hidden attribute are never returned. Fields that are marked with the ReadOnly attribute are not returned if a form is being rendered (in other words, if Fields is called from within a ListForm element). Fields that are marked with the ShowInNewForm attribute are not returned in the NEW or PREVIEWNEW display modes. Fields marked with the ShowInFileDlg attribute are not returned when rendering the NewForm dialog form.
Example
This example uses the Field element to specify options for the Area list.
<Field Type="Choice" BaseType="Text" Name="Area">
<CHOICES>
<CHOICE>Views</CHOICE>
<CHOICE>Site Design</CHOICE>
<CHOICE>Layouts</CHOICE>
<CHOICE>Schema Design</CHOICE>
<CHOICE>Fields</CHOICE>
<CHOICE>Forms</CHOICE>
<CHOICE>Projects</CHOICE>
<CHOICE>Inter-Team Issues</CHOICE>
<CHOICE>Schedule</CHOICE>
<CHOICE>Spec</CHOICE>
<CHOICE>Headcount</CHOICE>
<CHOICE>Misc</CHOICE>
</CHOICES>
</Field>