TCA column type category

New in version 11.4

The TCA field type called category has been added to TYPO3 Core. Its main purpose is to simplify the TCA configuration when adding a category tree to a record. It therefore supersedes the CategoryRegistry as well as the ExtensionManagementUtility->makeCategorizable(), which has required creating a "TCA overrides" file.

New in version 12.0

While using the type category, TYPO3 takes care of generating the necessary TCA configuration. Developers only have to define the TCA column and add category as the desired TCA type in the tables's TCA file (inside or outside of the Overrides folder).

EXT:my_extension/Configuration/TCA/Overrides/someTable.php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

$GLOBALS['TCA'][$myTable]['columns']['categories'] = [
    'config' => [
        'type' => 'category',
    ],
];

ExtensionManagementUtility::addToAllTCAtypes(
    $myTable,
    'categories'
);
Copied!

The following options can be overridden via page TSconfig, TCE form:

  • size
  • maxitems
  • minitems
  • readOnly
  • treeConfig

Properties of the TCA column type category

Name Type Scope
string Display / Proc.
string (list of) Display / Proc.
string (table name) Proc. / Display
string or LLL reference Display
string (SQL WHERE) Proc. / Display
array Display / Proc.
integer > 0 Display / Proc.
integer > 0 Display
string (table name) Proc.
boolean Display
string Display / Proc.
integer Display
array Display

default

default
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.
RenderType
all

Default value set if a new record is created. If empty, no category gets selected.

exclusiveKeys

exclusiveKeys
Type
string (list of)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.
RenderType
all

List of keys that exclude any other keys in a select box where multiple items could be selected. See also property exclusiveKeys of selectTree.

foreign_table

foreign_table
Type
string (table name)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Proc. / Display

The item-array will be filled with records from the table defined here. The table must have a TCA definition.

The uids of the chosen records will be saved in a comma-separated list by default.

Use property MM <columns-category-properties-mm> to store the values in an intermediate MM table instead.

foreign_table_prefix

foreign_table_prefix
Type
string or LLL reference
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display

Label prefix to the title of the records from the foreign-table.

See also property foreign_table_prefix of select field.

foreign_table_where

foreign_table_where
Type
string (SQL WHERE)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Proc. / Display
Default
AND {#sys_category}.{#sys_language_uid} IN (-1, 0)

The items from foreign_table are selected with this WHERE clause. If set make sure to append the default value to your query. See also property foreign_table_where of select field.

itemGroups

itemGroups
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.
RenderType
all

Contains an array of key-value pairs. The key contains the id of the item group, the value contains the label of the item group or its language reference.

Only groups containing items will be displayed. In the select field first all items with no group defined are listed then the item groups in the order of their definition, each group with the corresponding items.

See also property itemGroups of select field.

maxitems

maxitems
Type
integer > 0
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['maxitems']
Scope
Display / Proc.

Maximum number of child items. Defaults to a high value. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

minitems

minitems
Type
integer > 0
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['minitems']
Scope
Display

Minimum number of child items. Defaults to 0. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

MM

MM
Type
string (table name)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Proc.

New in version 11.4

TCA table column fields that define ['config']['MM'] can omit the specification of the intermediate MM table layout in ext_tables.sql. The TYPO3 database analyzer takes care of proper schema definition.

Extensions are strongly encouraged to drop CREATE TABLE definitions from the ext_tables.sql file for those intermediate tables referenced by TCA table columns. Dropping these definitions allows the Core to adapt and migrate definitions if needed.

This value contains the name of the table in which to store a MM relation. It is used together with foreign_table.

The database field with a MM property only stores the number of records in the relation.

Please have a look into the additional information in the MM common property description and the property MM of select field

readOnly

readOnly
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['readOnly']
Scope
Display

Renders the field in a way that the user can see the values but cannot edit them. The rendering is as similar as possible to the normal rendering but may differ in layout and size.

relationship

relationship
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.
RenderType
all
Default
manyToMany

All possible values are:

oneToOne
Stores the uid of the selected category. When using this relationship, maxitems=1 will automatically be added to the column configuration. While one record can only have a relation to one category, each category can still have a relationship to more then one record.
oneToMany
Stores the uids of selected categories in a comma-separated list.
manyToMany (default):
Uses the intermediate table sys_category_record_mm and only stores the categories count on the local side. This is the use case, which was previously accomplished using ExtensionManagementUtility->makeCategorizable().

In the following example a category tree is displayed, but only one category can be selected.

$GLOBALS['TCA'][$myTable]['columns']['mainCategory'] = [
    'config' => [
        'type' => 'category',
        'relationship' => 'oneToOne'
    ]
];
Copied!

All other relevant options, for example maxitems=1, are being set automatically.

size

size
Type
integer
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['size']
Scope
Display

Maximal number of elements to be displayed by default

treeConfig

treeConfig
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display
RenderType
selectTree

Either childrenField or parentField has to be set - childrenField takes precedence. Keywords:

dataProvider
Allows to define a custom data provider class for usecases where special data preparation is necessary. By default \TYPO3\CMS\Core\Tree\TableConfiguration\DatabaseTreeDataProvider is used.
childrenField (string)
Field name of the foreign_table that references the uid of the child records.
parentField (string)
Field name of the foreign_table that references the uid of the parent record
startingPoints (string, comma separated values)

allows to set multiple records as roots for tree records.

The setting takes a CSV value, e.g. 2,3,4711, which takes records of the uids 2, 3 and 4711 into account and creates a tree of these records.

Additionally, each value used in startingPoints may be fed from a site configuration by using the ###SITE:### syntax.

Example:

# Site config
base: /
rootPageId: 1
categories:
    root: 123
Copied!
// Example TCA config
'config' => [
    'treeConfig' => [
        'startingPoints' => '1,2,###SITE:categories.root###',
    ],
],
Copied!

This will evaluate to 'startingPoints' => '1,2,123'.

appearance (array, optional)
showHeader (boolean)
Whether to show the header of the tree that contains a field to filter the records and allows to expand or collapse all nodes
expandAll (boolean)
Whether to show the tree with all nodes expanded
maxLevels (integer)
The maximal amount of levels to be rendered (can be used to stop possible recursions)
nonSelectableLevels (list, default "0")
Comma-separated list of levels that will not be selectable, by default the root node (which is "0") cannot be selected