selectTree
The select
render type is used to display hierarchical data in a
tree structure.
The according database field is generated automatically.
A field with the select
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 select
render type can handle multiple
tables through the configuration options.
Table of contents
Example: A happy little tree!
[
'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,
],
],
],
],
],
]
Properties of the TCA column type select
with renderType selectTree
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.
Note
If you mix non-database relations with database relations like this, DO NOT use integers for values and DO NOT use "_" (underscore) in values either! Will not work if you also use "MM" relations!
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!)
The "deny list" approach for single field values has been removed, the only allowed option
for auth
is explicit
. Extensions using config value explicit
should be adapted to switch to explicit
instead. The upgrade wizard
"Migrate backend groups "explicit_allowdeny" field to simplified format." that transfers
existing be_
rows to the new format, drops any DENY
fields and instructs
admins to not set new access rights of affected backend groups.
Handling of auth
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
-
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_
. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.state
dbFieldLength
-
- Type
- integer
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Default
- 255
- Scope
- Proc.
New in version 13.0
As TYPO3 takes care of generating the according database field for
select
fields since TYPO3 v13, a developer can adjust the length of the database field with this option in TCA directly.The TCA config option
db
contains an integer value that is applied toField Length varchar
fields (nottext
) 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 usedb
forField Length type=select
fields to increase or decrease the default length.
<?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,
],
];
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
-
- 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
-
- 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
-
For details see fieldInformation.
fieldWizard
-
localizationStateSelector
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']
For details see localizationStateSelector.
fileFolderConfig
-
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
-
- 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
-
- 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\
. See getPublicPath() . Alternatively use the prefix "EXT:" to point to an extension folder.CMS\ Core\ Core\ Environment:: get Public Path () 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[ '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
-
- 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-
to store the values in an intermediate MM table instead.select- tree- properties- mm>
[
'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,
],
],
],
],
],
]
[
'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',
],
],
],
]
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
-
- 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.
[
'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: ',
],
],
],
]
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. TheWHERE
clause is effectively appended to the existingWHERE
clause (which contains default constraints, such asNOT deleted
) and must begin withAND
.
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.
Note
The field name part of the marker is not in upper case letters. It must match the exact case used in the database.
So for example
sys_
must be referenced usinglanguage_ uid ###REC_
FIELD_ sys_ language_ uid### - ###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:
ormy Setting. category Pid### ###SITE:
.root Page Id###
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.
[
'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: ',
],
],
],
]
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_
ortable 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
-
- 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
-
- 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
-
- 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.
Note
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
-
- 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
-
- 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
-
- 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_
on the foreign side to the field name on the local side.opposite_ field For example, if the field
companies.
is your local side and you want to make the same relation editable from the foreign side of the relation in a field calledemployees persons.
, you would need to set theemployers MM_
value of the TCA configuration of theopposite_ field persons.
field to the string "employees".employers Note
Bidirectional references only get registered once on the native side in
sys_
.refindex
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_
is an array which references which fields contain the references to the opposite side, so that they can be queried for match field configuration.opposite Usage
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
-
Changed in version 13.0
This setting is obsolete. Remove all occurrences of
MM_
from TCA. Thehas Uid Field uid
column is added as primary key automatically, ifmultiple = true
is set, otherwise a combined primary key of fieldsuid_
,local uid_
plus eventuallyforeign tablenames
andfieldname
is used.
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
-
- 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.
Warning
This property affects only the display. It is still possible to write to those fields when using the DataHandler.
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
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']
- Scope
- Display
Either
children
orField parent
has to be set -Field children
takes precedence. Keywords:Field 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\
is used.CMS\ Core\ Tree\ Table Configuration\ Database Tree Data Provider
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
-
- 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
-
- 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 pids2
,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.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
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['']
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
-
- Type
- boolean
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['treeConfig']['appearance']['expandAll']
Whether to show the tree with all nodes expanded
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
-
- 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[ '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!