Attention
TYPO3 v9 has reached its end-of-life September 30th, 2021 and is not maintained by the community anymore. Looking for a stable version? Use the version switch on the top left.
You can order Extended Long Term Support (ELTS) here: TYPO3 ELTS.
TCEFORM¶
Allows detailed configuration of how editing forms are rendered for a page tree branch and for individual tables if you like. You can enable and disable options, blind options in selector boxes etc.
See the core API document section FormEngine for more details on how records are rendered in the backend.
The properties listed below apply to various contexts which are explained per property. The full property path thus depends on the property and where it should apply. In general, a more specific property path overrides a less specific one:
Some properties apply to single fields, those can be usually set per table or
per table and record type. This leads to the property paths
TCEFORM.[tableName].[fieldName].[propertyName]
to configure the field for all types
and TCEFORM.[tableName].[fieldName].types.[typeName]
to configure a field for a specific
type, see the TCA type section for details on types.
Other properties also apply to flex form fields, in this case the full property
path including the data structure key has to be set:
TCEFORM.[tableName].[fieldName].[dataStructureKey].[flexSheet].[flexFieldName].[propertyName]
.
The [dataStructKey]
represents the key of a FlexForm in
$GLOBALS['TCA'][<tableName>]['columns'][<field>]['config']['ds']
. This key will be split into up to
two parts. By default the first part will be used as identifier of the FlexForm in TSconfig. The second part
will override the identifier if it is not empty, list
or *
. For example the identifier of the key
my_ext_pi1,list
will be my_ext_pi1
and of the key *,my_CType
it will be my_CType
. See section
Pointing to a data structure of the TCA reference for details.
Some properties apply to whole FlexForm sheets, their property path is
TCEFORM.[tableName].[fieldName].[dataStructureKey].[flexSheet].[propertyName]
.
While all that property path munging looks messy at first, it should become more clear if reading through the single properties below and looking at the examples.
addItems¶
- Datatype
localized string
- Description
Change the list of items in TCA type=select fields. Using this property, items can be added to the list. Note that the added elements might be removed if the selector represents records: If the select box is a relation to another table. In that case only existing records will be preserved.
The subkey
icon
will allow to add your own icons to new values.This property is available for various levels:
- table level, example:
TCEFORM.tt_content.header_layout.addItems
- table and record type level, example:
TCEFORM.tt_content.header_layout.types.textpic.addItems
- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.addItems
Where
sDEF
is the sheet name.
Warning
Do not add page types this way (using
TCEFORM.pages.doktype.addItems
), instead the proper PHP API should be used to do this, see Core APIs for details.Note
The
icon
is probably outdated, this documentation should be checked, probably an icon identifier is used nowadays.- Example
TCEFORM.tt_content.header_layout { # Add another header_layout option: addItems.1525215969 = Another header layout # Add another one with localized label and icon addItems.1525216023 = LLL:EXT:my_ext/Resources/Private/Language/locallang.xlf:header_layout addItems.1525216023.icon = EXT:my_ext/icon.png }
altLabels¶
- Datatype
localized string
- Description
This property applies to TCA type=select, TCA type=check and TCA type=radio.
This property allows you to enter alternative labels for the items in the list. For a single checkbox or radio button, use
default
, for multiple checkboxes and radiobuttons, use an integer for their position starting at 0.This property is available for various levels:
- table level:
TCEFORM.[tableName].[fieldName].altLabels
- table and record type level:
TCEFORM.[tableName].[fieldName].types.typeName.altLabels
- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.altLabels
Where
sDEF
is the sheet name.
Example
TCEFORM.pages.doktype { # Set a different item label altLabels.1 = STANDARD Page Type altLabels.254 = Folder (for various elements) # Sets the default label for Recycler via "locallang": altLabels.255 = LLL:EXT:my_ext/Resources/Private/Language/locallang_tca.xlf:recycler }![]()
The Page types with modified labels¶
PAGE_TSCONFIG_ID¶
- Datatype
integer
- Description
This option allows to provide a value for dynamic SQL-WHERE parameters. The value is defined for a specific field of a table. For usage with flexform fields, the entire path to a sub-field must be provided.
Note
This value can be used for the TCA property foreign_table_where and for the
addWhere
part of the suggest wizard.- Example
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.PAGE_TSCONFIG_ID = 22
In this example, the value will substitute the marker in a plugin FlexForm.
TCEFORM.tx_myext_table.myfield.PAGE_TSCONFIG_ID = 22
This example might be used for a record in an extension. It refers to a table called
tx_myext_table
and the fieldmyfield
. Here the marker will be substituted by the value22
.
PAGE_TSCONFIG_IDLIST¶
- Datatype
list of integers
- Description
See above.
- Example
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.PAGE_TSCONFIG_IDLIST = 20,21,22
In this example, the value will substitute the marker in a plugin FlexForm.
TCEFORM.tx_myext_table.myfield.PAGE_TSCONFIG_IDLIST = 20,21,22
This example might be used for a record in an extension. It refers to a table called
tx_myext_table
and the fieldmyfield
. Here the marker will be substituted by the list of integers.
PAGE_TSCONFIG_STR¶
- Datatype
string
- Description
See above.
- Example
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.PAGE_TSCONFIG_STR = %hello%
In this example, the value will substitute the marker in a plugin FlexForm.
TCEFORM.tx_myext_table.myfield.PAGE_TSCONFIG_STR = %hello%
This example might be used for a record in an extension. It refers to a table called
tx_myext_table
and the fieldmyfield
. Here the marker will be substituted by the given value.
config¶
- Datatype
string / array
- Description
This setting allows to override TCA field configuration. This will influence configuration settings in $GLOBALS['TCA'][<tableName>]['columns'][<fieldName>]['config'][<key>], see TCA reference for details.
Not all configuration options can be overriden, the properties are restricted and depend on the field type. The array
typo3/sysext/backend/Classes/Form/Utility/FormEngineUtility.php->$allowOverrideMatrix
within FormEngine code defines details:'input' => ['size', 'max', 'readOnly'], 'text' => ['cols', 'rows', 'wrap', 'max', 'readOnly'], 'check' => ['cols', 'readOnly'], 'select' => ['size', 'autoSizeMax', 'maxitems', 'minitems', 'readOnly', 'treeConfig'], 'group' => ['size', 'autoSizeMax', 'max_size', 'maxitems', 'minitems', 'readOnly'], 'inline' => ['appearance', 'behaviour', 'foreign_label', 'foreign_selector', 'foreign_unique', 'maxitems', 'minitems', 'size', 'autoSizeMax', 'symmetric_label', 'readOnly'], 'imageManipulation' => ['ratios', 'cropVariants']
This property is available for various levels:
- table level, example:
TCEFORM.tt_content.header.config.max
- table and record type level, example:
TCEFORM.tt_content.header.types.textpic.config.max
- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.config.max
Where
sDEF
is the sheet name.
config.treeConfig¶
- Datatype
int
- Description
The
treeConfig
sub properties of TCEFORM.config are dedicated to the TCA config typeselect
with renderType=selectTree. A couple of treeConfig properties can be overriden on page TSconfig level, see their detailed description in the TCA reference:config.treeConfig.rootUid config.treeConfig.appearance.expandAll config.treeConfig.appearance.maxLevels config.treeConfig.appearance.nonSelectableLevels
This property is available for various levels:
- table level, example:
TCEFORM.tt_content.myField.config.treeConfig.rootUid
- table and record type level, example:
TCEFORM.tt_content.header.types.config.treeConfig.rootUid
- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.config.treeConfig.rootUid
Where
sDEF
is the sheet name.
disabled¶
- Datatype
boolean
- Description
If set, the field is not displayed in the backend form of the record. However, the field can still be set by other means. For example if this property is set:
TCEFORM.tt_content.colPos.disabled = 1
the Column field will not be displayed in the content elements form. The content element can still be moved to another column which internally also sets the fieldcolPos
. Fields with the TSconfig propertyTCEFORM.<table>.<field>.disable
therefore show the same behaviour as fields of the TCA type passthrough.- table level, example:
TCEFORM.tt_content.header.disabled
- table and record type level, example:
TCEFORM.tt_content.header.types.textpic.disabled
- Flex form sheet level. If set, the entire tab is not rendered, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.disabled
Where
sDEF
is the sheet name.- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.disabled
Where
sDEF
is the sheet name.
- Example
TCEFORM.pages.title { # The title field of the pages table is not editable disabled = 1 }
disableNoMatchingValueElement¶
- Datatype
boolean
- Description
This property applies only to items in TCA type=select fields. If a selector box value is not available among the options in the box, the default behavior of TYPO3 is to preserve the value and to show a label which warns about this special state:
A missing selector box value is indicated by a warning message¶
If disableNoMatchingValueElement is set, the element "INVALID VALUE" will not be added to the list.
This property is available for various levels:
- table level, example:
TCEFORM.tt_content.header_layout.disableNoMatchingValueElement
- table and record type level, example:
TCEFORM.tt_content.header_layout.types.textpic.disableNoMatchingValueElement
- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.disableNoMatchingValueElement
Where
sDEF
is the sheet name.
- Example
TCEFORM.pages.doktype { # "INVALID VALUE ..." label will never show up disableNoMatchingValueElement = 1 }
Now the selector box will default to the first element in the selector box:
Instead of show a warning message the system choose the first element in the selector box¶
itemsProcFunc¶
- Datatype
custom
- Description
This property applies only to items in TCA type=select fields. The properties of this key is passed on to the itemsProcFunc in the parameter array by the key "TSconfig".
This property is available for various levels:
- table level:
TCEFORM.[tableName].[fieldName].itemsProcFunc
- table and record type level:
TCEFORM.[tableName].[fieldName].types.[typeName].itemsProcFunc
- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.itemsProcFunc
Where
sDEF
is the sheet name.
keepItems¶
- Datatype
list of values
- Description
Change the list of items in TCA type=select fields. Using this property, all items except those defined here are removed.
This property is available for various levels:
- table level, example:
TCEFORM.tt_content.header_layout.keepItems
- table and record type level, example:
TCEFORM.tt_content.header_layout.types.textpic.keepItems
- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.keepItems
Where
sDEF
is the sheet name.
- Example
TCEFORM.pages.doktype { # Show only standard and "Spacer" page types keepItems = 1, 199 }
label¶
- Datatype
localized string
- Description
This allows you to enter alternative labels for any field. The value can be a
LLL:
reference to a localization file, the system will then look up the selected backend user language and tries to fetch the localized string if available. However, it is also possible to override these by appending the language key and hard setting a value, for examplelabel.de = Neuer Feldname
.This property is available for various levels:
- table level, example:
TCEFORM.tt_content.header.label
- table and record type level, example:
TCEFORM.tt_content.header.types.textpic.label
- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.label
Where
sDEF
is the sheet name.
- Example
TCEFORM.pages.title { label = LLL:EXT:my_ext/Resources/Private/Language/locallang.xlf:table.column label.default = New Label label.de = Neuer Feldname }
noMatchingValue_label¶
- Datatype
localized string
- Description
This property applies only to items in TCA type=select fields, it allows defining a different label of the noMatchingValue element.
It is possible to use the placeholder
%s
to insert the value. If the property is set to empty, the label will be blank.This property is available for various levels:
- table level, example:
TCEFORM.tt_content.header_layout.noMatchingValue_label
- table and record type level, example:
TCEFORM.tt_content.header_layout.types.textpic.noMatchingValue_label
- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.noMatchingValue_label
Where
sDEF
is the sheet name.
Example
TCEFORM.pages.doktype { # Different "INVALID VALUE ..." label: noMatchingValue_label = VALUE "%s" was not available! }![]()
An invalid selector box value is indicated by a warning message¶
removeItems¶
- Datatype
list of values
- Description
Change the list of items in TCA type=select fields. Using this property, single items can be removed, leaving all others.
This property is available for various levels:
- table level, example:
TCEFORM.tt_content.header_layout.removeItems
- table and record type level, example:
TCEFORM.tt_content.header_layout.types.textpic.removeItems
- Flex form field level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.myField.removeItems
Where
sDEF
is the sheet name.
- Example
TCEFORM.pages.doktype { # Remove "Recycler" and "Spacer" page types removeItems = 199, 255 }
sheetDescription¶
- Datatype
localized string
- Description
Specifies a description for the sheet shown in the FlexForm.
- This property is only available on flex form sheet level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.sheetDescription
Where
sDEF
is the sheet name.
sheetShortDescr¶
- Datatype
localized string
- Description
Specifies a short description of the sheet used as link title in the tab-menu.
- This property is only available on flex form sheet level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.sheetShortDescription
Where
sDEF
is the sheet name.
sheetTitle¶
- Datatype
localized string
- Description
Set the title of the sheet / tab in a FlexForm configuration.
- This property is only available on flex form sheet level, example:
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF.sheetTitle
Where
sDEF
is the sheet name.
- Example
TCEFORM.tt_content.pi_flexform.my_ext_pi1.sDEF { # Rename the first tab of the FlexForm plug-in configuration sheetTitle = LLL:my_ext/Resource/Private/Language/locallang.xlf:tt_content.pi_flexform.my_ext_pi1.sDEF }
suggest¶
Configuration of the suggest wizard that is available and often enabled for TCA type=group fields.

A configured suggest wizard¶
The properties listed below are available on various levels. A more specific setting overrides a less specific one:
- Configuration of all suggest wizards in all tables for all target query tables:
TCEFORM.suggest.default
- Configuration of all suggest wizards in all tables looking up records from a specific target table:
TCEFORM.suggest.[queryTable]
- Configuration of one suggest wizard field in one table for all target query tables:
TCEFORM.[tableName].[fieldName].suggest.default
- Configuration of one suggest wizard field in one table for a specific target query table:
TCEFORM.[tableName].[fieldName].suggest.[queryTable]
- Configuration of one suggest wizard field in a flex form field of one table for all target query tables:
TCEFORM.[tableName].[fieldName].[dataStructureKey].[sheetName].[flexFieldName].suggest.default
- Configuration of one suggest wizard field in a flex form field of one table for a specific target query table:
TCEFORM.[tableName].[fieldName].[dataStructureKey].[sheetName].[flexFieldName].suggest.[queryTable]
additionalSearchFields¶
- Datatype
string
- Description
Comma-separated list of fields the suggest wizard should also search in. By default the wizard looks only in the fields listed in the label and label_alt of TCA ctrl properties.
addWhere¶
- Datatype
string
- Description
Additional WHERE clause (with AND at the beginning).
Markers possible for replacement:
###THIS_UID###
###CURRENT_PID###
- Example
TCEFORM.pages.storage_pid.suggest.default { addWhere = AND pages.pid=###PAGE_TSCONFIG_ID### }
cssClass¶
- Datatype
string
- Description
Add a CSS class to every list item of the result list.
- Example
TCEFORM.suggest.pages { # Configure all suggest wizards which list records from table "pages" # to add the CSS class "pages" to every list item of the result list. cssClass = pages }
hide¶
- Datatype
boolean
- Description
Hide the suggest field. Works only for single fields.
- Example
TCEFORM.pages.storage_pid.suggest.default { hide = 1 }
maxPathTitleLength¶
- Datatype
positive integer
- Description
Maximum number of characters to display when a path element is too long.
- Example
TCEFORM.suggest.default { maxPathTitleLength = 30 }
minimumCharacters¶
- Datatype
positive integer
- Description
Minimum number of characters needed to start the search. Works only for single fields.
- Default
2
- Example
TCEFORM.pages.storage_pid.suggest.default { minimumCharacters = 3 }
pidDepth¶
- Datatype
positive integer
- Description
Expand pidList by this number of levels. Only has an effect, if pidList has a value.
- Example
TCEFORM.suggest.default { pidList = 6,7 pidDepth = 4 }
pidList¶
- Datatype
list of values
- Description
Limit the search to certain pages (and their subpages). When pidList is empty all pages will be included in the search as long as the backend user is allowed to see them.
- Example
TCEFORM.suggest.default { # sets the pidList for a suggest fields in all tables pidList = 1,2,3,45 }
receiverClass¶
- Datatype
PHP class name
- Description
PHP class alternative receiver class - the file that holds the class should be derived from
\TYPO3\CMS\Backend\Form\Element\SuggestDefaultReceiver
.- Default
\TYPO3\CMS\Backend\Form\Element\SuggestDefaultReceiver
renderFunc¶
- Datatype
string
- Description
User function to manipulate the displayed records in the result.
searchCondition¶
- Datatype
string
- Description
Additional WHERE clause (no AND needed to prepend).
- Example
TCEFORM.pages.storage_pid.suggest.default { # Configure the suggest wizard for the field "storage_pid" in table "pages" # to search only for pages with doktype=1 searchCondition = doktype=1 }
searchWholePhrase¶
- Datatype
boolean
- Description
Whether to do a
LIKE=%mystring%
(searchWholePhrase = 1) or aLIKE=mystring%
(to do a real find as you type).- Default
0
- Example
TCEFORM.pages.storage_pid.suggest.default { # Configure the suggest wizard for the field "storage_pid" in table "pages" to search only for whole phrases searchWholePhrase = 1 }