selectTree

The selectTree render type is used to display hierarchical data in a tree structure.

The according database field is generated automatically.

A field with the selectTree render type allows you to represent data in a hierarchical manner, similar to a tree. It is typically used when working with database tables that have a hierarchical structure. The properties treeConfig and foreign_table are mandatory and must be provided to establish the connection to the relevant database table. Optionally, you can also use items or itemsProcFunc to pass the values, but these are not sufficient on their own. The top-level item in the tree will always represent the descriptive name of the table.

Regarding joining several tables, the selectTree render type can handle multiple tables through the configuration options.

Table of contents

Example: A happy little tree!

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php 
[
    'columns' => [
        'select_tree_1' => [
            'label' => 'select_tree_1 pages, showHeader=true, expandAll=true, size=20, order by sorting, static items, description',
            'description' => 'field description',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectTree',
                'foreign_table' => 'pages',
                'foreign_table_where' => 'ORDER BY pages.sorting',
                'size' => 20,
                'items' => [
                    [
                        'label' => 'static from tca 4711',
                        'value' => 4711,
                    ],
                    [
                        'label' => 'static from tca 4712',
                        'value' => 4712,
                    ],
                ],
                'behaviour' => [
                    'allowLanguageSynchronization' => true,
                ],
                'treeConfig' => [
                    'parentField' => 'pid',
                    'appearance' => [
                        'expandAll' => true,
                        'showHeader' => true,
                    ],
                ],
            ],
        ],
    ],
]
Copied!

Properties of the TCA column type select with renderType selectTree

Name Type Scope
allowNonIdValues
 boolean Proc.
authMode
 string (keyword) Display / Proc.
behaviour
allowLanguageSynchronization
 boolean Proc.
dbFieldLength
 integer Proc.
default
 string Display / Proc.
disableNoMatchingValueElement
 boolean Display
exclusiveKeys
 string (list of) Display / Proc.
fieldInformation
fieldWizard
localizationStateSelector
 array
fileFolderConfig
allowedExtensions
 string Display / Proc.
depth
 integer Display / Proc.
folder
 string Display / Proc.
foreign_table
 string (table name) Proc. / Display
foreign_table_item_group
 string (column name) Proc. / Display
foreign_table_prefix
 string or LLL reference Display
foreign_table_where
 string (SQL WHERE) Proc. / Display
items
 array Display / Proc.
itemsProcFunc
 string (class->method reference) Display / Proc.
maxitems
 integer > 0 Display / Proc.
minitems
 integer > 0 Display
MM
 string (table name) Proc.
MM_match_fields
 array Display / Proc.
MM_opposite_field
 string (field name) Proc.
MM_oppositeUsage
 array Proc.
MM_table_where
 string (SQL WHERE) Proc.
MM_hasUidField
multiple
 boolean Display / Proc.
readOnly
 boolean Display
size
 integer Display
treeConfig
 array Display
dataProvider
 string (fully qualified class name)
childrenField
 string
parentField
 string
startingPoints
 string (comma separated values)
appearance
 array
showHeader
 boolean
expandAll
 boolean
maxLevels
 integer
nonSelectableLevels
 string (comma separated list)

allowNonIdValues

allowNonIdValues
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Proc.
RenderType
all

Only useful if foreign_table is enabled.

If set, then values which are not integer ids will be allowed. May be needed if you use itemsProcFunc or just enter additional items in the items array to produce some string-value elements for the list.

authMode

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

Authorization mode for the selector box. The only possible option is:

explicitAllow
All static values from the "items" array of the selector box will be added to a matrix in the backend user configuration where a value must be explicitly selected if a user (other than admin) is allowed to use it!)
Migration: Using authMode='explicitDeny'

The "deny list" approach for single field values has been removed, the only allowed option for authMode is explicitAllow. Extensions using config value explicitDeny should be adapted to switch to explicitAllow instead. The upgrade wizard "Migrate backend groups "explicit_allowdeny" field to simplified format." that transfers existing be_groups rows to the new format, drops any DENY fields and instructs admins to not set new access rights of affected backend groups.

