Grouping fields (palettes)

Changed in version 14.0 Breaking: #107789 - Core TCA and user settings showitem strings use short form references

TYPO3 Core TCA configurations have been updated to use short form translation reference formats (for example core.form.tabs:*) instead of the full LLL:EXT: path format in showitem strings.

Custom extensions that programmatically manipulate TCA showitem strings from core tables and expect the full LLL:EXT: path format will break.

If editing records in the backend, all fields are usually displayed after each other in single rows. Palettes provide a way to display multiple fields next to each other if the browser window size allows this. They can be used to group multiple related fields in one combined section.

Each palette has a name and can be referenced by name from within the ['types'] section.

To modify existing palettes you can use the utility functions \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addFieldsToPalette and ExtensionManagementUtility::addFieldsToAllPalettesOfField.

Table of Contents

Examples

A location groups its address and its coordinates in palettes:

The address and the coordinates of a location

Palettes get defined in the section palettes of the tables TCA array. The address palette puts the ZIP code and the city on a line of their own:

        EXT:my_extension/Configuration/TCA/Overrides/405-tx_myextension_location-address.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_location', [
  'street' => [
    'label' => 'my_extension.db:location.street',
    'config' => [
      'type' => 'input',
    ],
  ],
  'zip' => [
    'label' => 'my_extension.db:location.zip',
    'config' => [
      'type' => 'input',
      'size' => 10,
    ],
  ],
]);
$GLOBALS['TCA']['tx_myextension_location']['palettes']['address'] = [
  'label' => 'my_extension.db:location.palette.address',
  'showitem' => 'street, --linebreak--, zip, city',
];
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_location',
  '--palette--;;address',
  '',
  'replace:city',
);

The palettes then get referenced in the types section:

        EXT:my_extension/Configuration/TCA/Overrides/405-tx_myextension_location-address.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_location', [
  'street' => [
    'label' => 'my_extension.db:location.street',
    'config' => [
      'type' => 'input',
    ],
  ],
  'zip' => [
    'label' => 'my_extension.db:location.zip',
    'config' => [
      'type' => 'input',
      'size' => 10,
    ],
  ],
]);
$GLOBALS['TCA']['tx_myextension_location']['palettes']['address'] = [
  'label' => 'my_extension.db:location.palette.address',
  'showitem' => 'street, --linebreak--, zip, city',
];
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_location',
  '--palette--;;address',
  '',
  'replace:city',
);

It is also possible to define the label of a palette directly in the palette definition. Declaring the label in an 'palettes' array can reduce boilerplate declarations if a palette is used over and over again in multiple types. If a label is defined for a palette this way, it is always displayed. Setting a specific label in the 'types' array for a palette overrides the default label that was defined within the 'palettes' array. There is no way to unset a label that is set within the 'palettes' array. It will always be displayed.

The feedback palette of a talk has the label "Feedback". The record type workshop shows the palette with a label of its own:

        EXT:my_extension/Configuration/TCA/Overrides/298-tx_myextension_talk-feedback.php
    

<?php

use MyVendor\MyExtension\Backend\FeedbackCountFormatter;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

// The feedback form of the website stores these values, the editors only
// read them
ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'feedback_opened' => [
    'label' => 'my_extension.db:talk.feedback_opened',
    'config' => [
      'type' => 'none',
      // For example "05/12/2027 (5 days)"
      'format' => 'date',
      'format.' => [
        'strftime' => true,
        'option' => '%x',
        'appendAge' => true,
      ],
    ],
  ],
  'rating' => [
    'label' => 'my_extension.db:talk.rating',
    'config' => [
      'type' => 'none',
      // The average of all ratings, for example "4.3"
      'format' => 'float',
      'format.' => [
        'precision' => 1,
      ],
    ],
  ],
  'feedback_count' => [
    'label' => 'my_extension.db:talk.feedback_count',
    'config' => [
      'type' => 'none',
      // For example "12 attendees"
      'format' => 'user',
      'format.' => [
        'userFunc' => FeedbackCountFormatter::class . '->format',
      ],
    ],
  ],
]);
$GLOBALS['TCA']['tx_myextension_talk']['palettes']['feedback'] = [
  'label' => 'my_extension.db:talk.feedback',
  'showitem' => 'feedback_opened, rating, feedback_count',
];
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  '--palette--;;feedback',
  'talk,keynote',
  'after:comments_closed',
);
// In a workshop, the participants give the feedback
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  '--palette--;my_extension.db:talk.feedback.workshop;feedback',
  'workshop',
  'after:comments_closed',
);

