Field Variables

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:

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.

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

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

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.

displayCountBar

Example value: false

Versions 22.12 and later. Set to true by default, this field variable can allow you to disable the counter below the Block Editor that displays the content's character count, word count, and estimated time to read. See the the Block Editor documentation for more info.

charLimit

Example value: 5000

Versions 22.12 and later. Defines a character limit to Block Editor content. The content cannot be saved if it exceeds to configured limit. By default, Block Editors have no character limit; removing this variable likewise removes any previously set limit. See the the Block Editor documentation for more info.

customBlocks

Example value: {"extensions":[{"url":"https://local.dotcms.site/custom.js"}]}

Versions 23.03 and later. Allows the activation of custom remote extensions to the Block Editor. For more information on creating custom extensions, see the relevant section of the Block Editor documentation.

File Field

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

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

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

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:

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": "..."
}