FieldRef Element (ContentType)

Applies to: SharePoint 2016 | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

Specifies a column to reference in this content type.

Definition

<FieldRef
  Aggregation="sum" | "count" | "average" | "min" | "max" | "merge" | "plaintext" | "first" | "last"
  Customization="Text"
  DefaultValue="Text"
  Description="Text"
  DisplayName="Text"
  Format="Text"
  Filterable="TRUE" | "FALSE"
  FilterableNoRecurrence="TRUE" | "FALSE"
  FromBaseType="TRUE" | "FALSE"
  Hidden="TRUE" | "FALSE" | "orResource"
  ID="Text"
  Locked="TRUE" | "FALSE"
  Name="Text"
  Node="Text"
  NumLines="Integer"
  PIAttribute="Text"
  PITarget="Text"
  PrimaryPIAttribute="Text"
  PrimaryPITarge="Text"
  ReadOnly="TRUE" | "FALSE"
  ReadOnlyClient="TRUE" | "FALSE"
  Required="TRUE" | "FALSE"
  Sealed="TRUE" | "FALSE"
  ShowInDisplayForm="TRUE" | "FALSE"
  ShowInEditForm="TRUE" | "FALSE"
  ShowInFileDlg="TRUE" | "FALSE"
  ShowInListSettings="TRUE" | "FALSE"
  ShowInNewForm="TRUE" | "FALSE"
  Sortable="TRUE" | "FALSE">
</FieldRef>

Elements and attributes

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute Description
Aggregation

If you use the Node attribute to specify an XPath expression that returns a collection of values, you can also include an Aggregation attribute that specifies the action to take on the value set that is returned.

This action can be either an aggregation function or an indication of the particular element within the collection.

Possible values include the following:

  • sum

  • count

  • average

  • min

  • max

  • merge

  • plaintext   Converts node text content into plain text.

  • first   Applies property promotion and demotion to the first element in the collection.

  • last   Applies property promotion and demotion to the last element in the collection.

For more information about how the Node, PIAttribute, PITarget, PrimaryPIAttribute, and PrimaryPITarget attributes are used for property promotion and demotion in XML documents, see Using Content Types to Specify XML Document Properties.

Customization

Optional Text. A string in Collaborative Application Markup Language (CAML) that defines custom field properties.

DefaultValue

Obsolete.

Description

Optional Text. Provides the description that is shown in the edit form for a list if a column description is specified. By default, columns in SharePoint Foundation do not have descriptions.

DisplayName

Required Text. The displayed name for the column. Maximum length is 255 characters.

The value of this attribute is used as a column heading when the field is displayed in a table view and as a form label when the field is displayed in a form. You use the DisplayName attribute to change the display name to a value that is different from the name that is defined on the field itself.

Format

Optional Text. Specifies the formatting to be used for numerical values.

For date/time columns, the following values are possible:

  • DateOnly   Only display (and allow edits to) the date portion (the time portion is set to 12:00 A.M. for all edited values).

  • DateTime   Display and edit both date and time of day (default).

  • ISO8601   Display date and time in ISO8601 time format converted to UTC: YYYY-MM-DDTHH:MM:SSZ.

    This is the format used for document properties in the Microsoft Office system, as well as for the standard interchange format used in Microsoft SharePoint Foundation between New and Edit forms and the server.

  • ISO8601Basic   Use the abbreviated form of 8601 date/time formats: YYYYMMDDTHHMMSSZ.

    This is the format used for vCard/iCal.

For Choice fields, this attribute can be set to Dropdown (default), which provides editing options through a drop-down selection, or to RadioButtons, which provides options through a group of radio buttons.

For URL fields, this 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">.

Filterable

Optional Boolean. TRUE to define the column as filterable.

FilterableNoRecurrence

Optional Boolean. TRUE to define the column as filterable with no recurring values.

FromBaseType

Optional Boolean. This attribute has been deprecated in favor of the Sealed attribute.

Hidden

Optional Boolean. If TRUE, the field is completely hidden from the user interface. Setting ReadOnly to TRUE means the field is not displayed in New or Edit forms but can still be included in views.

If you do not include this attribute, SharePoint Foundation treats the column as if the attribute was set to FALSE.

ID

Required Text. Specifies the field ID of the column that this FieldRef element references. The field ID is the string representation of a GUID, including braces. The value is case sensitive.

You can find the IDs for built-in fields in the file fieldswss.xml located on the following path:
%ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\FEATURES\fields

Locked Obsolete.
Name

Required Text. The name of a column. This is the internal name of a column 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.

Node

Optional Text. Specifies the XML node in the document which contains the column value. Used for property promotion and demotion in XML documents.

