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 Category
as well
as the Extension
, which has required
creating a "TCA overrides" file.
New in version 12.0
When using the category
type, TYPO3 takes care of
generating the according database field.
A developer does not need to define this field in an extension's
ext_
file.
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).
<?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
read
Only tree
Config
Note
It is still possible to configure a category tree with type=select
and render
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
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-
to store the values in an intermediate MM table instead.category- properties- mm>
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.
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.
See also property itemGroups of select field.
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.
New in version 11.4
TCA table column fields that define
['config']
can omit the specification of the intermediate MM table layout in ext_tables.sql. The TYPO3 database analyzer takes care of proper schema definition.['MM'] Extensions are strongly encouraged to drop
CREATE TABLE
definitions from theext_
file for those intermediate tables referenced by TCA table columns. Dropping these definitions allows the Core to adapt and migrate definitions if needed.tables. sql 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:
one
To One - 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. one
To Many - Stores the uids of selected categories in a comma-separated list.
many
(default):To Many - Uses the intermediate table
sys_
and only stores the categories count on the local side. This is the use case, which was previously accomplished usingcategory_ record_ mm Extension
.Management Utility->make Categorizable ()
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
-
- 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
children
orField parent
has to be set -Field children
takes precedence. Keywords:Field - 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 uids2
,3
and4711
into account and creates a tree of these records.Additionally, each value used in
starting
may be fed from a site configuration by using thePoints ###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
'starting
.Points' => '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