Record types

A basic table without distinct types

A table record supporting only one type defines which fields should be displayed in the backend form for the default type.

As an example, a comment on a blog post can be stored in a table as follows:

EXT:blog_example/Configuration/TCA/tx_blogexample_comment.php

<?php

return [
    'ctrl' => [
        'title' => 'Comment',
        // ...
    ],
    'types' => [
        '0' => [
            'showitem' => 'hidden, name, email, content, date',
        ],
    ],
    'columns' => [
        // ...
    ],
];

The types section is mandatory.

Supporting multiple record types in the same table

If a table supports multiple record types, the type of the record must be saved in a dedicated database field, commonly named record_type or just type. Usually a select field is used for that purpose.

The name of this field is registered in the ctrl section via property type.

As an example, a blog post might have several types where the fields displayed in the backend differ:

EXT:blog_example/Configuration/TCA/tx_blogexample_post.php

<?php

return [
    'ctrl' => [
        'title' => 'LLL:EXT:blog_example/.../locallang_db.xlf:post_title',
        'label' => 'title',
        'type' => 'record_type',
        'typeicon_classes' => [
            '0' => 'tx-blog-post',
            'link' => 'tx-blog-post-link',
            'special' => 'tx-blog-post-special',
        ],
        // ...
    ],
    'types' => [
        '0' => [
            'showitem' => 'blog, title, date, author, content, comments, ',
        ],
        'link' => [
            'showitem' => ' blog, title, date, author, link, ',
        ],
        'special' => [
            'showitem' => 'blog, title, date, author, content, tags, comments, ',
        ],
    ],
    'columns' => [
        'record_type' => [
            'label' => 'LLL:EXT:blog_example/.../post_types',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Blog Post',
                        'value' => '0',
                    ],
                    [
                        'label' => 'Link to External Blog Post',
                        'value' => 'link',
                    ],
                    [
                        'label' => 'Special Blog Post',
                        'value' => 'special',
                    ],
                ],
                'default' => '0',
            ],
        ],
        // ...
    ],
];

For each record type you can define additional creationOptions and change field display definitions via columnsOverrides.

It is also possible to define previewRenderers.

You can also define icons for each type using the property ctrl -> typeicon_classes.

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)
subtypes_addlist	array
subtypes_excludelist	array
subtype_value_field	string (field name)

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 different field column definitions to be applied when a record of this type is edited. Currently, only the display of form fields is affected, not data handling.

A typical property that can be changed is renderType.

The core uses this property to override 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: Create the blog plugin at once

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: Create the blog plugin at once

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: Display all fields on one page of the form

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 (plain text label or label reference) to override the default label from columns section.

--palette--;paletteLabel;paletteName

Name of a palette to show. The label (plain text label or label 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" (plain text label or label 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.

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

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]"

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.

Changed in version 13.0

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

Extensions still using this setting 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

Display all fields on one page of the form

The table containing the blog comments does not contain many fields. So they can all be displayed on one page of the backend form without using tabs:

EXT:blog_example/Configuration/TCA/tx_blogexample_comment.php

<?php

return [
    'types' => [
        '0' => [
            'showitem' => 'hidden, name, email, content, date, ',
        ],
    ],
    // ...
];

Group fields using tabs and use palettes

If a table has a larger number of fields, grouping them into tabs and palettes can improves the backend user experience. Palettes have the additional value that they can be reused across different record types.

EXT:blog_example/Configuration/TCA/tx_blogexample_post.php

<?php

return [
    'types' => [
        '0' => [
            'showitem' => '
            record_type, blog, title, date, author, content,
            --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:access,
                hidden,
                --palette--;;paletteStartStop,
                fe_group,
            --div--;LLL:EXT:core/Resources/Private/Language/Form/locallang_tabs.xlf:language,
                 --palette--;;paletteLanguage,
            ',
        ],
    ],
    'palettes' => [
        'paletteStartStop' => [
            'showitem' => 'starttime, endtime',
        ],
        'paletteLanguage' => [
            'showitem' => 'sys_language_uid, l10n_parent',
        ],
    ],
];

The syntax for tabs is:

--div--;<label>

Where label can be plain text label or label reference (preferred).

The syntax to insert a palette is:

--palette--;<label>;<paletteName>

The label can be omitted.

Examples for columnsOverrides in type section of TCA

Demonstrates property: columnsOverrides.

For example the special blog post type might require the author to be set and use a different render type and description for the content:

<?php

return [
    'ctrl' => [
        'title' => 'LLL:EXT:blog_example/.../locallang_db.xlf:post_title',
        // ...
    ],
    'types' => [
        'special' => [
            'columnsOverrides' => [
                'author' => [
                    'config' => [
                        'required' => true,
                    ],
                ],
                'content' => [
                    'description' => 'You can use Markdown syntax for the content. ',
                    'config' => [
                        'renderType' => 'codeEditor',
                    ],
                ],
            ],
            'showitem' => 'blog, title, date, author, content, tags, comments, ',
        ],
        // ...
    ],
    // ...
];

While the field type type cannot be changed in the columnsOverrides the render type renderType can be changed.

Override default values by type

A blog post of type link should have a different default value for the author field then other blog post types:

EXT:blog_example/Configuration/TCA/tx_blogexample_post.php

<?php

return [
    'ctrl' => [
        'title' => 'LLL:EXT:blog_example/.../locallang_db.xlf:post_title',
        // ...
    ],
    'types' => [
        'link' => [
            'showitem' => 'blog, title, date, author, link, ',
            'creationOptions' => [
                'defaultValues' => [
                    'author' => 'External Author',
                ],
            ],
        ],
        // ...
    ],
    // ...
];

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 with the c blogexample_list as determined by the field Ctype of the table tt_content.

This could be used to preview the blog plugin in the page module.

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

Example: Create the blog plugin at once

Demonstrates property: saveAndClose.

When editors create a new blog plugin in the plugin is automatically saved and the user returned to the page module:

EXT:blog_example/Configuration/TCA/Overrides/tt_content_blogexample_list.php

<?php

$GLOBALS['TCA']['tt_content']['types']['blogexample_list']['creationOptions']['saveAndClose'] = true;

Note

This property only takes effect in the table tt_content.

Record types

A basic table without distinct types

Supporting multiple record types in the same table

Properties of types section of TCA

columnsOverrides

creationOptions

saveAndClose

defaultValues

previewRenderer

showitem

subtypes_addlist

subtypes_excludelist

subtype_value_field

Extended examples for using the types section of TCA

Display all fields on one page of the form

Group fields using tabs and use palettes

Examples for columnsOverrides in type section of TCA

Override default values by type

PreviewRenderer examples

Example: Create the blog plugin at once

Properties of `types` section of TCA

Extended examples for using the `types` section of TCA