..  include:: /Includes.rst.txt

..  _palettes:

==========================
Grouping fields (palettes)
==========================

..  versionchanged:: 14.0
    :changelog: breaking-107789-1729603200

    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
:ref:`['types'] section <types>`.

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


..  contents:: Table of Contents

..  _palettes-examples:

Examples
========

A location groups its address and its coordinates in palettes:

..  figure:: /Images/Conference/PaletteLocation.png
    :alt: The address and the coordinates of a location
    :class: with-shadow

    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:

..  literalinclude:: /CodeSnippets/my_extension/Configuration/TCA/Overrides/405-tx_myextension_location-address.php
    :caption: EXT:my_extension/Configuration/TCA/Overrides/405-tx_myextension_location-address.php
    :emphasize-lines: 22-25

The palettes then get referenced in the `types` section:

..  literalinclude:: /CodeSnippets/my_extension/Configuration/TCA/Overrides/405-tx_myextension_location-address.php
    :caption: EXT:my_extension/Configuration/TCA/Overrides/405-tx_myextension_location-address.php
    :emphasize-lines: 26-31

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:

..  literalinclude:: /CodeSnippets/my_extension/Configuration/TCA/Overrides/298-tx_myextension_talk-feedback.php
    :caption: EXT:my_extension/Configuration/TCA/Overrides/298-tx_myextension_talk-feedback.php
    :visible-lines: 3, 47-63
    :emphasize-lines: 48, 60

..  _palettes-properties:

Properties of `palettes` section of TCA
=======================================

..  confval-menu::
    :name: palettes
    :display: table
    :type:
    :Scope:

    ..  include:: _Properties/_*.rst.txt
        :show-buttons: