Deprecation: #79440 - TCA Changes

Description

The TCA on field level has been changed. Nearly all column types are affected. In general, the sub-section wizards is gone and replaced by a combination of new renderType's and a new set of configuration options. Wizards are now divided into three different kinds:

fieldInformation - Informational HTML, typically displayed between the element label and the element itself.
fieldControl - Icons, typically displayed right next to the element, used to trigger certain actions, for instance to jump to the link view.
fieldWizard - HTML typically shown below the element to enrich the element with further functionality. Example is the rendering of thumbnails below a type=group element.

Other wizards like the "suggest" functionality have been merged into the affected elements itself.

Additionally, the config option defaultExtras, which was often set within columnsOverrides has been removed. The options were transferred to config options of the elements itself and can be set within columnsOverrides directly.

A TCA migration transforms old configuration options to new ones and throws descriptive log entries.

The first list covers all former existing wizards and shows where and how the functionality is now placed.

The second list below gives examples from before and after based on type, together with detail information on certain configuration options.

Wizard list

Add wizard, edit wizard and list wizard

The three wizards wizard_add, wizard_edit and wizard_list usually used in type=group and type=select with renderType=selectMultipleSideBySide are now default controls of these two elements and just need to be enabled. options are optional, the render engine selects a fallback title, a default pid and table name if needed.

Example before:

'wizards' => [
    '_VERTICAL' => 1,
    'edit' => [
        'type' => 'popup',
        'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_tca.xlf:be_users.usergroup_edit_title',
        'module' => [
            'name' => 'wizard_edit',
        'popup_onlyOpenIfSelected' => true,
        'icon' => 'actions-open',
        'JSopenParams' => 'width=800,height=600,status=0,menubar=0,scrollbars=1'
    ],
    'add' => [
        'type' => 'script',
        'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_tca.xlf:be_users.usergroup_add_title',
        'icon' => 'actions-add',
        'params' => [
            'table' => 'be_groups',
            'pid' => 0,
            'setValue' => 'prepend'
        ],
        'module' => [
            'name' => 'wizard_add'
        ]
    ],
    'list' => [
        'type' => 'script',
        'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_tca.xlf:be_users.usergroup_list_title',
        'icon' => 'actions-system-list-open',
        'params' => [
            'table' => 'be_groups',
            'pid' => 0
        ],
        'module' => [
            'name' => 'wizard_list'
        ]
    ]
]

Example after:

'fieldControl' => [
    'editPopup' => [
        'disabled' => false,
    ],
    'addRecord' => [
        'disabled' => false,
        'options' => [
            'setValue' => 'prepend',
        ],
    'listModule' => [
        'disabled' => false,
    ],
],

Color picker

The color picker wizard has been changed to type=input element with renderType=colorpicker

Example before:

'input_34' => [
    'label' => 'input_34',
    'config' => [
        'type' => 'input',
        'wizards' => [
            'colorChoice' => [
               'type' => 'colorbox',
               'title' => 'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.colorPick',
               'module' => [
                  'name' => 'wizard_colorpicker',
               ],
               'JSopenParams' => 'height=600,width=380,status=0,menubar=0,scrollbars=1',
               'exampleImg' => 'EXT:examples/res/images/japanese_garden.jpg',
            ]
        ],
    ],
],

Example after:

'input_34' => [
    'label' => 'input_34',
    'config' => [
        'type' => 'input',
        'renderType' => 'colorpicker',
    ],
],

Table wizard

The table wizard has been embedded in type=text element with renderType=textTable

Example before:

'text_17' => [
    'label' => 'text_17',
    'config' => [
        'type' => 'text',
        'cols' => '40',
        'rows' => '5',
        'wizards' => [
            'table' => [
                'notNewRecords' => 1,
                'type' => 'script',
                'title' => 'LLL:EXT:cms/locallang_ttc.xlf:bodytext.W.table',
                'icon' => 'content-table',
                'module' => [
                    'name' => 'wizard_table'
                ],
                'params' => [
                    'xmlOutput' => 0
                ]
            ],
        ],
    ],
],

Example after:

'text_17' => [
    'label' => 'text_17',
    'config' => [
        'type' => 'text',
        'renderType' => 'textTable',
        'cols' => '40',
        'rows' => '5',
    ],
],

RTE wizard

The RTE wizard that jumps to a full screen view of a text field has been embedded into EXT:rtehtmlarea directly and just needs to be turned on. This additionally obsoletes the defaultExtras=rte_only setting.

Example before:

'rte_1' => [
    'label' => 'rte_1',
    'config' => [
        'type' => 'text',
        'enableRichtext' => true,
        'RTE' => [
            'notNewRecords' => 1,
            'RTEonly' => 1,
            'type' => 'script',
            'title' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:bodytext.W.RTE',
            'icon' => 'actions-wizard-rte',
            'module' => [
                'name' => 'wizard_rte'
            ]
        ],
    ],
],

Example after:

'rte_1' => [
    'label' => 'rte_1',
    'config' => [
        'type' => 'text',
        'enableRichtext' => true,
        'fieldControl' => [
            'fullScreenRichtext' => [
                'disabled' => false,
            ],
        ],
    ],
],

Link browser

The link browser icon wizard has been embedded in new 'renderType' => 'inputLink' directly. The parameters blindLinkOptions, blindLinkFields and allowedExtensions are now all optional and options of section fieldControl.

Example before:

'input_29' => [
    'label' => 'input_29 link',
    'config' => [
        'type' => 'input',
        'wizards' => [
            'link' => [
            'type' => 'popup',
            'title' => 'LLL:EXT:frontend/Resources/Private/Language/locallang_ttc.xlf:header_link_formlabel',
            'icon' => 'actions-wizard-link',
            'module' => [
               'name' => 'wizard_link',
            ],
            'JSopenParams' => 'height=800,width=600,status=0,menubar=0,scrollbars=1',
            'params' => [
                'blindLinkOptions' => 'folder',
                'blindLinkFields' => 'class, target',
                'allowedExtensions' => 'jpg',
            ],
        ],
    ],
],

Example after:

'input_29' => [
    'label' => 'input_29',
    'config' => [
        'type' => 'input',
        'renderType' => 'inputLink',
        'fieldControl' => [
            'linkPopup' => [
                'options' => [
                    'blindLinkOptions' => 'folder',
                    'blindLinkFields' => 'class, target',
                    'allowedExtensions' => 'jpg',
                ],
            ],
        ],
    ],
],

Select wizard

The select wizard has been directly embedded in type=input and type=text elements, only works with a static list of items and is called valuePicker.

Example before:

'input_33' => [
    'label' => 'input_33',
    'config' => [
        'type' => 'input',
        'wizards' => [
            'select' => [
                'items' => [
                    [ 'spring', 'Spring', ],
                    [ 'summer', 'Summer', ],
                    [ 'autumn', 'Autumn', ],
                    [ 'winter', 'Winter', ],
                ],
            ],
        ],
    ],
],

Example after:

'input_33' => [
    'label' => 'input_33',
    'config' => [
        'type' => 'input',
        'valuePicker' => [
            'items' => [
                [ 'spring', 'Spring', ],
                [ 'summer', 'Summer', ],
                [ 'autumn', 'Autumn', ],
                [ 'winter', 'Winter', ],
            ],
        ],
    ],
],

Suggest wizard

The suggest wizard has been directly embedded in type=group element and is enabled by default. It can be disabled by setting hideSuggest=true in config section and suggest options can be added in suggestOptions.

Example before:

'group_db_8' => [
    'label' => 'group_db_8',
    'config' => [
        'type' => 'group',
        'internal_type' => 'db',
        'allowed' => 'tx_styleguide_staticdata',
        'wizards' => [
            '_POSITION' => 'top',
                'suggest' => [
                    'type' => 'suggest',
                    'default' => [
                        'pidList' => 42,
                    ],
                ],
            ],
        ],
    ],
],

Example after:

'group_db_8' => [
    'label' => 'group_db_8',
    'config' => [
        'type' => 'group',
        'internal_type' => 'db',
        'allowed' => 'tx_styleguide_staticdata',
        'suggestOptions' => [
            'default' => [
                'pidList' => 42,
            ]
        ],
    ],
],

Slider wizard

The slider wizard has been embedded in type=text as option slider within the config section.

Example before:

'input_30' => [
    'label' => 'input_30',
    'config' => [
        'type' => 'input',
        'size' => 5,
        'eval' => 'trim,int',
        'range' => [
            'lower' => -90,
            'upper' => 90,
        ],
        'default' => 0,
        'wizards' => [
            'angle' => [
                'type' => 'slider',
                'step' => 10,
                'width' => 200,
            ],
        ],
    ],
],

Example after:

'input_30' => [
    'label' => 'input_30',
    'config' => [
        'type' => 'input',
        'size' => 5,
        'eval' => 'trim,int',
        'range' => [
            'lower' => -90,
            'upper' => 90,
        ],
        'default' => 0,
        'slider' => [
            'step' => 10,
            'width' => 200,
        ],
    ],
],

Type list

type=input

The wizard slider has been directly embedded in this element. The new config option slider can be used to configure the slider. The slider appears if the option slider exists and is an arary.
The wizard select has been directly embedded in this element. The new config option valuePicker has been introduced to configure items of the drop down.
The four date related eval options date, datetime, time and timesec have been moved to renderType=inputDateTime.
The wizard wizard_link has been removed a field now displays the link wizard by setting renderType=inputLink for a type=input element.

type=text

The wizard select has been directly embedded in this element. The new config option valuePicker has been introduced to configure items of the drop down.
The wizard wizard_table has been given the own renderType=textTable.
The wizard RTE has been changed to a fieldControl of the richtext element implemented by extension rtehtmlarea.
defaultExtras=enable-tab has been moved to config option enableTabulator
defaultExtrasfixed-font has been moved to config option fixedFont
defaultExtras=nowrap has been moved to config option wrap=off

type=select with renderType=selectSingle

Config option showIconTable has been dropped. Showing assigned images below the select field has been migrated to a fieldWizard and is disabled by default.
Config option selicon_cols has been dropped without substitution, the render engine now shows as many images in a row as fit into the view.

Example to enable the icon display:

'select_single_5' => [
    'label' => 'select_single_5',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingle',
        'items' => [
            ['foo 1', 'foo1', 'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg'],
            ['foo 2', 'foo2', 'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg'],
        ],
        'fieldWizard' => [
            'selectIcons' => [
                'disabled' => false,
            ],
        ],
    ],
],

type=select with renderType=multipleSideBySide

Configuration option changes of the renderType=multipleSideBySide element are similar to the type=group changes. In detail, the following changes have been applied:

Config option selectedListStyle has been dropped without substitution.
Wizards wizard_add, wizard_edit and wizard_list have been changed to fieldControl and must be enabled per element. All options are still valid, but the system tries to determine sane fallback values if no options are given. For example, the table option of wizard_add and wizard_list fall back to the value of foreign_table if not explicitly given.

Example configuration of a multipleSideBySide field before change:

'select_multiplesidebyside_6' => [
    'exclude' => 1,
    'label' => 'select_multiplesidebyside_6',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectMultipleSideBySide',
        'foreign_table' => 'tx_styleguide_staticdata',
        'rootLevel' => 1,
        'size' => 5,
        'autoSizeMax' => 20,
        'wizards' => [
            '_VERTICAL' => 1,
            'edit' => [
                'type' => 'popup',
                'title' => 'edit',
                'module' => [
                    'name' => 'wizard_edit',
                ],
                'icon' => 'actions-open',
                'popup_onlyOpenIfSelected' => 1,
                'JSopenParams' => 'height=350,width=580,status=0,menubar=0,scrollbars=1',
            ],
            'add' => [
                'type' => 'script',
                'title' => 'add',
                'icon' => 'actions-add',
                'module' => [
                    'name' => 'wizard_add',
                ],
                'params' => [
                    'table' => 'tx_styleguide_staticdata',
                    'pid' => '0',
                    'setValue' => 'prepend',
                ],
            ],
            'list' => [
                'type' => 'script',
                'title' => 'list',
                'icon' => 'actions-system-list-open',
                'module' => [
                    'name' => 'wizard_list',
                ],
                'params' => [
                    'table' => 'tx_styleguide_staticdata',
                    'pid' => '0',
                ],
            ],
        ],
    ],
],