For more information about how the Node, PIAttribute, PITarget, Primary PIAttribute, and PrimaryPITarget attributes are used for property promotion and demotion in XML documents, see Using Content Types to Specify XML Document Properties.

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.

PIAttribute Optional Text. Specifies the attribute in the document processing instruction (specified by the PITarget attribute) to use as the column value. Used for property promotion and demotion in XML documents.

If you specify the PIAttribute attribute, you must also specify the PITarget attribute.

For more information about how the Node, PIAttribute, PITarget, Primary PIAttribute, and PrimaryPITarget attributes are used for property promotion and demotion in XML documents, see Using Content Types to Specify XML Document Properties.

PITarget

Optional Text. Specifies the document processing instruction in which the column value is stored in documents of this content type. Used for property promotion and demotion in XML documents.

If you specify the PIAttribute attribute, you must also specify the PITarget attribute.

For more information about how the Node, PIAttribute, PITarget, Primary PIAttribute, and PrimaryPITarget attributes are used for property promotion and demotion in XML documents, see Using Content Types to Specify XML Document Properties.

PrimaryPIAttribute

Optional Text. Specifies an alternate attribute in the document processing instruction, specified by the PrimaryPITarget, to use as the column value.

If you specify the PrimaryPIAttribute attribute, you must also specify the PrimaryPITarget attribute. If specified, SharePoint Foundation uses these values before those specified in the PITarget and PIAttribute attributes.

Used for property promotion and demotion in XML documents.

For more information about how the Node, PIAttribute, PITarget, Primary PIAttribute, and PrimaryPITarget attributes are used for property promotion and demotion in XML documents, see Using Content Types to Specify XML Document Properties.

PrimaryPITarget

Optional Text. Specifies an alternative document processing instruction in which the column value is stored for documents of this content type.

If you specify the PrimaryPIAttribute attribute, you must also specify the PrimaryPITarget attribute. If specified, SharePoint Foundation uses these values before those specified in the PITarget and PIAttribute attributes.

For more information about how the Node, PIAttribute, PITarget, Primary PIAttribute, and PrimaryPITarget attributes are used for property promotion and demotion in XML documents, see Using Content Types to Specify XML Document Properties.

ReadOnly

Optional Boolean. If TRUE, the field is not displayed in New or Edit forms but can be included in views. Setting the Hidden attribute to TRUE completely hides the field from the UI.

If you do not include this attribute, SharePoint Foundation treats the column as if the attribute was set to FALSE.

Required

Required Boolean. If TRUE, the field must have value assigned to it before an item that is created using this content type can be saved.

If an empty field value is given in a form post, either the standard required-field text or an explicitly specified message (that is, 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).

Sealed

Optional Boolean. TRUE to define the column as sealed. You cannot edit sealed columns through the SharePoint Foundation user interface or object model.If you do not include this attribute, SharePoint Foundation treats the column as if the attribute was set to FALSE.

ShowInDisplayForm

Optional Boolean. TRUE to display the column on the Display form for items of this content type.

ShowInEditForm

Optional Boolean. TRUE to display the field on the Edit Item page.

ShowinFileDlg

Optional Boolean. TRUE to display the column in the file dialog box for items of this content type.

ShowInListSettings

Optional Boolean. If FALSE, the field does not show up in a Fields enumeration when the display mode is set to New. Fields with this setting do not show up in the default New Item page for a given list.

ShowInNewForm

Optional Boolean. TRUE to display the column on the New form for items of this content type.

Sortable

Optional Boolean. TRUE if values in the field can be sorted.

Child elements

None

Parent elements

Occurrence

  • Minimum: 0
  • Maximum: No limit

Remarks

The FieldRef element is a reference to a column defined elsewhere, either at the site or list level. In the field reference, you can override a subset of the column properties, such as the following:

  • Display name
  • XML promotion and demotion attributes
  • Whether the field is read-only, required, or hidden

Changing these properties in the field reference changes them only as they apply to the specific content type that contains the field reference.

Important

The ID, Name, DisplayName, and Required attributes are always required, even when the FieldRef element references a field that is defined in the same element manifest.

Example

The following example shows two FieldRef elements specifying columns to include in a content type.

<FieldRefs>
  <!--  Built-in Title field -->
  <FieldRef ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}" Name="Title" DisplayName="Item" Required="TRUE" Sealed="TRUE"/>
  <!--  Custom CostCenter field -->
  <FieldRef ID="{943E7530-5E2B-4C02-8259-CCD93A9ECB18}" Name="CostCenter" DisplayName="Department" Required="TRUE"/>
</FieldRefs>

See also