Properties of `palettes` section of TCA

Name	Type	Scope
description	string
isHiddenPalette	boolean
label	string
showitem	string (list of field names)

description

Type: string
TCA path: $GLOBALS['TCA'][$table]['palettes'][$palette]['description']

Allows to display a localized description text into the palette declaration. It will be displayed below the palette label.

This additional help text can be used to clarify some field usages directly in the UI.

Note

In contrast to the palette label, the description property can not be overwritten on a record type basis.

Example

The coordinates of a location with a description

        EXT:my_extension/Configuration/TCA/Overrides/415-tx_myextension_location-coordinates.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_location', [
  'latitude' => [
    'label' => 'my_extension.db:location.latitude',
    'config' => [
      'type' => 'number',
      'scale' => 6,
    ],
  ],
  'longitude' => [
    'label' => 'my_extension.db:location.longitude',
    'config' => [
      'type' => 'number',
      'scale' => 6,
    ],
  ],
]);
$GLOBALS['TCA']['tx_myextension_location']['palettes']['coordinates'] = [
  'label' => 'my_extension.db:location.palette.coordinates',
  'description' => 'my_extension.db:location.palette.coordinates.description',
  'showitem' => 'latitude, longitude',
];
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_location',
  '--palette--;;coordinates',
  '',
  'after:country',
);

isHiddenPalette

Type: boolean
TCA path: $GLOBALS['TCA'][$table]['palettes'][$palette]['isHiddenPalette']

If set to true, this palette will never be shown, but the fields of the palette are technically rendered as hidden elements in FormEngine.

This is sometimes useful when you want to set a field's value by JavaScript from another user-defined field. You can also use it along with the IRRE (TCA columns type inline) foreign_selector feature if you don't want the relation field to be displayed (it must be technically present and rendered though, that's why you should put it to a hidden palette in that case).

Note

The "isHiddenPalette" concept is more a hack than a solution in current FormEngine code. It has been introduced for the "FAL" file resource handling to have virtual fields which can be handled in JavaScript but are not displayed to the editor. It comes with the price of a bunch of HTML that is disabled via CSS if editing those records in the backend. The core will sooner or later reconsider this solution and substitute it with something more appropriate. Extension authors should stay away from this property if possible to not run into upgrade troubles if that happens.

label

Type: string
TCA path: $GLOBALS['TCA'][$table]['palettes'][$palette]['label']

Allows to display a localized label text as a dedicated entry into the palette declaration, instead as a part of the types configuration. By using the explicit label entry, code duplication upon reusing existing palettes can be reduced. The label is always shown with the palette, no matter where it is referenced.

The palette with the coordinates of a location has its own label, so the types reference it with --palette--;;coordinates, without a label:

        EXT:my_extension/Configuration/TCA/Overrides/415-tx_myextension_location-coordinates.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_location', [
  'latitude' => [
    'label' => 'my_extension.db:location.latitude',
    'config' => [
      'type' => 'number',
      'scale' => 6,
    ],
  ],
  'longitude' => [
    'label' => 'my_extension.db:location.longitude',
    'config' => [
      'type' => 'number',
      'scale' => 6,
    ],
  ],
]);
$GLOBALS['TCA']['tx_myextension_location']['palettes']['coordinates'] = [
  'label' => 'my_extension.db:location.palette.coordinates',
  'description' => 'my_extension.db:location.palette.coordinates.description',
  'showitem' => 'latitude, longitude',
];
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_location',
  '--palette--;;coordinates',
  '',
  'after:country',
);

showitem

Type: string (list of field names)
Required: true
TCA path: $GLOBALS['TCA'][$table]['palettes'][$palette]['showitem']

Specifies which fields are displayed in which order in the palette.