Migration: Using authMode='individual'

Handling of authMode being set to individual has been fully dropped. The Core provides no alternative. This has been an obscure setting ever since and there is no direct migration. Extensions that rely on this handling need to find a substitution based on Core hooks, Core events or other existing Core API functionality.

behaviour

behaviour

allowLanguageSynchronization

allowLanguageSynchronization
Type
boolean
Default
false
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['allowLanguageSynchronization']
Scope
Proc.

Allows an editor to select in a localized record whether the value is copied over from default or source language record, or if the field has an own value in the localization. If set to true and if the table supports localization and if a localized record is edited, this setting enables FieldWizard LocalizationStateSelector: Two or three radio buttons shown below the field input. The state of this is stored in a json encoded array in the database table called l10n_state. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.

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

$selectField = [
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingleBox',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];
Copied!

dbFieldLength

dbFieldLength
Type
integer
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Default
255
Scope
Proc.

New in version 13.0

The TCA config option dbFieldLength contains an integer value that is applied to varchar fields (not text) and defines the length of the database field. It will not be respected for fields that resolve to an integer type. Developers who wish to optimize field length can use dbFieldLength for type=select fields to increase or decrease the default length.

Example: Increase the dbFieldLength for a select field
Excerpt from EXT:my_extension/Configuration/TCA/myextension_domain_model_mytable.php 
<?php

$selectField = [
    'label' => 'My field',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingleBox',
        'items' => [
            ['label' => '', 'value' => ''],
            ['label' => 'Some label', 'value' => 'some'],
            ['label' => 'Another label', 'value' => 'another'],
        ],
        'default' => '',
        'dbFieldLength' => 10,
    ],
];
Copied!

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, the first element in the items array is selected.

disableNoMatchingValueElement

disableNoMatchingValueElement
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display
RenderType
all

If set, then no element is inserted if the current value does not match any of the existing elements. A corresponding options is also found in Page TSconfig.

exclusiveKeys

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

List of keys that exclude any other keys in a select box where multiple items could be selected.

fieldInformation

fieldInformation

For details see fieldInformation.

fieldWizard

fieldWizard

localizationStateSelector

localizationStateSelector
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']

For details see localizationStateSelector.

fileFolderConfig

fileFolderConfig

allowedExtensions

allowedExtensions
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fileFolderConfig']['allowedExtensions']
Scope
Display / Proc.

List of file extensions to select. If blank, all files are selected. Specify list in lowercase.

This configuration can be overridden by Page TSconfig.

depth

depth
Type
integer
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fileFolderConfig']['depth']
Scope
Display / Proc.
RenderType
all

Depth of directory recursions. Default is 99. Specify in range from 0-99. 0 (zero) means no recursion into subdirectories. Only useful in combination with property folder.

This configuration can be overridden by Page TSconfig.

folder

folder
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fileFolderConfig']['folder']
Scope
Display / Proc.

Specifying a folder from where files are added to the item array.

Specify the folder relative to the \TYPO3\CMS\Core\Core\Environment::getPublicPath(). See getPublicPath() . Alternatively use the prefix "EXT:" to point to an extension folder.

Files from the folder are selected recursively to the level specified by depth and only files of the extensions defined by allowedExtensions are listed in the select box.

Only the file reference relative to the folder is stored.

If the files are images (gif,png,jpg) they will be configured as icons (third parameter in items array).

This configuration can be overridden by Page TSconfig.

