Item group API methods

Adding custom select item groups

Registration of a select item group takes place in Configuration/TCA/tx_myextension_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.

EXT:my_extension/Configuration/TCA/Overrides/600-tt_content-conference_list.php

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
use TYPO3\CMS\Extbase\Utility\ExtensionUtility;

defined('TYPO3') or die();

// A group of its own in the content element wizard and the type select
ExtensionManagementUtility::addTcaSelectItemGroup(
  'tt_content',
  'CType',
  'conference',
  'my_extension.db:tt_content.group.conference',
  'after:plugins',
);

ExtensionUtility::registerPlugin(
  'MyExtension',
  'ConferenceList',
  'my_extension.db:plugin.conferencelist.title',
  'my-extension-conference-list',
  'conference',
  'my_extension.db:plugin.conferencelist.description',
  'FILE:EXT:my_extension/Configuration/FlexForms/ConferenceList.xml',
);

// The plugin lists the upcoming conferences without further settings, so
// a new plugin is saved at once, with its header hidden
$GLOBALS['TCA']['tt_content']['types']['myextension_conferencelist']['creationOptions'] = [
  'defaultValues' => [
    'header_layout' => '100',
  ],
  'saveAndClose' => true,
];

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, the group key of the item specifies the id of the item group.

EXT:my_sitepackage/Configuration/TCA/Overrides/tx_myextension_talk.php

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

// The conferences of this site also address agencies, so the audience of
// a talk gets an item for them in the group of the business audience
ExtensionManagementUtility::addTcaSelectItem(
  'tx_myextension_talk',
  'audience',
  [
    'label' => 'my_sitepackage.db:talk.audience.agencies',
    'value' => 'agencies',
    'group' => 'business',
  ],
  'decision_makers',
  'after',
);

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 or 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.