Field definitions (columns)

The ['columns'] section contains configuration for each table field (also called "column") which can be edited or shown in the backend. This is typically the biggest part of a TCA definition.

The configuration includes both properties for the display in the backend as well as the processing of the submitted data.

Each field can be configured as a certain "type" (required!), for instance a checkbox, an input field, or a database relation selector box. Each type allows a set of additional "renderType"s (sometimes required!). Each "type" and "renderType" combination comes with a set of additional properties.

Content on this page

Subpages

Example: A basic input field

The basic structure of a field definition in TCA looks like this:

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php

[
    'columns' => [
        'input_1' => [
            'l10n_mode' => 'prefixLangTitle',
            'label' => 'input_1 description',
            'description' => 'field description',
            'config' => [
                'type' => 'input',
                'behaviour' => [
                    'allowLanguageSynchronization' => true,
                ],
            ],
        ],
    ],
]

You can find this example in the extension styleguide.

Properties on the level parallel to label are valid for all "type" and "renderType" combinations. They are listed below. The list of properties within the "config" section depend on the specific "type" and "renderType" combination and are explained in detail in the ['columns']['config'] section.

Properties of `columns` section of TCA

Name	Type	Scope
config	array	Display / Proc.
type	string, one of the column types
rendertype	string
description	plain text label or label reference	Display
displayCond	string / array	Display
exclude	boolean	Display / Proc.
l10n_display	string (list of keywords)	Display
l10n_mode	string (keyword)	Display / Proc.
label	plain text label or label reference	Display
onChange	string	Display

config

Type: array
Required: true
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display / Proc.
Examples: the basic input field example

Contains the main configuration properties of the fields display and processing behavior.

The possibilities for this array depend on the value of the array keys type and rendertype within the array.

type

Type: string, one of the column types
Required: true
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['type']

The type influences the rendering of the form field in the backend. It also influences the processing of data on saving the values.

rendertype

Type: string
Required: true
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['rendertype']

For some type definitions there are additional render types available that mainly influence rendering. For example Select fields and Text areas provide different render types.

description

Type: plain text label or label reference
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['description']
Scope: Display
Examples: the basic input field example

The property can be used to display an additional help text between the field label and the user input when editing records. As an example, the Core uses the description property in the site configuration module when editing a site on some properties like identifier.

The property is available on all common TCA types like input and select and so on.

The field can be used with a string that will be directly output or with a language reference.

displayCond

Type: string / array
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['displayCond']
Scope: Display
Examples: Examples for display conditions

Contains one or more condition rules for whether to display the field or not.

Read more in the dedicated chapter displayCond.

exclude

Type: boolean
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['exclude']
Scope: Display / Proc.

If set, all backend users are prevented from editing the field unless they are members of a backend user group with this field added as an "Allowed Excludefield" (or "admin" user).

See Access lists for more about permissions.

Example: Simple input field

EXT:my_extension/Configuration/TCA/tx_myextension_mytable.php

<?php

return [
  'ctrl' => [
    'title' => 'My table',
    'label' => 'title',
  ],
  'columns' => [
    'title' => [
      'label' => 'Title',
      'exclude' => true,
      'config' => [
        'type' => 'input',
      ],
    ],
  ],
  'types' => [
    '0' => [
      'showitem' => 'title',
    ],
  ],
];

l10n_display

Type: string (list of keywords)
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['l10n_display']
Scope: Display
Examples: the select field with defaultAsReadonly, Translated field without l10n_display definition

Localization display, see l10n_mode.

This option can be used to define the language related field rendering. This has nothing to do with the processing of language overlays and data storage but the display of form fields.

Keywords are:

hideDiff: The differences to the default language field will not be displayed.
defaultAsReadonly: This renders the field as read only field with the content of the default language record. The field will be rendered even if l10n_mode is set to 'exclude'. While exclude defines the field not to be translatable, this option activates the display of the default data.

l10n_mode

Type: string (keyword)
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['l10n_mode']
Scope: Display / Proc.
Examples: prefixLangTitle, Disable the prefixLangTitle for the header field in tt_content

Only active if the ['ctrl']['languageField'] property is set.

The main relevance is when a record is localized by an API call in DataHandler that makes a copy of the default language record. You can think of this process as copying all fields from the source record. By default, the given value from the default language record is copied to the localization overlay and the field is editable in the overlay record. This behaviour can be changed:

exclude: Field will not be shown in FormEngine if this record is a localization of the default language. Works basically like a display condition. Internally, the field value of the default language record is copied over to the field of the localized record. The DataHandler keeps the values of localized records in sync and actively copies a changed value from the default language record into the localized overlays if changed. You can force the field to be displayed as readonly (with default language value) by setting "l10n_display" to defaultAsReadonly.
prefixLangTitle: The field value from the default language record gets copied when a localization overlay is created, but the content is prefixed with the title of the target language. The field stays editable in the localized record. It only works for field types like "text" and "input". The text will be prepended and can be configured by the page TSconfig property TCEMAIN.translateToMessage

If this property is not set for a given field, the value of the default language record is copied over to the localized record on creation, the field value is then distinct from the default language record, can be edited at will and will never be overwritten by the DataHandler if the value of the default language record changes.

label

Type: plain text label or label reference
Required: true
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['label']
Scope: Display
Examples: the basic input field example

The name of the field as shown in the form:

Note

Labels can be overridden in the types definition and the palettes definition. They can also be overridden by the page TSconfig property label.

onChange

Type: string
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['onChange']
Scope: Display

If set to reload, it triggers a form reload once the value of this field is changed. This is automatically set for fields specified as record type in the control section.

The onChange property is useful for fields which are targets of a display condition's FIELD: evaluation.

On changing the field a modal gets displayed prompting to reload the record.

Example: Select field triggering reload

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_requestUpdate_1' => [
            'label' => 'select_requestUpdate_1',
            'onChange' => 'reload',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Just an item',
                        'value' => 1,
                    ],
                    [
                        'label' => 'bar',
                        'value' => 'bar',
                    ],
                    [
                        'label' => 'and yet another one',
                        'value' => -1,
                    ],
                ],
            ],
        ],
    ],
]

Field definitions (columns)

Example: A basic input field

Properties of columns section of TCA

Properties of `columns` section of TCA