Record types 

The types section is mandatory for all table definitions.

Basic tables with only one type use this section to define which fields should be displayed in the backend form in the property showitem.

If the table should provide multiple record types, the field containing the type must be defined in $GLOBALS['TCA'][$table]['ctrl']['type'] and all supported types must be array entries in $GLOBALS['TCA'][$table]['types'].

Each entry in the types array is an array with at least the property showitem defined.

Defining multiple types in one table is similar to what is often done with Single Table Inheritance in Object-orientated programming.

Table of Contents

Subpages

Changed in version 13.3

A basic table without distinct types 

When the table record does not support multiple types it still needs to define one type in order to define which fields should be displayed in the backend form for the default type.

For example the comment of a blog post can be stored in a table that supports no additional types:

EXT:blog_example/Configuration/TCA/tx_blogexample_comment.php 
<?php

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

Omitting the types section is not supported by TYPO3.

Supporting multiple record types in the same table 

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

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

For example a blog post might have one of several types where the fields displayed in the backend differ

EXT:blog_example/Configuration/TCA/tx_blogexample_post.php 
<?php

return [
    'ctrl' => [
        'title' => 'LLL:blog_example.db:tx_blogexample_domain_model_post',
        '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:blog_example.labels: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',
            ],
        ],
        // ...
    ],
];
Copied!

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

It is also possible to define distinct previewRenderers.

You can also define individual icons per type, using 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)

columnsOverrides

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.

creationOptions

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

New in version 13.0

saveAndClose

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

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

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

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

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"
Copied!
--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).

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

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 

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, ',
        ],
    ],
    // ...
];
Copied!

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--;core.form.tabs:access,
                hidden,
                --palette--;;paletteStartStop,
                fe_group,
            --div--;core.form.tabs:language,
                 --palette--;;paletteLanguage,
            ',
        ],
    ],
    'palettes' => [
        'paletteStartStop' => [
            'showitem' => 'starttime, endtime',
        ],
        'paletteLanguage' => [
            'showitem' => 'sys_language_uid, l10n_parent',
        ],
    ],
];
Copied!

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:blog_example.db:tx_blogexample_domain_model_post',
        // ...
    ],
    '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, ',
        ],
        // ...
    ],
    // ...
];
Copied!

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:blog_example.db:tx_blogexample_domain_model_post',
        // ...
    ],
    'types' => [
        'link' => [
            'showitem' => 'blog, title, date, author, link, ',
            'creationOptions' => [
                'defaultValues' => [
                    'author' => 'External Author',
                ],
            ],
        ],
        // ...
    ],
    // ...
];
Copied!

PreviewRenderer examples 

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;
Copied!

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;
Copied!