This string is a comma separated list of field names from ['columns'] section, each field can optionally have a second, semicolon separated field to override the default label property of the field.

The access palette of a conference gives the fields starttime and endtime labels of their own:

EXT:my_extension/Configuration/TCA/tx_myextension_conference.php

<?php

return [
  'ctrl' => [
    'title' => 'my_extension.db:conference',
    'label' => 'title',
    'descriptionColumn' => 'internal_notes',
    'default_sortby' => 'conference_date DESC',
    'tstamp' => 'tstamp',
    'crdate' => 'crdate',
    'delete' => 'deleted',
    'editlock' => 'editlock',
    'enablecolumns' => [
      'disabled' => 'hidden',
      'starttime' => 'starttime',
      'endtime' => 'endtime',
      'fe_group' => 'fe_group',
    ],
    'languageField' => 'sys_language_uid',
    'transOrigPointerField' => 'l10n_parent',
    'transOrigDiffSourceField' => 'l10n_diffsource',
    'translationSource' => 'l10n_source',
    'versioningWS' => true,
    'origUid' => 't3_origuid',
    'iconfile' => 'EXT:my_extension/Resources/Public/Icons/Conference.svg',
    'security' => [
      'ignorePageTypeRestriction' => true,
    ],
  ],
  'columns' => [
    'title' => [
      'label' => 'my_extension.db:conference.title',
      'config' => [
        'type' => 'input',
        'required' => true,
        'max' => 255,
        'eval' => 'trim',
      ],
    ],
    'conference_date' => [
      'label' => 'my_extension.db:conference.conference_date',
      'config' => [
        'type' => 'datetime',
        'format' => 'date',
        'required' => true,
      ],
    ],
    'internal_notes' => [
      'label' => 'my_extension.db:conference.internal_notes',
      'config' => [
        'type' => 'text',
        'rows' => 3,
      ],
    ],
  ],
  // The fields of the other tabs are added in Configuration/TCA/Overrides/
  'types' => [
    '0' => [
      'showitem' => '
        title, conference_date,
        --div--;my_extension.db:tab.program,
        --div--;my_extension.db:tab.details,
        --div--;core.form.tabs:categories,
        --div--;core.form.tabs:access,
          hidden, --palette--;;access, fe_group, editlock,
        --div--;core.form.tabs:language,
          --palette--;;language,
        --div--;my_extension.db:tab.comments,
        --div--;core.form.tabs:notes,
          internal_notes,
      ',
    ],
  ],
  'palettes' => [
    'access' => [
      'label' => 'core.form.palettes:access',
      // The labels of the fields tell the editors what the dates are for
      'showitem' => '
        starttime;my_extension.db:conference.starttime,
        endtime;my_extension.db:conference.endtime,
      ',
    ],
    'language' => [
      'showitem' => 'sys_language_uid, l10n_parent',
    ],
  ],
];

Instead of a field name, the special keyword --linebreak-- can be used to place groups of fields on single lines. Note this line grouping only works well if the browser window size allows multiple fields next to each other, if the width is not sufficient the fields will wrap below each other anyways.

The address palette of a location shows the street on a line of its own:

        EXT:my_extension/Configuration/TCA/Overrides/405-tx_myextension_location-address.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_location', [
  'street' => [
    'label' => 'my_extension.db:location.street',
    'config' => [
      'type' => 'input',
    ],
  ],
  'zip' => [
    'label' => 'my_extension.db:location.zip',
    'config' => [
      'type' => 'input',
      'size' => 10,
    ],
  ],
]);
$GLOBALS['TCA']['tx_myextension_location']['palettes']['address'] = [
  'label' => 'my_extension.db:location.palette.address',
  'showitem' => 'street, --linebreak--, zip, city',
];
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_location',
  '--palette--;;address',
  '',
  'replace:city',
);

Caution

A field name must only appear once in the entire record. Do not reference a single field within the showitem list of a types section and again in a palette used in the same type. Do not use a field in multiple palettes referenced in a type, or multiple times in one palette.

Grouping fields (palettes)

Examples

Properties of palettes section of TCA

Properties of `palettes` section of TCA