The Reference field is used for defining references to other content. When a content holds references pointing to other content (for example a group references users in its Members field) it is done using a Reference field.
The following applies to the behavior of the Field:
- number of references: a Reference field can be configured to hold either a single or multiple references.
- default value: one or more default references can be set via Field configuration.
- types of referable content: types of referable content can be restricted.
- location of referable content: location of referable content can be restricted.
- set of referable content: set of referable content can be defined with an optional query.
- moving/renaming references: when a referenced content is moved to another place or renamed it does not break the connection - the moved/renamed content is still visible in the Reference Field of the main content (this is because references are connected by content id, not path).
- permission handling: if the current user does not have see permissions to one of the references, that reference is not visible for the user.
- copying content with references: when a content with a Reference Field is copied, the newly created content will hold the same references as the source content. Copying source content references along with the source content does not affect this behavior, the newly created content will hold references to the originally referenced content and not the newly created copies.
- short name: Reference
Usage in CTD:
<Field name="Manager" type="Reference">...</Field>
The following properties can be set in the field's field setting configuration:
- AllowMultiple: a boolean property defining whether multiple references are allowed or only a single content can be referenced. By default only a single reference is allowed.
- AllowedTypes: allowed content types can be defined by explicitly listing type names in Type xml elements. By default all content types can be referenced.
- SelectionRoot: allowed location of referable content can be defined by listing paths in Path xml elements. By default content can be referenced from under /Root
- DefaultValue: a default single content reference can be defined with its path. Default multiple references can be defined with a comma separated list. By default the Field contains no references.
Fully featured example:
<Field name="MyReferenceField" type="Reference"><DisplayName>My reference field</DisplayName><Description>Referenced content</Description><Configuration><AllowMultiple>true</AllowMultiple><AllowedTypes><Type>Folder</Type><Type>File</Type></AllowedTypes><SelectionRoot><Path>/Root/System</Path><Path>/Root/Sites</Path></SelectionRoot><DefaultValue>/Root/System/SystemPlugins,/Root/System/Schema</DefaultValue></Configuration></Field>
The above example configures the Reference Field so that:
- multiple references can be added
- only File and Folder content types can be added as references
- content can only be referenced from under /Root/System and /Root/Sites
- by default /Root/System/SystemPlugins and /Root/System/Schema is referenced
React field controls
Reference field can be displayed with multiple controls depending on number or type of referenced items. For single reference fields or for user references the suggested control is Autocomplete and for multiple reference fields we suggest to use ReferenceGrid (TagsInput is also available, but not usable without a custom control mapper that overrides the default one). On how to use them, see the related docs