New TCA Types in TYPO3 v12

Easier configuration for your custom records

|Benni Mack
Feature Image for Article New TCA Types in TYPO3 v12

In this blog post, we're delving into more user-friendly methods for configuring TCA, the powerhouse behind all the editing and rendering logic derived from database entries in TYPO3. 

What is TCA? And why should I care?

At the core of TYPO3 lies TCA, an acronym for "Table Configuration Array" - a PHP-based layer that unifies the definition of data that is accessible and manipulatable within TYPO3. This layer governs the structure of data storage in the database, extending its capabilities to include additional fields for content creators and enabling flexible rendering in TypoScript via the frontend. It's crucial to grasp these concepts if you want to extend TYPO3 because TCA defines everything from Pages and Content Elements to Addresses and Website User Records. Explore more about TCA and its concepts in the TCA Reference guide on docs.typo3.org.

In TYPO3, TCA imparts semantic value to database tables and fields. For instance, if you want editors to choose from three valid options, TCA facilitates presenting the options as a dropdown in the admin interface. While a database field alone lacks this contextual meaning, TCA steps in to provide it. Any extension can seamlessly introduce new fields or even entire database tables for editing within the TYPO3 backend. So, if you've ever envisioned extending beyond TYPO3's base framework, this serves as an excellent starting point.

Previous pain points with TCA

Given that TCA is an extensive PHP-compiled array, its high degree of flexibility allows for substantial manipulation within TYPO3 extensions. However, TCA carries the weight of TYPO3's extensive history, and for newcomers, its semantics haven't always been straightforward. For instance, understanding that a field of type input could possess an eval option like password to indicate its treatment as a password input field for editors is not obvious. And the information not being stored with the plain value in the database adds complexity. Furthermore, the term `input` was occasionally applied to fields intended for selecting specific dates or times, contributing to a convoluted interpretation of its meaning.

Smarter types with less confusing options to the rescue

Within TYPO3 v11, several novel TCA types made their debut, including type=language for facilitating the selection of available languages for a site, and type=category in place of the generic type=select with renderType=selectTree and a reference to the database table sys_category. TYPO3 v12 has taken these concepts to new heights, further expanding their scope and functionality.

Say hello to new types

Rather than navigating the potentially error-prone task of writing type=input with eval in TCA, in version 12, extension authors can confidently leverage the following new TCA types for defining fields:

  • color 
  • datetime
  • email
  • file
  • folder
  • json
  • link
  • number
  • password
  • uuid


The official TYPO3 documentation lists all the field types in the TCA Reference guide. 

The benefits of streamlined code

The uuid and json types are entirely new, and were introduced to cater to specific use cases - notably in the context of the new system extensions "Reactions" and "Webhooks." All other fields have been meticulously re-defined, simplifying the lives of existing TYPO3 integrators and extension authors everywhere.

Let’s look at an example. Color denotes a selection of any HEX color value. This was previously defined via type=input and renderType=colorpicker. Now, specific components are implicitly defined through the use of type=color. Less code to write delivers a much more streamlined coding process.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// Before

'a_color_field' => [
    'label' => 'Color field',
    'config' => [
        'type' => 'input',
        'renderType' => 'colorpicker',
        'size' => 20,
        'max' => 1024,
        'eval' => 'trim',
        'valuePicker' => [
            'items' => [
                ['typo3 orange', '#FF8700'],
            ],
        ],
    ],
],

// After
'a_color_field' => [
    'label' => 'Color field',
    'config' => [
        'type' => 'color',
        'size' => 20,
        'valuePicker' => [
            'items' => [
                ['typo3 orange', '#FF8700'],
            ],
        ],
    ]
]

Similar instances of condensing the TCA definition, originally managed through "eval" with specific options, have now been transitioned to custom TCA types. Among my top favorites are “link” and “file”.

Type link

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// Before

'cta_link' => [
    'label' => 'CTA Link',
    'config' => [
        'type' => 'input',
        'renderType' => 'inputLink',
        'required' => true,
        'max' => 1024,
        'eval' => 'trim,
        'fieldControl' => [
            'linkPopup' => [
                'disabled' => true,
                'options' => [
                    'title' => 'Browser title',
                    'blindLinkFields' => 'class,target,title',
                    'blindLinkOptions' => 'mail,folder,file,telephone',
                ],
            ],
        ],
        'softref' => 'typolink',
    ],
],

// After
'cta_link' => [
    'label' => 'CTA Link',
    'config' => [
        'type' => 'link',
        'required' => true,
        'allowedTypes' => ['page', 'url', 'record'],
        'appearance' => [
            'enableBrowser' => false,
            'browserTitle' => 'Browser title',
            'allowedOptions' => ['params', 'rel'],
        ],
    ]
]

Type “File”

Writing relations to files used to be a specialty, but is now simplified via a custom TCA type. Here is a typical example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Before
'columns' => [
    'image' => [
        'label' => 'My image',
        'config' => \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::getFileFieldTCAConfig(
            'image',
            [
                'maxitems' => 6,
            ],
            $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']
        ),
    ],
],

// After
'columns' => [
    'image' => [
        'label' => 'My image',
        'config' => [
            'type' => 'file',
            'maxitems' => 6,
            'allowed' => 'common-image-types'
        ],
    ],
],

Effortlessly migrate your existing installation

TYPO3 comes equipped with an automatic migration process for your existing TCA to seamlessly transition to the new structure, alleviating any concerns during the upgrading process.

At b13, we staunchly advocate for Rector for TYPO3 — a tool designed to autonomously migrate your extension code, including TCA, ensuring it aligns with the future-proof syntax.

Need assistance? We’re here to help!

If you still struggle with upgrading your installation to the next version, give us a call and we’ll give you a helping hand.

Get in touch!

previous article: What enterprises should expect when they partner with a new agency next article: Introduction to Content-Security-Policy (CSP)