Contao Developer Documentation > Reference > Data Container Array > Fields

Fields

The fields key of the DCA defines the columns of a table. Depending on these settings, the Contao core engine decides which type of form field to load, whether a user is allowed to access a certain field and whether a field can be used as sort or filter criteria.

Example

// contao/dca/tl_example.php
$GLOBALS['TL_DCA']['tl_example']['fields']['myfield'] = [
    'label' => &$GLOBALS['TL_LANG']['tl_example']['myfield'],
    'exclude' => true,
    'inputType' => 'text',
    'eval' => ['tl_class'=>'w50', 'maxlength'=>255],
    'sql' => "varchar(255) NOT NULL default ''",
];

Reference

Key	Value	Description
label	`&$GLOBALS['TL_LANG']` (`array`)	Field label. Typically a reference to the global language array. Needs to be an array containing two elements: the field’s label and its description.¹
default	Default value (`mixed`)	Default value that is set when a new record is created.
exclude	true/false (`bool`)	If true the field will be excluded for non-admins. It can be enabled in the user group module (allowed excluded fields).
toggle	true/false (`bool`)	since 4.13 If true the field can be used to trigger the `toggle` action.
search	true/false (`bool`)	If true the field will be included in the search menu (see “sorting records” -> “panelLayout”).
sorting	true/false (`bool`)	If true the field will be included in the sorting menu (see “sorting records” -> “panelLayout”).
filter	true/false (`bool`)	If true the field will be included in the filter menu (see “sorting records” -> “panelLayout”).
flag	Sorting mode (`integer`)	1 Sort by initial letter ascending 2 Sort by initial letter descending 3 Sort by initial X letters ascending (see length) 4 Sort by initial X letters descending (see length) 5 Sort by day ascending 6 Sort by day descending 7 Sort by month ascending 8 Sort by month descending 9 Sort by year ascending 10 Sort by year descending 11 Sort ascending 12 Sort descending Note: flags 5 through 10 will also enable formatting of timestamps in the back end when used as a label somewhere.
length	Sorting length (`integer`)	Allows to specify the number of characters that are used to build sorting groups (flag 3 and 4).
inputType	Field type (`string`)	`checkbox` Checkbox `checkboxWizard` Checkbox Wizard `chmod` CHMOD table `fileTree` File tree `imageSize` Two text fields with drop-down menu (creates an Image Size Array) `inputUnit` Text field with small unit drop-down menu `keyValueWizard` Key » Value wizard `listWizard` List wizard `metaWizard` Used for setting meta information in the file manager `moduleWizard` Module wizard `optionWizard` Option wizard `pageTree` Page tree `password` Password field `picker` General purpose picker `radio` Radio button `radioTable` Table with images and radio buttons `sectionWizard` Used for defining sections in the page layout `select` Drop-down menu `serpPreview` Search Engine Result Preview (SERP) widget `tableWizard` Table wizard `text` Text field `textStore` Text field that will not display its current value `textarea` Textarea `timePeriod` Text field with drop-down menu `trbl` Four text fields with a small unit drop-down menu
options	Options (`array`)	Options of a drop-down menu or radio button menu. Specify as `['opt1', 'opt2', 'opt3']` or `['value1' => 'label1', 'value2' => 'label2']`. Special case ambiguous numerical value/index: `[0 => 'label1', 1 => 'label2']` or `['0' => 'label1', '1' => 'label2']`: If option values are integers and starting with 0, the label will also be used as value. Use the eval option `isAssociative` to prevent this.
options_callback	Callback function (`array`)	Callback function that returns an array of options. Please specify as `['Class', 'Method']`.
foreignKey	table.field (`string`)	Get options from a database table. Returns ID as key and the field you specify as value. The field can be a complete SQL expression, e.g.: `tl_member.CONCAT(firstname,' ',lastname)`
reference	`&$GLOBALS['TL_LANG']` (`array`)	Array that holds the options labels. Typically a reference to the global language array.
explanation	Array key (`string`)	Array key that holds the explanation. This is a reference to the `XPL` category of the `explain` translation domain. See more information below.
input_field_callback	Callback function (`array`)	Executes a custom function instead of using the default input field routine and passes the the DataContainer object and the label as arguments.
eval	Field configuration (`array`)	Various configuration options. See next paragraph.
wizard	Callback functions (`array`)	Call a custom function and add its return value to the input field. Please specify each callback as `['Class', 'Method']`.
sql	Database field definition (`string` or `array`)	Describes data type and its database configuration. (see paragraph SQL Column Definition).
relation	Configuration of relations (`array`)	Describes relation to parent table (see paragraph Relations).
load_callback	Callback functions (`array`)	These functions will be called when the field is loaded. Please specify each callback function as `['Class', 'Method']`. Passes the field’s value and the data container as arguments. Expects the field value as return value.
save_callback	Callback functions (`array`)	These functions will be called when the field is saved. Please specify each callback function as `['Class', 'Method']`. Passes the field’s value and the data container as arguments. Expects the field value as return value. Throw an exception to display an error message.
xlabel	Callback functions (`array`)	These functions will be called when the widget is rendered and allows you to add additional html after the field label. Please specify each callback function as `['Class', 'Method']`.

