Fields to be displayed (types)

Note

Click here if you are looking for ['columns']['config']['type'].

The ['types'] section plays a crucial role in TCA to specify which fields from the ['columns'] section are displayed if editing a table row in FormEngine. At least one type has to be configured before any field will show up, the default type is 0.

Multiple types can be configured, which one is selected depends on the value of the field specified in ['ctrl']['type'] property. This approach is similar to what is often done with Single Table Inheritance in Object-orientated programming.

Table of Contents

Subpages

Changed in version 13.3

Creating content elements has been simplified by removing the need to define the system fields for each element again and again. This shrinks down a content element's showitem to just the element specific fields. See also Automatically added system fields to content types (tt_content).

Introduction

The ['types'] system is powerful and allows differently shaped editing forms re-using fields, having own fields for specific forms and arranging fields differently on top of a single database table. The tt_content with all its different content elements is a good example on what can be done with ['types'].

The basic ['types'] structure looks like this:

'types' => [
     '0' => [
           'showitem' => 'aField, anotherField',
     ],
     'anotherType' => [
           'showitem' => 'aField, aDifferentField',
     ],
],

So, the basic array has a key field with type names (here '0', and 'anotherType'), with a series of possible properties each, most importantly the showitem property.

Properties of `types` section of TCA

Name	Type	Scope
columnsOverrides	array (columns fields overrides)	Display
creationOptions	list of options
saveAndClose	bool
defaultValues	array
previewRenderer	string	Display
showitem	string (list of field configuration sets)
subtype_value_field	string (field name)
subtypes_addlist	array
subtypes_excludelist	array

columnsOverrides

Type: array (columns fields overrides)
Path: $GLOBALS['TCA'][$table]['types'][$type]
Scope: Display
Examples: Examples for columnsOverrides

Changed or added ['columns'] field display definitions.

This allows to change the column definition of a field if a record of this type is edited. Currently, it only affects the display of form fields, but not the data handling.

A typical property that can be changed here is renderType.

The core uses this property to override for instance the "bodytext" field config of table "tt_content": If a record of type "text" is edited, it adds "enableRichtext = 1" to trigger an RTE to the default "bodytext" configuration, and if a type "table" is edited, it adds "renderType = textTable" and "wrap = off" to "bodytext".

The FormEngine basically merges "columnsOverrides" over the default "columns" field after the record type has been determined.

Attention

It is not possible to override any properties in "Proc." scope: The DataHandler does not take "columnsOverrides" into account. Only pure "Display" related properties can be overridden. This especially means that columns config 'type' must not be set to a different value.

creationOptions

Type: list of options
Path: $GLOBALS['TCA'][$table]['types'][$type]['creationOptions']

New in version 13.0

The page TSconfig option newContentElement.wizardItems.[group].elements.[name] can be defined through TCA as well:

saveAndClose

Type: bool
Default: false
Path: $GLOBALS['TCA'][$table]['types'][$type]['creationOptions']['saveAndClose']
Examples: Example: Activate save and close for divider content element

New in version 13.0

If true, clicking on the new element wizard will take the user directly to the page module, rather than showing the edit form from the form engine.

Can be overridden with page TSconfig option saveAndClose.

defaultValues

Type: array
Path: $GLOBALS['TCA'][$table]['types'][$type]['creationOptions']['defaultValues']
Examples: Example: Activate save and close for divider content element

New in version 13.0

Default values inserted into the fields of the tt_content record on creation via the "New Content Element" wizard

Can be overridden with page TSconfig option tt_content_defValues.

previewRenderer

Type: string
Path: $GLOBALS['TCA'][$table]['types'][$type]['previewRenderer']
Scope: Display
Examples: types-example-previewRenderer

Deprecated since version 13.4

Registration of subtypes has been deprecated. Registration of custom types should therefore always be done by using record types.

To configure a preview renderer for the whole table see previewRenderer.

Configures a backend preview for a content element.

Have also a look at Configure custom backend preview for content element for more details.

Use property previewRenderer of section ctrl to configure the preview globally for the whole table.

showitem

Type: string (list of field configuration sets)
Path: $GLOBALS['TCA'][$table]['types'][$type]['showitem']
Required: true
Examples: Showitem examples

Configuration of the displayed order of fields in FormEngine and their tab alignment.

The whole string is a comma , separated list of tokens. Each token can have keywords separated by semicolon ;.

Each comma separated token is one of the following:

fieldName;fieldLabel

Name of a field to show. Optionally an alternative label (string or LLL reference) to override the default label from columns section.

--palette--;paletteLabel;paletteName

