Display conditions in TCA columns
Display conditions ($GLOBALS['TCA'][$table]['columns'][$field][displayCond]) can be used to only display the affected field if certain other fields are set to certain values.
Conditions can be grouped and nested using boolean operators AND or OR as
array keys. See examples below.
Table of contents
Rules in display conditions
A rule is a string divided into several parts by ":" (colons). The first part is the rule-type and the subsequent parts depend on the rule type.
The following rules are available:
- FIELD
-
This evaluates based on another field's value in the record.
- Part 1 is the field name
-
Part 2 is the evaluation type. These are the possible options:
- REQ
- Requires the field to have a "true" value. False values are "" (blank string) and 0 (zero). Everything else is true. For the REQ evaluation type Part 3 of the rules string must be the string "true" or "false". If "true" then the rule returns "true" if the evaluation is true. If "false" then the rule returns "true" if the evaluation is false.
- > / < / >= / <=
- Evaluates if the field value is greater than, less than the value in "Part 3"
- = / !=
- Evaluates if the field value is equal to value in "Part 3"
- IN / !IN
- Evaluates if the field value is in the comma list equal to value in "Part 3"
- - / !-
- Evaluates if the field value is in the range specified by value in "Part 3" ([min] - [max])
- BIT / !BIT
- Evaluates if the bit specified by the value in "Part 3" is set in the field's value (considered as an integer)
- Part 3 is a comma separated list of string or numeric values
- REC:NEW:true
- This will show the field for new records which have not been saved yet.
- REC:NEW:false
- This will show the field for existing records which have already been saved.
- HIDE_FOR_NON_ADMINS
- This will hide the field for all non-admin users while admins can see it. Useful for FlexForm container fields which are not supposed to be edited directly via the FlexForm but rather through some other interface.
- USER
-
userFunc call with a fully qualified class name.
Additional parameters can be passed separated by colon:
USER:My Vendor\ My Extension\ User\ My Condition Matcher->check Header: some: more: info The following arguments are passed as array to the userFunc:
record: the currently edited recordflex: details about the FlexForm if the condition is used in oneContext flexform:Value Key vDEF condition: additional parametersParameters
The called method is expected to return a
boolvalue:trueif the field should be displayed,falseotherwise. - VERSION:IS
-
Evaluate if a record is a "versioned" record from workspaces.
-
Part 1 is the type:
- IS
- Part 2 is "true" or "false": If true, the field is shown only if the record is a version (pid == -1).
Example to show a field in "Live" workspace only:
VERSION:IS: false
-
In FlexForm, display conditions can be attached to single fields in sheets, to sheets itself, to flex section fields
and to flex section container element fields. FIELD references can be prefixed with a sheet name to
reference a field from a neighbor sheet, see examples below.
Tip
Fields used in a condition should have the column option
onChange set to reload.
Examples for display conditions
Basic display condition
The registration deadline of a conference is only shown while the field
registration_ is set:
<?php
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
defined('TYPO3') or die();
ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
'registration_deadline' => [
'label' => 'my_extension.db:conference.registration_deadline',
'displayCond' => 'FIELD:registration_open:REQ:true',
'config' => [
'type' => 'datetime',
'dbType' => 'datetime',
'nullable' => true,
'searchable' => false,
],
],
]);
ExtensionManagementUtility::addToAllTCAtypes(
'tx_myextension_conference',
'registration_deadline',
'',
'after:registration_open',
);
Combining conditions
Multiple conditions can be combined. The link to the tickets is only shown while the registration is open and the conference has seats:
<?php
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
defined('TYPO3') or die();
ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
'ticket_link' => [
'label' => 'my_extension.db:conference.ticket_link',
'displayCond' => [
'AND' => [
'FIELD:registration_open:REQ:true',
'FIELD:seats:>:0',
],
],
'config' => [
'type' => 'link',
'allowedTypes' => ['page', 'url'],
'appearance' => [
'browserTitle' => 'my_extension.db:conference.ticket_link.browser_title',
],
],
],
]);
ExtensionManagementUtility::addToAllTCAtypes(
'tx_myextension_conference',
'ticket_link',
'',
'after:registration_deadline',
);
A condition with several values: the live stream is only shown for conferences that take place online or hybrid:
<?php
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
defined('TYPO3') or die();
ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
'stream_url' => [
'label' => 'my_extension.db:conference.stream_url',
'displayCond' => 'FIELD:event_format:IN:online,hybrid',
'config' => [
'type' => 'link',
'allowedTypes' => ['url'],
],
],
]);
ExtensionManagementUtility::addToAllTCAtypes(
'tx_myextension_conference',
'stream_url',
'',
'after:event_format',
);
This is the same as a combination with OR:
- 'displayCond' => 'FIELD:event_format:IN:online,hybrid',
+ 'displayCond' => [
+ 'OR' => [
+ 'FIELD:event_format:=:online',
+ 'FIELD:event_format:=:hybrid',
+ ],
+ ],A complex example
Conditions can be nested. The number of seats of a conference is only shown in the default language, and only if the conference takes place on site or hybrid:
<?php
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
defined('TYPO3') or die();
ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
'seats' => [
'label' => 'my_extension.db:conference.seats',
'displayCond' => [
'AND' => [
'FIELD:sys_language_uid:=:0',
'OR' => [
'FIELD:event_format:=:onsite',
'FIELD:event_format:=:hybrid',
],
],
],
'config' => [
'type' => 'number',
'range' => [
'lower' => 1,
'upper' => 5000,
],
],
],
]);
ExtensionManagementUtility::addToAllTCAtypes(
'tx_myextension_conference',
'seats',
'',
'before:--div--;core.form.tabs:categories',
);
A complex example in a FlexForm
In a FlexForm, OR and AND are XML elements. The plugin of the conference
extension only asks for the number of conferences if it lists the upcoming or
the past ones:
<T3DataStructure>
<sheets>
<sDEF>
<ROOT>
<sheetTitle>my_extension.db:plugin.conferencelist.sheet.general</sheetTitle>
<type>array</type>
<el>
<settings.mode>
<label>my_extension.db:plugin.conferencelist.mode</label>
<onChange>reload</onChange>
<config>
<type>select</type>
<renderType>selectSingle</renderType>
<items>
<numIndex index="0">
<label>my_extension.db:plugin.conferencelist.mode.upcoming</label>
<value>upcoming</value>
</numIndex>
<numIndex index="1">
<label>my_extension.db:plugin.conferencelist.mode.past</label>
<value>past</value>
</numIndex>
<numIndex index="2">
<label>my_extension.db:plugin.conferencelist.mode.selected</label>
<value>selected</value>
</numIndex>
</items>
</config>
</settings.mode>
<settings.conferences>
<label>my_extension.db:plugin.conferencelist.conferences</label>
<displayCond>FIELD:settings.mode:=:selected</displayCond>
<config>
<type>group</type>
<allowed>tx_myextension_conference</allowed>
</config>
</settings.conferences>
<settings.categories>
<label>my_extension.db:plugin.conferencelist.categories</label>
<config>
<type>category</type>
</config>
</settings.categories>
<settings.display>
<label>my_extension.db:plugin.conferencelist.display</label>
<config>
<type>check</type>
<items>
<numIndex index="0">
<label>my_extension.db:plugin.conferencelist.display.logo</label>
</numIndex>
<numIndex index="1">
<label>my_extension.db:plugin.conferencelist.display.location</label>
</numIndex>
<numIndex index="2">
<label>my_extension.db:plugin.conferencelist.display.speakers</label>
</numIndex>
<numIndex index="3">
<label>my_extension.db:plugin.conferencelist.display.date</label>
</numIndex>
</items>
<cols>3</cols>
<default>15</default>
</config>
</settings.display>
<settings.limit>
<label>my_extension.db:plugin.conferencelist.limit</label>
<displayCond>
<or>
<value1>FIELD:settings.mode:=:upcoming</value1>
<value2>FIELD:settings.mode:=:past</value2>
</or>
</displayCond>
<config>
<type>number</type>
<default>10</default>
</config>
</settings.limit>
<settings.country>
<label>my_extension.db:plugin.conferencelist.country</label>
<config>
<type>country</type>
<labelField>localizedName</labelField>
<size>4</size>
<prioritizedCountries>
<numIndex index="0">CH</numIndex>
<numIndex index="1">DE</numIndex>
<numIndex index="2">AT</numIndex>
</prioritizedCountries>
</config>
</settings.country>
<settings.timezone>
<label>my_extension.db:plugin.conferencelist.timezone</label>
<config>
<type>select</type>
<renderType>selectSingle</renderType>
<items>
<numIndex index="0">
<label></label>
<value></value>
</numIndex>
</items>
<itemsProcessors>
<numIndex index="100">
<class>MyVendor\MyExtension\Backend\ItemsProcessor\TimezoneItemsProcessor</class>
<parameters>
<regions>Europe</regions>
</parameters>
</numIndex>
</itemsProcessors>
</config>
</settings.timezone>
</el>
</ROOT>
</sDEF>
<sHighlights>
<ROOT>
<sheetTitle>my_extension.db:plugin.conferencelist.sheet.highlights</sheetTitle>
<sheetDescription>my_extension.db:plugin.conferencelist.sheet.highlights.description</sheetDescription>
<type>array</type>
<el>
<settings.introduction>
<label>my_extension.db:plugin.conferencelist.introduction</label>
<config>
<type>text</type>
<enableRichtext>1</enableRichtext>
</config>
</settings.introduction>
<settings.highlights>
<title>my_extension.db:plugin.conferencelist.highlights</title>
<type>array</type>
<section>1</section>
<el>
<highlight>
<title>my_extension.db:plugin.conferencelist.highlight</title>
<type>array</type>
<el>
<title>
<label>my_extension.db:plugin.conferencelist.highlight.title</label>
<config>
<type>input</type>
</config>
</title>
<link>
<label>my_extension.db:plugin.conferencelist.highlight.link</label>
<config>
<type>link</type>
</config>
</link>
</el>
</highlight>
</el>
</settings.highlights>
</el>
</ROOT>
</sHighlights>
</sheets>
</T3DataStructure>
Access values in a flexform
Flex form fields can access field values from various different sources.
Each of the following conditions is an alternative for the display of
one field:
<!-- Hide field if value of record field "header" is not "true" -->
<displayCond>FIELD:parentRec.header:REQ:true</displayCond>
<!-- Hide field if value of parent record field "layout" is not "1" -->
<displayCond>FIELD:parentRec.layout:=:1</displayCond>
<!-- Hide field if value of neighbour field "settings.mode" on same sheet is not "selected" -->
<displayCond>FIELD:settings.mode:=:selected</displayCond>
<!-- Hide field if value of field "settings.mode" from sheet "sDEF" is not "selected" -->
<displayCond>FIELD:sDEF.settings.mode:=:selected</displayCond>Technical background
The display conditions are implemented in class
\TYPO3\,
which is a FormDataProvider.
It can be used for fields directly in the record as well as for
FlexForm values.