Examples: Select SVGs recursively from a folder
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php 
[
    'columns' => [
        'select_single_7' => [
            'label' => 'select_single_7 fileFolder, dummy first entry, selectIcons',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => '',
                        'value' => 0,
                    ],
                ],
                'fileFolderConfig' => [
                    'folder' => 'EXT:styleguide/Resources/Public/Icons',
                    'allowedExtensions' => 'svg',
                    'depth' => 1,
                ],
                'fieldWizard' => [
                    'selectIcons' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]
Copied!

foreign_table

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

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-select-tree-properties-mm> to store the values in an intermediate MM table instead.

Example: Select singe field with enabled selectIcons
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php 
[
    'columns' => [
        'select_single_12' => [
            'label' => 'select_single_12 foreign_table selicon_field',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'foreign_table' => 'tx_styleguide_elements_select_single_12_foreign',
                'fieldWizard' => [
                    'selectIcons' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]
Copied!
Example: Select field with foreign table via MM table
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php 
[
    'columns' => [
        'select_single_15' => [
            'label' => 'select_single_15 foreign_table',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'foreign_table' => 'tx_styleguide_staticdata',
                'MM' => 'tx_styleguide_elements_select_single_15_mm',
            ],
        ],
    ],
]
Copied!

foreign_table_item_group

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.

See also foreign_table_item_group.

foreign_table_prefix

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

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

Example: Select single field with foreign_prefix and foreign_where
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php 
[
    'columns' => [
        'select_single_3' => [
            'label' => 'select_single_3 static values, dividers, foreign_table_where',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Static values',
                        'value' => '--div--',
                    ],
                    [
                        'label' => 'static -2',
                        'value' => -2,
                    ],
                    [
                        'label' => 'static -1',
                        'value' => -1,
                    ],
                    [
                        'label' => 'DB values',
                        'value' => '--div--',
                    ],
                ],
                'foreign_table' => 'tx_styleguide_staticdata',
                'foreign_table_where' => 'AND {#tx_styleguide_staticdata}.{#value_1} LIKE \'%foo%\' ORDER BY uid',
                'foreign_table_prefix' => 'A prefix: ',
            ],
        ],
    ],
]
Copied!

foreign_table_where

foreign_table_where
Type
string (SQL WHERE)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Proc. / Display
RenderType
all

The items from foreign_table are selected with this WHERE clause. The WHERE clause is effectively appended to the existing WHERE clause (which contains default constraints, such as NOT deleted) and must begin with AND.

Field quoting

The example below uses the special field quoting syntax {#...} around identifiers to be as DBAL-compatible as possible. Note that ORDER BY and GROUP BY should NOT be quoted, since they always receive proper quoting automatically through the API.

Markers inside the WHERE statement

It is possible to use markers in the WHERE clause:

###REC_FIELD_[field name]###

Any field of the current record.

###THIS_UID###
Current element uid (zero if new).
###CURRENT_PID###
The current page id (pid of the record).

###SITEROOT###

###PAGE_TSCONFIG_ID###
A value you can set from Page TSconfig dynamically.
###PAGE_TSCONFIG_IDLIST###
A value you can set from Page TSconfig dynamically.
###PAGE_TSCONFIG_STR###
A value you can set from Page TSconfig dynamically.
###SITE:<KEY>.<SUBKEY>###
A value from the site configuration, for example: ###SITE:mySetting.categoryPid### or ###SITE:rootPageId###.

The markers are preprocessed so that the value of CURRENT_PID and PAGE_TSCONFIG_ID are always integers (default is zero), PAGE_TSCONFIG_IDLIST will always be a comma-separated list of integers (default is zero) and PAGE_TSCONFIG_STR will be quoted before substitution (default is blank string).

More information about markers set by Page TSconfig can be found in the TSconfig reference.

Example: Select single field with foreign_prefix and foreign_where
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php 
[
    'columns' => [
        'select_single_3' => [
            'label' => 'select_single_3 static values, dividers, foreign_table_where',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Static values',
                        'value' => '--div--',
                    ],
                    [
                        'label' => 'static -2',
                        'value' => -2,
                    ],
                    [
                        'label' => 'static -1',
                        'value' => -1,
                    ],
                    [
                        'label' => 'DB values',
                        'value' => '--div--',
                    ],
                ],
                'foreign_table' => 'tx_styleguide_staticdata',
                'foreign_table_where' => 'AND {#tx_styleguide_staticdata}.{#value_1} LIKE \'%foo%\' ORDER BY uid',
                'foreign_table_prefix' => 'A prefix: ',
            ],
        ],
    ],
]
Copied!