Name of a palette to show. The label (string or LLL reference) is optional. If set, it is shown above the single palette fields. The palette name is required and must reference a palette from the palette section.

--palette--;;caching // Show palette "caching" without additional label
--palette--;Caching;caching // Show palette "caching" with label "Caching"

--div--;tabLabel

Put all fields after this token onto a new tab and name the tab as given in "tabLabel" (string or LLL reference).

Note

It is good practice to add a comma in excess behind the very last field name as shown in the examples above. The FormEngine code will ignore this, but it helps developers to not forget about a comma when additional fields are added, which can suppress an annoying "Why is my new field not displayed?" bug hunt.

subtype_value_field

Type: string (field name)
Path: $GLOBALS['TCA'][$table]['types'][$type]

Deprecated since version 13.4

Registration of subtypes has been deprecated. Registration of custom types should therefore always be done by using record types. See also Migration from subtypes to types.

Field name, which holds a value being a key in the subtypes_excludelist array. This allows to add and hide fields found in the types configuration, based on the value of another field in the row.

subtypes_addlist

Type: array
Path: $GLOBALS['TCA'][$table]['types'][$type]

Deprecated since version 13.4

Registration of subtypes has been deprecated. Registration of custom types should therefore always be done by using record types. See also Migration from subtypes to types.

A list of fields to add when the subtype_value_field matches a key in this array.

Syntax

"[value]" => "[comma-separated list of fields which are added]"

subtypes_excludelist

Type: array
Path: $GLOBALS['TCA'][$table]['types'][$type]

Deprecated since version 13.4

Registration of subtypes has been deprecated. Registration of custom types should therefore always be done by using record types. See also Migration from subtypes to types.

See property subtype_value_field.

Syntax

"[field value]" => "[comma-separated list of fields (from the main types-config) which are removed]"

Changed in version 13.0

The properties bitmask_excludelist_bits and bitmask_excludelist_bits been removed, it is not considered anymore when rendering records in the backend record editing interface.

In case, extensions still use this setting, they should switch to casual $GLOBALS['TCA']['someTable']['ctrl']['type'] fields instead, which can be powered by columns based on string values.

Extended examples for using the `types` section of TCA

Showitem examples

Demonstrates property: showitem.

Extensions can also modify showitem values by utilizing ExtensionManagementUtility::addToAllTCAtypes(). See Customization Examples for details.

A form with 3 fields

'types' => [
    '0' => [
        'showitem' => 'hidden, title, poem,',
    ],
],

The above example shows three fields of the form. Since no further '--div--' are specified, there would be only one tab. In this case FormEngine will suppress that single tab and just show all specified fields without a tabbing indicator.

A form with two tabs

'types' => [
    '0' => [
        'showitem' => '
            hidden, title, poem,
            --div--;LLL:EXT:examples/locallang_db.xml:tx_examples_haiku.images, image1, image2,
        '
    ],
],

Put three fields on first tab "General" and the two fields "image1" and "image2" on a second tab with the localized name found in "EXT:examples/locallang_db.xml:tx_examples_haiku.images".

Rename the tab "General"

'types' => [
    '0' => [
        'showitem' => '
            --div--;LLL:EXT:examples/locallang_db.xml:tx_examples_haiku.images, hidden, title, poem,
            --div--;LLL:EXT:examples/locallang_db.xml:tx_examples_haiku.images, image1, image2,
        '
    ],
],

Similar to the example before, but rename the "General" tab to the string specified in label "LLL:EXT:examples/locallang_db.xml:tx_examples_haiku.images".

Required type examples

Required type - minimal configuration

The type 0 is required to be defined. It has to have at least the property showitem defined. A minimal configuration can be seen here, for example:

EXT:styleguide/Configuration/TCA/tx_styleguide_ctrl_minimal.php

[
    'types' => [
        [
            'showitem' => 'title',
        ],
    ],
]

It displays nothing but a single field.

Required type - tabs and palettes

The following configuration specifies two tabs: the first one labelled "general" with three fields "category" "subject" and "message", and the second one labelled "access" with the field "personal". Only the default type "0" is specified. Opening such a record looks like this:

Optional additional types

The power of the "types" configuration becomes clear when you want the form composition of a record to depend on a value from the record. Let's look at the tx_styleguide_type table from the styleguide extension. The ctrl section of its TCA contains a property called :php: type:

EXT:styleguide/Configuration/TCA/tx_styleguide_type.php

