TCA column type check
New in version 13.0
When using the check
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.
Introduction
This type creates checkbox(es).
There can be between 1 and 31 checkboxes. The corresponding database field must be of type integer. Each checkbox corresponds to a single bit of the integer value, even if there is only one checkbox.
Tip
This means that you should check the bits of values from single-checkbox fields and not just whether it is true or false.
There is a subtle difference between fields of the type check
and select
fields with the render type
selectCheckBox. For the
details please see: selectCheckBox and type check fields compared.
Warning
Resorting the 'items' of a type='check' config results in single items moving to different bit positions. It might be required to migrate existing field data if doing so.
The following renderTypes are available:
- default: One or more checkboxes are displayed.
- checkboxToggle: Instead of checkboxes, a toggle item is displayed.
- checkboxLabeledToggle: A toggle
switch where both states can be labelled (ON/OFF, Visible / Hidden or alike).
Its state can be inverted via
invert
State Display
Properties of the TCA column type check
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
cols
-
- Type
- integer/string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
- Examples
- Example: Default checkboxes with fixed columns, Example: Checkboxes with Inline columns and default value
In how many columns the checkboxes will be shown. Makes sense only if the 'items' property is defining multiple checkboxes.
Allowed values are 1, 2, 3, ..., 31 or
inline
, 1 being default. If set toinline
the checkboxes are "floating" and there will be as many in one row as fits to browser width.Note checkboxes will still wrap if browser width is not sufficient.
Examples Fixes columns -------------
[
'columns' => [
'checkbox_2' => [
'label' => 'checkbox_2',
'description' => 'one checkbox with label',
'config' => [
'type' => 'check',
'items' => [
[
'label' => 'foo',
],
],
],
],
],
]
default
-
- Type
- integer
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
- Examples
- Example: Checkboxes with Inline columns and default value
The default value of the checkbox(es).
Each bit of the decimal value corresponds to a checkbox. As an example, the value
5
enables the first and third checkbox.This is true even if there is only one checkbox, which then maps to the first bit (reading from right to left).
decimal value binary representation selected checkboxes 0 0000 0000 none 1 0000 0001 first 2 0000 0010 second 5 0000 0101 first, third 127 0111 1111 the first seven To find out the right default decimal value, first start off by writing down the binary representation and set the desired bits at the appropriate position to 1. Then convert the binary number to decimal. You can either use a calculator with programmer mode or search online for "binary to decimal".
eval
-
- Type
- string (list of keywords)
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Proc. / Display
- Example
- Example: Checkbox limited to a maximal number of checked records
Configuration of field evaluation.
Keywords:
- maximumRecordsChecked
-
If this evaluation is defined, the maximum number of records from the same table that can have this box checked will be limited. If someone tries to check the box of a record beyond the allowed maximum, the box will be unchecked automatically upon saving.
The actual limit is defined with the validation property validation.
- maximumRecordsCheckedInPid
- Similar to
maximum
but with the validation scope limited to records stored in the same page.Records Checked
fieldInformation
-
For details see fieldInformation.
fieldWizard
-
defaultLanguageDifferences
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['defaultLanguageDifferences']
For details see defaultLanguageDifferences.
localizationStateSelector
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']
For details see localizationStateSelector.
otherLanguageContent
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['otherLanguageContent']
For details see otherLanguageContent.
invertStateDisplay
-
- Type
- boolean
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
- Default
- false
- Example
- Example: Toggle checkbox with invertStateDisplay
The state of a checkbox can be displayed inverted when this property is set to true.
items
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
- Example
- Example: Three checkboxes, two with labels, one without
If set, this array will create an array of checkboxes instead of just a single "on/off" checkbox.
Note
You can have a maximum of 31 checkboxes in such an array and each element is represented by a single bit in the integer value which ultimately goes into the database.
In this array each entry is itself an associative array. The value sent to the database will be an integer representing a bit mask based on the position of the checkbox in this array.
A basic item looks like this:
'items' => [ ['label' => 'Green tomatoes'], // Note these should be LLL references ['label' => 'Red peppers'], ],
Copied!Use the
label
key, instead of the numerical index0
which was done in previous versions.Further properties can be set per item, but not all of them apply to all renderTypes:
- label (string or LLL reference)
- The displayed title.
- invertStateDisplay (boolean)
- All renderTypes. If set to true, checked / unchecked state are swapped in view: A checkbox is marked checked if the database bit is not set and vice versa.
- iconIdentifierChecked (string)
- Only if renderType is not set (default): An optional icon shown is selected / on. If not set, a check mark icon is used.
- iconIdentifierUnchecked (string)
- Only if renderType is not set (default): An optional icon shown selected / on. If not set, no icon is show (check mark icon not displayed).
- labelChecked (string)
- Mandatory property for renderType
checkbox
: Text shown if element is selected / on.Labeled Toggle - labelUnchecked (string)
- Mandatory property for renderType
checkbox
: Text shown if element is not selected.Labeled Toggle
itemsProcFunc
-
- Type
- string (class->method reference)
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
- Example
- Example: Checkboxes with itemsProcFunc
PHP method which is called to fill or manipulate the items array. It is recommended to use the actual FQCN with
class
and then concatenate the method:\VENDOR\
Extension\ User Function\ Form Engine\ Your Class:: class . '->your Method' This becomes handy when using an IDE and doing operations like renaming classes.
The provided method will have an array of parameters passed to it. The items array is passed by reference in the key
items
. By modifying the array of items, you alter the list of items. A method may throw an exception which will be displayed as a proper error message to the user.Passed parametersitems
(passed by reference)config
(TCA config of the field)TSconfig
(The matching itemsProcFunc TSconfig)table
(current table)row
(current database record)field
(current field name)effective
(correct page ID)Pid site
(current site)
The following parameter only exists if the field has a flex parent.
flex
Parent Database Row
The following parameters are filled if the current record has an inline parent.
inline
Parent Uid inline
Parent Table Name inline
Parent Field Name inline
Parent Config inline
Top Most Parent Uid inline
Top Most Parent Table Name inline
Top Most Parent Field Name
readOnly
-
- Type
- boolean
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- 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.
renderType
-
- Type
- boolean
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
- Default
- check
- Examples
- default, checkboxToggle, checkboxLabeledToggle
Three different render types are currently available for the check box field:
validation
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Proc.
- Example
- Example: Only one record can be checked
Values for the eval rules. The keys of the array must correspond to the keyword of the related evaluation rule. For
maximum
andRecords Checked maximum
the value is expected to be an integer.Records Checked In Pid