itemGroups

New in version 10.4

Starting with TYPO3 v10.4 item groups can be used in select fields to group items.

itemGroups
Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

type

array

Scope

Display / Proc.

RenderType

all

Contains an array of key-value pairs. The key contains the id of the item group, the value contains the label of the item group or its language reference.

Only groups containing items will be displayed. In the select field first all items with no group defined are listed then the item groups in the order of their definition, each group with the corresponding items.

In the renderType selectSingle item groups are rendered as <optgroup>.

In the renderType selectCheckbox the groups are displayed as accordions containing the check boxes.

In other renderTypes a non selectable item with the group name gets displayed.

API methods

Adding custom select item groups

Registration of a select item group takes place in Configuration/TCA/tx_mytable.php for new TCA tables, and in Configuration/TCA/Overrides/a_random_core_table.php for modifying an existing TCA definition.

For existing select fields additional item groups can be added via the api method ExtensionManagementUtility::addTcaSelectItemGroup.

ExtensionManagementUtility::addTcaSelectItemGroup(
    'tt_content',
    'CType',
    'sliders',
    'LLL:EXT:my_slider_mixtape/Resources/Private/Language/locallang_tca.xlf:tt_content.group.sliders',
    'after:lists'
);
Copied!

When adding a new select field, itemGroups should be added directly in the original TCA definition without using the API method. Use the API within TCA/Configuration/Overrides/ files to extend an existing TCA select field with grouping.

Attaching select items to item groups

Using the API method ExtensionManagementUtility::addTcaSelectItem a a fourth parameter in the array can be used to specify the id of the item group.

ExtensionManagementUtility::addTcaSelectItem(
    'tt_content',
    'CType',
    [
        'LLL:EXT:my_slider_mixtape/Resources/Private/Locallang/locallang_tca.xlf:tt_content.CType.slickslider',
        'slickslider',
        'EXT:my_slider_mixtape/Resources/Public/Icons/slickslider.png',
        'sliders'
    ]
);
Copied!

History

With the introduction of the itemGroups the TCA column type select has a clean API to group items for dropdowns in FormEngine. This was previously handled via placeholder --div-- items, which then rendered as <optgroup> HTML elements in a dropdown.

In larger installations or TYPO3 instances with lots of extensions, Plugins (tt_content.list_type), Content Types (tt_content.CType) or custom Page Types (pages.doktype) drop down lists could grow large and adding item groups caused tedious work for developers or integrators. Grouping can now be configured on a per-item basis. Custom groups can be added via an API or when defining TCA for a new table.

Examples

SelectSingle field with itemGroups

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php
[
    'columns' => [
        'select_single_16' => [
            'exclude' => 1,
            'label' => 'select_single_16',
            'description' => 'itemGroups',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'item 1',
                        1,
                        '',
                        'group1',
                    ],
                    [
                        'item 2',
                        2,
                        '',
                        'group1',
                    ],
                    [
                        'item 3',
                        3,
                        '',
                        'group3',
                    ],
                    [
                        'item 4',
                        3,
                    ],
                ],
                'itemGroups' => [
                    'group1' => 'Group 1 with items',
                    'group2' => 'Group 2 with no items',
                    'group3' => 'Group 3 with items',
                ],
            ],
        ],
    ],
]
Copied!

SelectSingle field with itemGroups, size=6

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php
[
    'columns' => [
        'select_single_17' => [
            'exclude' => 1,
            'label' => 'select_single_16',
            'description' => 'itemGroups, size=6',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'item 1',
                        1,
                        '',
                        'group1',
                    ],
                    [
                        'item 2',
                        2,
                        '',
                        'group1',
                    ],
                    [
                        'item 3',
                        3,
                        '',
                        'group3',
                    ],
                    [
                        'item 4',
                        3,
                    ],
                ],
                'itemGroups' => [
                    'group1' => 'Group 1 with items',
                    'group2' => 'Group 2 with no items',
                    'group3' => 'Group 3 with items',
                ],
                'size' => 6,
            ],
        ],
    ],
]
Copied!

SelectSingleBox field with itemGroups

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php
[
    'columns' => [
        'select_singlebox_3' => [
            'exclude' => 1,
            'label' => 'select_singlebox_3',
            'description' => 'itemGroups',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingleBox',
                'items' => [
                    [
                        'item 1',
                        1,
                        '',
                        'group1',
                    ],
                    [
                        'item 2',
                        2,
                        '',
                        'group1',
                    ],
                    [
                        'item 3',
                        3,
                        '',
                        'group3',
                    ],
                    [
                        'item 4',
                        3,
                    ],
                ],
                'itemGroups' => [
                    'group1' => 'Group 1 with items',
                    'group2' => 'Group 2 with no items',
                    'group3' => 'Group 3 with items',
                ],
            ],
        ],
    ],
]
Copied!

SelectCheckbox field with itemGroups

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php
[
    'columns' => [
        'select_checkbox_7' => [
            'exclude' => 1,
            'label' => 'select_checkbox_7',
            'description' => 'itemGroups',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectCheckBox',
                'items' => [
                    [
                        'foo 1',
                        1,
                        '',
                        'group1',
                    ],
                    [
                        'foo 2',
                        2,
                        'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg',
                        'group1',
                    ],
                    [
                        'foo 3',
                        3,
                        'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg',
                    ],
                    [
                        'foo 4',
                        4,
                    ],
                    [
                        'foo 5',
                        1,
                        '',
                        'group3',
                    ],
                ],
                'itemGroups' => [
                    'group1' => 'Group 1 with items',
                    'group2' => 'Group 2 with no items',
                    'group3' => 'Group 3 with items',
                ],
            ],
        ],
    ],
]
Copied!

Multiple side by side field with itemGroups

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php
[
    'columns' => [
        'select_multiplesidebyside_10' => [
            'exclude' => 1,
            'label' => 'select_multiplesidebyside_1 autoSizeMax=10, size=3 description',
            'description' => 'field description',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectMultipleSideBySide',
                'items' => [
                    [
                        'item 1',
                        1,
                        '',
                        'group1',
                    ],
                    [
                        'item 2',
                        2,
                        '',
                        'group1',
                    ],
                    [
                        'item 3',
                        3,
                        '',
                        'group3',
                    ],
                    [
                        'item 4',
                        4,
                    ],
                ],
                'itemGroups' => [
                    'group1' => 'Group 1 with items',
                    'group2' => 'Group 2 with no items',
                    'group3' => 'Group 3 with items',
                ],
                'size' => 3,
                'autoSizeMax' => 10,
                'multiple' => true,
            ],
        ],
    ],
]
Copied!