¹ Since Contao 4.9, defining a label for a DCA field is optional. If no label is defined, Contao will automatically look for a translation in tl_example.field_name, e.g. $GLOBALS['TL_LANG']['tl_example']['field_name'].

Explanation

Explanations are used together with the helpwizard eval setting. The latter will show the help wizard icon and the help wizard itself will show the explanation. explanation is a configuration value holding a simple string. It is a reference to the $GLOBALS['TL_LANG']['XPL'] translation array, i.e. a reference into the XPL category of the explain translation domain.

The explanation itself can be defined in two ways: either as a single string:

// contao/languages/en/explain.php
$GLOBALS['TL_LANG']['XPL']['example'] = 'Content for the help wizard.';

or as a multi dimensonal array representing an explanation table:

// contao/languages/en/explain.php
$GLOBALS['TL_LANG']['XPL']['example'] = [
    ['First row header', 'First row content.'],
    ['Second row header', 'Second row content.'],
];

Show full example

Evaluation

The evaluation array (eval) configures a particular field in detail. You can e.g. create mandatory fields, add a date picker or define the rows and columns of a textarea. You can also modify the field appearance or enable data encryption. Each field can be validated against a regular expression.

Key	Value	Description
addWizardClass	true/false (`bool`)	Whether or not to add the `wizard` CSS class for the widget if a wizard icon is in use. Default: `true`. Note: this setting does not exist anymore in Contao 4.12 and up.
allowHtml	true/false (`bool`)	If true the current field will accept HTML input (see “Allowed HTML tags” in the back end System => Settings).
alwaysSave	true/false (`bool`)	If true the field will always be saved, even if its value has not changed. This can be useful in conjunction with a load_callback.
blankOptionLabel	Label (`string`)	Label for the blank option (defaults to `-`).
chosen	true/false (`bool`)	Native selects enhanced with Chosen.
collapseUncheckedGroups	true/false (`bool`)	This feature is available in Contao 4.13 and later. If true all option groups without at least one checked option will be collapsed. The first group of options will not be collapsed if there are no options selected at all. Applies to checkbox widgets with a nested array of options only.
colorpicker	true/false (`bool`)	If true the current field will have a mooRainbow color picker.
cols	Columns (`integer`)	Number of columns (used for `textarea`, `radioTable` and `tableWizard` fields).
csv	Delimiter (`string`)	The choice of this field will not be stored as serialized string but rather as given delimiter-separated list. Example: `'eval' => ['csv'=>',']`
customRgxp	Regular expression (`string`)	This feature is available in Contao 4.11 and later. Custom regular expression to be used when using `'rgxp' => 'custom'`
customTpl	Filename (`string`)	Use own template for this input field `'customTpl' => 'template-file-name'`
datepicker	true/false (`bool`)	If true the current field will have a MooTools-DatePicker.
dcaPicker	true/false (`bool`)	If true the general purpose picker will be shown. Allows to pick different records from the system and return them as an insert tag.
decodeEntities	true/false (`bool`)	If true HTML entities will be decoded. Note that HTML entities are always decoded if allowHtml is true.
disabled	true/false (`bool`)	Disables the field (not supported by all field types).
doNotCopy	true/false (`bool`)	If true the current field will not be duplicated if the record is duplicated.
doNotSaveEmpty	true/false (`bool`)	If true the field will not be saved if it is empty.
doNotShow	true/false (`bool`)	If true the current field will not be shown in “edit all” or “show details” mode.
doNotTrim	true/false (`bool`)	If true the whitespace of the input of this field will not be trimmed before saving.
encrypt	true/false (`bool`)	If true the field value will be stored encrypted.
extensions	File extensions (`string`)	Limits the file tree to certain file types (comma separated list). Applies to file trees only.
fallback	true/false (`bool`)	If true the field can only be assigned once per table.
feEditable	true/false (`bool`)	If true the current field can be edited in the front end. Applies to table `tl_member` only.
feGroup	Group name (`string`)	personal personal data address address details contact contact details login login details (table `tl_member` only) You can also define your own groups.
feViewable	true/false (`bool`)	If true the current field is viewable in the member listing module.
fieldType	Input field type (`string`)	checkbox allow multiple selections radio allow a single selection only Applies to file and page trees only.
files	true/false (`bool`)	If true files and folders will be shown. If false, only folders will be shown. Applies to file trees only.
filesOnly	true/false (`bool`)	Removes the radio buttons or checkboxes next to folders. Applies to file trees only.
findInSet	true/false (`bool`)	Sort by the actual option values instead of their labels.
helpwizard	true/false (`bool`)	If true the helpwizard icon will appear next to the field label.
hideInput	true/false (`bool`)	If true the field value will be hidden (it is still visible in the page source though!).
includeBlankOption	true/false (`bool`)	If true a blank option will be added to the options array. Applies to drop-down menus only.
isAssociative	true/false (`boolean`)	Indicates that an array of options is indeed an associative array. Example of an ambiguous array of options: `['0' => 'Zero', '1' => 'One']`.
isBoolean	true/false (`bool`)	Indicates that a particular field is boolean.
isGallery	true/false (`bool`)	Displays selected files of a `fileTree` widget as an image gallery.
isHexColor	true/false (`bool`)	Defines the input as being a color definition in Hex notation. Invalid characters will automatically be removed.
isSortable	true/false (`bool`)	This feature is available in Contao 4.10 and later. Enable sorting for the selected items. Applies to file trees and pickers.
mandatory	true/false (`bool`)	If true the field cannot be empty.
maxlength	Maximum length (`integer`)	Maximum number of characters that is allowed in the current field.
maxval	Maximum value (`integer`)	Maximum number value to be checked (upper bound).
metaFields	`metaWizard` fields (`array`)	Defines the available fields for the `metaWizard` input type.
minlength	Minimum length (`integer`)	Minimum number of characters that have to be entered.
minval	Minimum value (`integer`)	Minimum number value to be checked (lower bound).
multiple	true/false (`bool`)	Make the input field multiple. Applies to text fields, select menus, radio buttons and checkboxes. Required for the checkbox wizard.
nospace	true/false (`bool`)	If true whitespace characters will not be allowed.
orderField	Order column (`string`)	Database column where the order of the selected items gets stored. This is only required if `isGallery` or `isDownloads` is set. Applies to file trees only.
path	Path (`string`)	Custom root directory for file trees. Applies to file trees only.
placeholder	Placeholder (`string`)	Displays a placeholder for the respective field.
preserveTags	true/false (`bool`)	If true no HTML tags will be removed at all.
readonly	true/false (`bool`)	Makes the field read only (not supported by all field types).
rgxp	Regular expression (`string`)	Limits the user input to certain rules (see paragraph Regular Expressions).
rows	Rows (`integer`)	Number of rows (used for `textarea` and `tableWizard` fields).
rte	Rich text editor file (`string`)	`ace` or `tinyMCE` for example. For `ace` you can also define the type, e.g. `ace\|js` or `ace\|php`. Note: `allowHtml` and `decodeEntities` is automatically enabled if `rte` equals to `ace\|html` or if it starts with `tiny`.
size	Size (`integer`)	Size of a multiple select menu or number of input fields.
spaceToUnderscore	true/false (`bool`)	If true any whitespace character will be replaced by an underscore.
style	Style attributes (`string`)	Style attributes (e.g. `border:2px`).
submitOnChange	true/false (`bool`)	If true the form will be submitted when the field value changes.
tl_class	CSS class(es) (`string`)	Add the given CSS class(es) to the generated HTML. See section Arranging Fields for supported values.
trailingSlash	true/false (`bool`)	If true a trailing slash will be added to the field value. If false, an existing trailing slash will be removed from the field value.
unique	true/false (`bool`)	If true the field value cannot be saved if it exists already.
uploadFolder	Path (`string`)	The target path for file uploads of the `upload` widget.
useRawRequestData	true/false (`bool`)	If true the raw request data from the Symfony request is used. Warning: input filtering is bypassed! Make sure the data is never output anywhere in the back end unescaped which it would if you added the field to a regular back end list view for example.
versionize	true/false (`bool`)	If false skip this field in the versioning. Default `true`.

