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

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.'],
    ['headspan', 'Use `headspan` to spread this text over the header and the content and style it as a headline.'],
    ['colspan', 'Use `colspan` to spread this text over the header and the content.'],
];

// contao/dca/tl_content.php
use Contao\CoreBundle\DataContainer\PaletteManipulator;

$GLOBALS['TL_DCA']['tl_content']['fields']['example'] = [
    'inputType' => 'text',
    'explanation' => 'example',
    'eval' => ['tl_class' => 'w50', 'helpwizard' => true],
    'sql' => ['type' => 'string', 'default' => ''],
];

PaletteManipulator::create()
    ->addField('example', 'text')
    ->applyToPalette('text', 'tl_content')
;

// contao/languages/en/tl_content.php
$GLOBALS['TL_LANG']['example'] = [
    'Example field',
    'Field for demonstrating the explanation configuration.'
];

// contao/languages/en/explain.php
$GLOBALS['TL_LANG']['XPL']['example'] = 'Explanatory text for the <strong>example</strong> field.';

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
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.
basicEntities	true/false (bool)	If true, converts basic entities like ­, & etc. back to their Contao representation [&], [-] etc. when editing and vice versa when saving.
blankOptionLabel	Label (string)	Label for the blank option (defaults to -).
chosen	true/false (bool)	Native selects enhanced with Chosen.
collapseUncheckedGroups	true/false (bool)	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)	Custom regular expression to be used when using 'rgxp' => 'custom'
errorMsg	Custom Message (string)	Custom error message 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.
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)	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.

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.

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.

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()).

Enumerations

By using Enumerations, the options of a field can be generated automatically.

If you store a BackedEnum as enum in the DCA, Contao will generate a matching option item for all Enum::cases().

Automatic translations

By implementing the interface Contao\CoreBundle\Translation\TranslatableLabelInterface, Contao will also generate a translation for each option and provide them as reference.

// String backed enumeration that implements TranslatableLabelInterface
namespace App/Data;

use Contao\CoreBundle\Translation\TranslatableLabelInterface;
use Symfony\Component\Translation\TranslatableMessage;

enum Salutation: string implements TranslatableLabelInterface
{
    case ms = 'ms';
    case mr = 'mr';
    case mx = 'mx';

    public function label(): TranslatableMessage
    {
        return new TranslatableMessage(
            'salutation.label.' . $this->value,
            [],
            'messages',
        );
    }

# translations/messages.de.yaml
salutation:
    label:
        ms: Frau
        mr: Herr
        mx: ''

// contao/dca/tl_member.php
$GLOBALS['TL_DCA']['tl_member']['salutation'] => [
  'inputType' => 'select',
  'enum' => App\Data\Salutation::class,
];

// Will result in:
$GLOBALS['TL_DCA']['tl_member']['salutation'] => [
  'inputType' => 'select',
  'options' => ['ms', 'mr', 'mx'],
  'reference' => [
    'ms' => 'Frau',
    'mr' => 'Herr',
    'mx' => '',
  ],
];

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: