Add more fields to content elements in TYPO3

In the last section of this series, we created our content element. In this section, I explain how to add more fields to the content element.

This article is part of a series on content elements in TYPO3, here are links to the other parts of this series.

  1. Create a basic content element
  2. Add more fields to content elements (this article)
  3. creating inline records (coming soon)

Add additional fields to TYPO3 content element

Which fields are available in a content element and how they get saved is defined using TCA (Table Configuration Array).

TCA is a big array which defines what fields are visible in the backend and how they get saved. It is stored in $GLOBALS['TCA'] global variable.

TCA definition for the content elements

Every content elements is defined in a php file in Configuration/TCA/Overrides/ folder. Name of the file should start with tt_content. It can have any other text appended to it. For example, the file for a slider content element may be tt_content_my_slider.php.

The TCA definition file (tt_content_my_slider) file does two things.

1: adds new TCA item using TYPO3’s addTcaSelectItem utility method.

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTcaSelectItem(
    'tt_content',
    'CType',
    [
        'My Slider',
        'my_slider',
        'my-slider',
    ],
    'textmedia',
    'after'
);

2: It adds new items (TCA definitions) to the $GLOBALS['TCA']['tt_content']['types'] array.

$GLOBALS['TCA']['tt_content']['types']['my_awesome_new_content_element'] = [
    'showitem' => 'here comes the actual TCA definition'
];

The showitem key in the definition array has a special syntax, lets learn it.

The showitem syntax

Fields can be defined in a comma-separated list of values. for example, to show header and assets (asset is a field in tt_content table which stores image), we would write 'header, assets'.

To define a custom label for a field, add a semicolon after the field name. for example header;my awesome header defines “my awesome header” as the label of the header field.

$GLOBALS['TCA']['tt_content']['types']['my_extension_my_slider'] = [
    'showitem' => 'header;my awesome header, assets'
];

palette

Palettes are used to divide fields into sections, there are a number of built-in palettes to use (for example general).

The example below adds assets to the general palette.

$GLOBALS['TCA']['tt_content']['types']['my_extension_my_slider'] = [
    'showitem' => '--palette--;;general,slider header, assets,'
];

You can define your own palettes as well. Pallets help you keep your code readable by dividing them into small pieces and keep backend of your content element neat.

The following example defines a new palette header_and_image to the tt_content table and adds header and assets field to it.

$GLOBALS['TCA']['tt_content']['palettes']['header_and_image'] = [
    'showitem' => 'header,assets,--linebreak--',
];

Now the palette can be used like built-in palettes.

$GLOBALS['TCA']['tt_content']['types']['my_extension_my_slider'] = [
    'showitem' => 'header_and_image'
];

linebreak

The --linebreak-- keyword adds a line break.

In the example below a line break is added after the header field.

$GLOBALS['TCA']['tt_content']['palettes']['header_and_image'] = [
    'showitem' => 'header,--linebreak--,assets,--linebreak--',
];

tab

The --tab-- keyword divides fields in tabs. The following example adds a new tab called “Slider images” and adds assets fields to it.

$GLOBALS['TCA']['tt_content']['types']['my_extension_my_slider'] = [
    'showitem' => 'header,--div--;Slider images,assets'
];

Custom fields

Adding custom field is not different than using built-in fields, you only need to add TCA column definition for it using addTCAcolumns method and add a database definition for it.

For example, let’s define a new field called “custom background color” for a content element.

First create a file ext_tables.sql in the root folder of your extension (if already not exists ) and add the snippet below to it.

CREATE TABLE tt_content (
    my_extension_background_color varchar(22) DEFAULT '' NOT NULL,
);

his is normal SQL syntax. The only difference is it uses CREATE statement, although it updates existing tt_content table.

Now define the TCA column definition for the content elements.

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns('tt_content', [
    'my_extension_background_color' => [
        'exclude' => 0,
        'label' => 'color',
        'config' => [
            'type' => 'text',
        ],
    ],
]);

The my_extension_background_color field can now be used like the built in fields.

$GLOBALS['TCA']['tt_content']['types']['my_extension_my_slider'] = [
    'showitem' => '--palette--;;general,header,assets,my_extension_background_color'
];

Configure how the fields look and behave

Let’s say you want to enable the rich text editor in a text field or define the maximum number of images a user can add, you can configure all these using columnsOverrides key. Add columnsOverrides key to content element definition array.

$GLOBALS['TCA']['tt_content']['types']['my_extension_my_slider'] = [
    'showitem' => ' here comes field definitions',
     'columnsOverrides' => [/* here comes the columnsOverrides configuration */],
];

In this example we override header to allow rich text editing.

$GLOBALS['TCA']['tt_content']['types']['my_extension_my_slider'] = [
    'showitem' => 'header,assets',
     'columnsOverrides' => [
            'header' => [
                'config' => [
                    'enableRichtext' => true,
                    'richtextConfiguration' => 'default',
                ],
            ],
        ],
];

When adding your custom content element, you can pass all the configuration at definition time. In the example below we set the renderType to colorpicker in our my_extension_background_color field.

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns('tt_content', [
    'my_extension_background_color' => [
        'exclude' => 0,
        'label' => 'color',
        'config' => [
            'type' => 'text',
            'renderType' => 'colorpicker',
        ],
    ],
]);

For all possible configurations check out TCA documentation.

A few things to consider

Use built-in fields, when you can:

While it is easy to define custom fields, you should try to use the builtin fields when possible. It keeps the tt_content table tidy. Switching between CTypes keep the data when builtin fields are used. for example, if use the builtin header field for your “slider header”, switching to textmedia does not reset the header value.

Do not use built-in fields for totally irrelevant data:

Avoid using built-in fields when data stored in it is completely irrelevant to their names. For example, if you have a “slider background color”, subheader field should not be used for it.