Field Variables

Last Updated: Nov 18, 2022
documentation for the dotCMS Content Management System

Field variables provide extended options for configuring fields in dotCMS. A field variable takes the form of a key-value pair, but should not be confused with the Key/Value Field; rather, field variables are properties of all fields, capable of changing a field's behavior in important ways.

When building a Content Type in the admin panel, field variables can be accessed through each field's configuration pane under a tab of the same name:

Field variables input area in the dotCMS user interface.

To assign or retrieve a field variable headlessly, see the relevant functions of the Content Type API.

This page contains a list of all pre-defined field variables, and also briefly discusses the creation of custom variables.

Universal Field Variables

Some field variable keys can adjust any field to which they are applied. More detailed descriptions can be found below the table.

Field Variable KeyValue Type
uniquePerSiteBoolean
esCustomMappingJSON

uniquePerSite

This defaults to false when undeclared; when set to true, it alters the Unique property, causing the field value to be enforced as unique — that is, no two contentlets of this type can share the same value in this field — on a site-by-site basis, instead of globally. This can be important in a multi-site environment.

esCustomMapping

The esCustomMapping field variable allows a field to be mapped by Elasticsearch in customizable ways. It takes an Elasticsearch field mapping, expressed in JSON, as its value. Below, two simple examples of Elastic mappings that can be used as values were taken from our page on how content is mapped to Elasticsearch.

See the Elasticsearch documentation for more detailed information on Elasticsearch field mappings.

Example 1: Index as Keywords

The following mapping causes Elasticsearch to index the field as a keyword rather than as normal text, and moreover limits the size of the value stored in the index:

{
    "type": "keyword",
    "ignore_above": 8191
}

Example 2: Unstructured, Unstored, & Language-Specific

The following mapping indicates Elasticsearch should index the field as analyzed, unstructured text; that the field should not be stored; and that the Russian language text analyzer should be used:

{
    "analyzer": "russian",
    "store": "false",
    "type": "text"
}

Any Elasticsearch analyzer can be specified for the field; see Elasticsearch's documentation for a list of the built-in analyzers.

Field-Specific Variables

The following keys are grouped by the fields to which they apply.

Binary Field

Field Variable KeyValue Type
acceptComma-separated list
maxFileLengthByte count
indexMetadataFieldsComma-separated list

accept

Example value: application/pdf,image/*

Declaring the accept field variable creates a whitelist of media types, limiting what data types the Binary Field will accept as valid inputs.

maxFileLength

Example value: 1024

This number specifies the maximum file length of an upload, in bytes.

indexMetadataFields

Example value: width,contentType,author,keywords,fileSize,title

This variable limits the file asset metadata fields subject to search indexing. By default, this configuration is handled globally by the INDEX_METADATA_FIELDS property (defined in the dotmarketing-config.properties file, and overridden with the DOT_INDEX_METADATA_FIELDS environment variable). However, this variable permits a field to override the global setting.

Block Editor Field

Field Variable KeyValue Type
stylesCSS
allowedBlocksComma-separated list
contentTypesComma-separated list

styles

Example value: color:red;font-size:16px;

You can define a Block Editor's CSS styling by way of the styles field variable, by setting its value to a CSS string containing the desired properties.

allowedBlocks

Example value: heading2,heading3,paragraph,contentlets

This variable allows content architects to configure which blocks are available to content contributors in a given Block Editor. For a list of block system names, see the table on the Block Editor page.

contentTypes

Example value: Activity,Blog

Similar to whitelisting block types, it is possible to limit the available Content Types available for insertion into the Block Editor as contentlets. Assign the key contentTypes a value of a list of variables corresponding to allowed Content Types.

File Field

Field Variable KeyValue Type
defaultPathPath

defaultPath

Example value: /images/gallery/beach

Sets the default directory used by file selection dialogs. Can point to a specific host, or to a site-relative path.

Image Field

Field Variable KeyValue Type
defaultPathPath

defaultPath

Example value: /images/gallery/beach

Sets the default directory used by file selection dialogs. Can point to a specific host, or to a site-relative path.

Key/Value Field

Field Variable KeyValue Type
whiteListJSON

whiteList

Example value: { "A":["1", "2"], "B":[], "C":[] }

dotCMS supports creating a whitelist of valid keys for a given Key/Value Field, as well as pre-defined values for said keys.

The example above creates a whitelist containing the following:

  • One predefined key (A) with two possible predefined values (1 and 2)
  • Two other predefined keys (B and C) permitting arbitrary value entry

Users inputting data into this Key/Value field will find a dropdown menu in the Key position contining A, B, and C. Moreover, while A is selected, the Value field will change from a text input to a dropdown containing 1 and 2.

Relationship Field

Field Variable KeyValue Type
showFieldsComma-separated list

showFields

Example value: firstName,lastName,userId

This variable allows you to configure which related-content fields are visible as columns to users editing a contentlet containing a Relationship field.

For a visual aid, here's a screenshot taken from a Blog contentlet on dotCMS's demo site, showing the default rendering of the related Blog Author contentlet, as seen by a user making a blog post:

By setting the showFields key to the value given in the example, we observe an immediate change to the presentation of the related contentlet:

WYSIWYG Field

The WYSIWYG Field responds to the following field variables:

Field Variable KeyValue Type
defaultPathPath
dragAndDropBoolean
tinymcepropsJSON

defaultPath

Example value: /images/gallery/beach

Sets the default directory used by file selection dialogs. Can point to a specific host, or to a site-relative path.

dragAndDrop

Example value: false

This key defaults to true; this variable determines whether or not a WYSIWYG field will accept a file via drag and drop as a valid input.

tinymceprops

Example value: {menubar:false,statusbar:false,resize:false}

dotCMS uses TinyMCE as the core of its WYSIWYG field. Properties that customize TinyMCE can be passed as JSON to this key to customize your WYSIWYG field.

This configuration can also be handled at the file level; for more information, see the doc section on WYSIWYG customization. See also TinyMCE's documentation for a list of properties.

User-Defined Field Variables

In addition to the pre-defined configuration options described above, content architects can also define their own custom field variables for any other desired purpose. These can accessed through the Content Type API, or, from version 22.09 onwards, through Velocity, the getFieldVariables('fieldVar') method of a ContentMap, such as one of the built-in content objects.

An individual field variable returned by API call has the following structure:

{
    "clazz": "com.dotcms.contenttype.model.field.ImmutableFieldVariable",
    "fieldId": "...",
    "id": "...",
    "key": "...",
    "value": "..."
}

On this page