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.
// 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 ''",
];
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.1 |
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'] . |
1 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']
.
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.'],
];
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. |
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. '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 |
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. |
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 (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] ) |
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. http:// or https:// ) |
custom |
This feature is available in Contao 4.11 and later. customRgxp evaluation key e.g. 'eval' => ['rgxp' => 'custom', 'customRgxp' => '/^[1-9]\d*$/'] |
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 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. |
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 |