Using the encrypt option is deprecated and its internal implementation relies on mcrypt, which will no longer be available in PHP 7.2 and higher. Use a load and save callback with your own implementation instead.

Regular Expressions

Regular expressions (rgxp) requires the input of a field to match a pre-defined format. A lot of useful formats are shipped with Contao, but additional formats can be registered using a hook.

Key	Description
digit	allows numeric characters only (including full stop [.] and minus [-])
natural	allows non-negative natural numbers (including 0)
alpha	allows alphabetic characters only (including full stop [.] minus [-] and space [ ])
alnum	allows alphanumeric characters only (including full stop [.] minus [-], underscore [_] and space [ ])
extnd	disallows `#<>()\\=`
date	expects a valid date
time	expects a valid time
datim	expects a valid date and time
friendly	expects a valid “friendly name format” e-mail address (`Lorem Ipsum <foobar@example.com>` or `Lorem Ipsum [foobar@example.com]`)
email	expects a valid e-mail address
emails	expects a valid list of valid e-mail addresses
url	expects a valid URL
alias	expects a valid alias
folderalias	expects a valid folder URL alias
phone	expects a valid phone number (numeric characters, space [ ], plus [+], minus [-], parentheses [()] and slash [/])
prcnt	allows numbers between 0 and 100
locale	expects a valid locale (e.g. “de_CH”)
language	expects a valid language code (e.g. “de-CH”)
google+	expects a Google+ ID or vanity name
fieldname	expects a valid field name (added in version 3.5.16 / 4.2.3)
httpurl	This feature is available in Contao 4.11 and later. expects a valid absolute URL (beginning with `http://` or `https://`)
custom	This feature is available in Contao 4.11 and later. enables you to define a custom regular expression under the `customRgxp` evaluation key e.g. `'eval' => ['rgxp' => 'custom', 'customRgxp' => '/^[1-9]\d*$/']`