Example after:

'select_multiplesidebyside_6' => [
    'exclude' => 1,
    'label' => 'select_multiplesidebyside_6 wizards',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectMultipleSideBySide',
        'foreign_table' => 'tx_styleguide_staticdata',
        'rootLevel' => 1,
        'size' => 5,
        'autoSizeMax' => 20,
        'fieldControl' => [
            'editPopup' => [
                'disabled' => false,
            ],
            'addRecord' => [
                'disabled' => false,
            ],
            'listModule' => [
                'disabled' => false,
            ],
        ],
    ],
],

type=group

This element got most changes in this series. A number of options have been fine-tuned and got better default values:

Similar to type=select with type=multipleSideBySide, the three wizards wizard_add, wizard_edit and wizard_list have been changed to fieldControl and are disabled by default.
Config option selectedListStyle has been dropped without substitution.
The suggest wizard has been directly embedded in type=group and has been enabled by default for internal_type=db elements. It can be disabled with hideSuggest=true and options of the suggest can be hand over in config option suggestOptions.
The config option show_thumbs showed two different things in the past: With internal_type=db, it displayed the list of selected records as a table below the element, with internal_type=file it rendered thumbnails of selected files and displayed the below the element. show_thumbs has been dropped, the functionality has been transferred to fieldWizard as recordsOverview and fileThumbnails respectively and are enabled by default. They can be disabled by setting disabled=true.
The config option disable_controls has been obsoleted, single parts of the group element can be disabled by adding disabled=true to the according fieldControl or fieldWizard.

