TCA column type `category`

The TCA type category can be used to render a category tree.

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).

The according database field is generated automatically.

Table of contents:

Example: Simple category field

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'
);

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

size
maxitems
minitems
readOnly
treeConfig

Note

It is still possible to configure a category tree with type=select and renderType=selectTree when you want to override specific fields, but in most cases the simplified category TCA type is sufficient.

Properties of the TCA column type `category`

Name	Type	Scope
default	string	Display / Proc.
exclusiveKeys	string (list of)	Display / Proc.
foreign_table	string (table name)	Proc. / Display
foreign_table_item_group	string (column name)	Proc. / Display
foreign_table_prefix	plain text label or label reference	Display
foreign_table_where	string (SQL WHERE)	Proc. / Display
itemGroups	array	Display / Proc.
maxitems	integer > 0	Display / Proc.
minitems	integer > 0	Display
MM	string (table name)	Proc.
readOnly	boolean	Display
relationship	string	Display / Proc.
size	integer	Display
treeConfig	array	Display

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

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

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_item_group

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

New in version 13.0

This property references a specific field in the foreign table, which holds an item group identifier.

foreign_table_prefix

Type: plain text label or label reference
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display

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

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

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.

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

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

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

Note

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.

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

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.

Warning

This property affects only the display. It is still possible to write to those fields when using the DataHandler.

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'
    ]
];

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

size

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

Maximal number of elements to be displayed by default

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

// Example TCA config
'config' => [
    'treeConfig' => [
        'startingPoints' => '1,2,###SITE:categories.root###',
    ],
],

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

TCA column type category

Example: Simple category field

Properties of the TCA column type category

default

exclusiveKeys

foreign_table

foreign_table_item_group

foreign_table_prefix

foreign_table_where

itemGroups

maxitems

minitems

MM

readOnly

relationship

size

treeConfig

TCA column type `category`

Properties of the TCA column type `category`