[
    'ctrl' => [
        'title' => 'Form engine - type',
        'label' => 'input_1',
        'tstamp' => 'tstamp',
        'crdate' => 'crdate',
        'delete' => 'deleted',
        'sortby' => 'sorting',
        'iconfile' => 'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg',
        'versioningWS' => true,
        'languageField' => 'sys_language_uid',
        'transOrigPointerField' => 'l10n_parent',
        'transOrigDiffSourceField' => 'l10n_diffsource',
        'translationSource' => 'l10n_source',
        'enablecolumns' => [
            'disabled' => 'hidden',
        ],
        'type' => 'record_type',
        'security' => [
            'ignorePageTypeRestriction' => true,
        ],
    ],
]

This indicates that the field called record_type is to specify the type of any given record of the table. Let's look at how this field is defined in the property columns:

EXT:styleguide/Configuration/TCA/tx_styleguide_type.php

[
    'columns' => [
        'record_type' => [
            'label' => 'type',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'type 0',
                        'value' => '0',
                    ],
                    [
                        'label' => 'Type with changed fields',
                        'value' => 'withChangedFields',
                    ],
                    [
                        'label' => 'Type with columnsOverrides',
                        'value' => 'withColumnsOverrides',
                    ],
                ],
            ],
        ],
    ],
]

There's nothing unusual here. It's a pretty straightforward select field, with three options. Finally, in the types section, we define what fields should appear and in what order for every value of the type field:

EXT:styleguide/Configuration/TCA/tx_styleguide_type.php

[
    'types' => [
        0 => [
            'showitem' => 'record_type, input_1, text_1',
        ],
        'withChangedFields' => [
            'showitem' => 'record_type, input_1, color_1, text_1',
        ],
        'withColumnsOverrides' => [
            'showitem' => 'record_type, input_1, color_1, text_1',
            'columnsOverrides' => [
                'color_1' => [
                    'label' => 'color_1, readOnly, size=10',
                    'config' => [
                        'readOnly' => true,
                        'size' => 10,
                    ],
                ],
                'text_1' => [
                    'config' => [
                        'renderType' => 'codeEditor',
                        'format' => 'html',
                    ],
                ],
            ],
        ],
    ],
]

The result if the following display when type 0 is chosen:

Changing to type withChangedFields reloads the form and displays the a different set of fields:

Examples for columnsOverrides in type section of TCA

Demonstrates property: columnsOverrides.

Type withOverriddenColumns shows the fields and overrides part of the configuration of the fields:

Note

It is a good idea to give all "types" speaking names, except the default type 0. Therefore we named the other types withChangedFields and withOverriddenColumns instead of 1, 2 etc. In a real life example they should have names from the domain.

Example adding "nowrap" to a text type for type "text"

Demonstrates property: columnsOverrides.

Example adding "nowrap" to a text type for type "text":

EXT:my_extension/Configuration/TCA/tx_myextension_table.php (Excerpt)

'types' => [
    'text' => [
        'showitem' => 'hidden, myText',
        'columnsOverrides' => [
            'myText' => [
                'config' => [
                    'wrap' => 'off',
                ],
            ],
        ],
    ],
    // ...
],

PreviewRenderer examples

Deprecated since version 13.4

Registration of subtypes has been deprecated. Registration of custom types should therefore always be done by using record types.

If you used PreviewRenderer with a subtype see section Migration: PreviewRenderer for subtypes.

Demonstrates property: previewRenderer.

This specifies the preview renderer only for records of type $type as determined by the type field of your table.

$GLOBALS['TCA']['tt_content']['types'][$type]['previewRenderer']
    = \MyVendor\MyExtension\Preview\PreviewRenderer::class;

Example: Activate save and close for divider content element

Demonstrates property: saveAndClose.

EXT:my_extension/Configuration/TCA/Overrides/tt_content.php

<?php

$GLOBALS['TCA']['tt_content'] = array_merge_recursive(
    $GLOBALS['TCA']['tt_content'],
    [
        // ...
        'types' => [
            'div' => [
                'creationOptions' => [
                    'saveAndClose' => true,
                    'defaultValues' => [
                        'bodytext' => '<p>some text</p>',
                    ],
                ],
            ],
        ],
    ]
);

Fields to be displayed (types)

Introduction

Properties of types section of TCA

columnsOverrides

creationOptions

saveAndClose

defaultValues

previewRenderer

showitem

subtype_value_field

subtypes_addlist

subtypes_excludelist

Extended examples for using the types section of TCA

Showitem examples

A form with 3 fields

A form with two tabs

Rename the tab "General"

Required type examples

Required type - minimal configuration

Required type - tabs and palettes

Optional additional types

Examples for columnsOverrides in type section of TCA

Example adding "nowrap" to a text type for type "text"

PreviewRenderer examples

Example: Activate save and close for divider content element

Properties of `types` section of TCA

Extended examples for using the `types` section of TCA