Example of a typical group field before:

'group_db_1' => [
    'label' => 'group_db_1',
    'config' => [
        'type' => 'group',
        'internal_type' => 'db',
        'allowed' => 'be_users,be_groups',
        'wizards' => [
            'edit' => [
                'type' => 'popup',
                'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.edit',
                'module' => [
                    'name' => 'wizard_edit',
                ],
                'popup_onlyOpenIfSelected' => 1,
                'icon' => 'actions-open',
                'JSopenParams' => 'height=350,width=580,status=0,menubar=0,scrollbars=1'
            ],
            'add' => [
                'type' => 'script',
                'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.createNewPage',
                'icon' => 'actions-add',
                'params' => [
                    'table' => 'be_users',
                    'pid' => 0,
                    'setValue' => 'append'
                ],
                'module' => [
                'name' => 'wizard_add'
                ],
            ],
            'list' => [
                'type' => 'script',
                'title' => 'LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.list',
                'icon' => 'actions-system-list-open',
                'params' => [
                    'table' => 'be_groups',
                    'pid' => '0'
                ],
                'module' => [
                    'name' => 'wizard_list'
                ]
            ]
        ],
    ],
],

Example after:

'group_db_1' => [
    'label' => 'group_db_1',
    'config' => [
        'type' => 'group',
        'internal_type' => 'db',
        'allowed' => 'be_users,be_groups',
        'fieldControl' => [
            'editPopup' => [
                'disabled' => false,
            ],
            'addRecord' => [
                'disabled' => false,
            ],
            'listModule' => [
                'renderType' => 'listModule',
                'options' => [
                'disabled' => false,
            ],
        ],
    ],
],

Disable other parts of type=group:

'group_db_1' => [
    'label' => 'group_db_1',
    'config' => [
        'type' => 'group',
        'internal_type' => 'db',
        'allowed' => 'be_users,be_groups',
        'fieldControl' => [
            // Disable element browser icon
            'elementBrowser' => [
                'disabled' => true,
            ],
            // Disable insert from clipboard icon
            'insertClipboard' => [
                'disabled' => true,
            ],
        ],
        'fieldWizard => [
            // Disable button list of allowed tables
            'tableList' => [
                'disabled' => true,
            ],
            // Disable list of allowed file types
            'fileTypeList' => [
                'disabled' => true,
            ],
            // Disable thumbnail view of selected files
            'fileThumbnails' => [
                'disabled' => true,
            ],
            // Disable table view of selected records
            'recordsOverview' => [
                'disabled' => true,
            ],
            // Disable direct file upload button
            'fileUpload' => [
                'disabled' => true,
            ],
        ],
    ],
],

Impact

Using old TCA settings as outlined above will throw a deprecation warnings.

Affected Installations

Most installations are affected by this change.

Migration

An automatic TCA migration transfers from old TCA settings to new ones and throws deprecation log entries with hints which changes should be incorporated. For flex form data structure definitions, the TCA migration is called when opening an according record and logs, too.