Meta Wizard Fields

When using the metaWizard input type, as it is used in tl_files within the Contao core for example, the available fields can be defined through the metaFields key in the eval definition of the field. This definition is an associative array, where the key is the key of the meta field and its value will be used for additional attributes of the text input field.

The meta wizard only supports text input fields, and textarea fields since Contao 4.9.10.

For example, this is the definition of the tl_files.meta field from the Contao core:

$GLOBALS['TL_DCA']['tl_files']['fields']['meta']['eval']['metaFields'] = [
    'title' => 'maxlength="255"',
    'alt' => 'maxlength="255"',
    'link' => 'maxlength="255"',
    'caption' => 'maxlength="255"',
];

Each meta field is always a simple text input, which can be expanded with additional HTML attributes. In this case, all the meta fields get the attribute maxlength="255".

If you want to add an additional meta field to the file manager of Contao, you could do it like this:

// contao/dca/tl_files.php
$GLOBALS['TL_DCA']['tl_files']['fields']['meta']['eval']['metaFields']['example'] = 
    'maxlength="255"'
;

This will insert the new meta field, however it will have no label in the back end, as its translation is still missing. The translation key for these meta fields consists of the name of the field, grouped and prefixed by MSC.aw_. So for this new field the translation definition could look like this:

// contao/languages/en/default.php
$GLOBALS['TL_LANG']['MSC']['aw_example'] = 'My example';

Relations

Relations describe, how database fields are related to other tables. Define the referenced table in the foreignKey key. Relations provide model classes to load referenced data sets efficiently and developer friendly. (see \Contao\Model::getRelated()).

Key	Value	Description
type	Type of relation (`string`)	hasOne Value references a child data set hasMany Value references some child data sets (serialized) belongsTo Value references a parent data set (e.g. `pid`) belongsToMany Value references some parent data sets (serialized)
load	Load behaviour (`string`)	lazy Loading referenced records only when necessary (default, saves RAM) eager Loading referenced records automatically (saves database calls)
table	Relation table (`string`)	A database table for this relation. Optional, by default Contao tries to extract it from the `foreignKey` attribute.
field	Relation table field (`string`)	Override the default relation field (`id`). Useful for relation with `tl_files.uuid` for example.

SQL Column Definition

Since Contao 3.0, the database definition is added using the sql key as a string to each DCA field, e.g. varchar(255) NOT NULL default ''. Starting from Contao 4.3, one can use Doctrine Schema Representation to take full advantage of the Doctrine Database Abstraction Layer.

Examples:

Doctrine Schema Representation	SQL Equivalent
`['type' => 'string', 'length' => 32, 'default' => '']`	`VARCHAR(32) NOT NULL DEFAULT ''`
`['type' => 'string', 'length' => 1, 'fixed' => true, 'default' => '']`	`CHAR(1) NOT NULL DEFAULT ''`
`['type' => 'integer', 'notnull' => false, 'unsigned' => true]`	`INT UNSIGNED NULL`
`['type' => 'binary', 'length' => 16, 'fixed' => true, 'notnull' => false]`	`BINARY(16) NULL`