items

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

Contains the elements for the selector box unless the property foreign_table or special has been set in which case automated values are set in addition to any values listed in this array.

For examples see also property items of singleSelect.

itemsProcFunc

itemsProcFunc
Type
string (class->method reference)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.

PHP method which is called to fill or manipulate the items array. See itemsProcFunc about details.

maxitems

maxitems
Type
integer > 0
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
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']
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.

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.

MM_match_fields

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

Array of field => value pairs to both insert and match against when writing/reading MM relations.

MM_opposite_field

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

If you want to make a MM relation editable from the foreign side (bidirectional) of the relation as well, you need to set MM_opposite_field on the foreign side to the field name on the local side.

For example, if the field companies.employees is your local side and you want to make the same relation editable from the foreign side of the relation in a field called persons.employers, you would need to set the MM_opposite_field value of the TCA configuration of the persons.employers field to the string "employees".

MM_oppositeUsage

MM_oppositeUsage
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Proc.

In a MM bidirectional relation using match fields the opposite side needs to know about the match fields for certain operations (for example, when a copy is created in a workspace) so that relations are carried over with the correct information.

MM_oppositeUsage is an array which references which fields contain the references to the opposite side, so that they can be queried for match field configuration.

MM_table_where

MM_table_where
Type
string (SQL WHERE)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Proc.

Additional where clause used when reading MM relations.

Example:

{#uid_local} = ###THIS_UID###
Copied!

The above example uses the special field quoting syntax {#...} around identifiers to be as DBAL-compatible as possible.

MM_hasUidField

MM_hasUidField

Changed in version 13.0

This setting is obsolete. Remove all occurrences of MM_hasUidField from TCA. The uid column is added as primary key automatically, if multiple = true is set, otherwise a combined primary key of fields uid_local, uid_foreign plus eventually tablenames and fieldname is used.

multiple

multiple
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.

Allows the same item more than once in a list.

If used with bidirectional MM relations it must be set for both the native and foreign field configuration.

Changed in version 13.0

The property MM_hasUidField is obsolete. It had to be defined previously when using multiple.

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 value but cannot edit it.

size

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

Maximal number of elements to be displayed in the tree by default

treeConfig

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

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

dataProvider

dataProvider
Type
string (fully qualified class name)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['dataProvider']

Allows to define a custom data provider class for use cases where special data preparation is necessary. By default \TYPO3\CMS\Core\Tree\TableConfiguration\DatabaseTreeDataProvider is used.

childrenField

childrenField
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['childrenField']

Field name of the foreign_table that references the uid of the child records.

parentField

parentField
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['parentField']

Field name of the foreign_table that references the uid of the parent record

startingPoints

startingPoints
Type
string (comma separated values)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['startingPoints']

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

This property can also be set by page TSconfig, see config.treeConfig

Example:

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

appearance

appearance
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['']

showHeader

showHeader
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['appearance']['showHeader']

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

expandAll
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['appearance']['expandAll']

Whether to show the tree with all nodes expanded

maxLevels

maxLevels
Type
integer
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['appearance']['maxLevels']

The maximal amount of levels to be rendered (can be used to stop possible recursions)

nonSelectableLevels

nonSelectableLevels
Type
string (comma separated list)
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['appearance']['nonSelectableLevels']
Default
0

Comma-separated list of levels that will not be selectable, by default the root node (which is "0") cannot be selected

Example: Tree with non selectable levels
EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php 
[
    'columns' => [
        'select_tree_2' => [
            'label' => 'select_tree_2 pages, showHeader=false, nonSelectableLevels=0,1, maxitems=4, size=10',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectTree',
                'foreign_table' => 'pages',
                'maxitems' => 4,
                'size' => 10,
                'treeConfig' => [
                    'parentField' => 'pid',
                    'appearance' => [
                        'expandAll' => true,
                        'showHeader' => false,
                        'nonSelectableLevels' => '0,1',
                    ],
                ],
            ],
        ],
    ],
]
Copied!