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_tables.sql 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 invertStateDisplay

Properties of the TCA column type `check`

Name	Type	Scope
behaviour
allowLanguageSynchronization	boolean	Proc.
cols	integer/string	Display
default	integer	Display / Proc.
eval	string (list of keywords)	Proc. / Display
fieldInformation
fieldWizard
defaultLanguageDifferences	array
localizationStateSelector	array
otherLanguageContent	array
invertStateDisplay	boolean	Display
items	array	Display
itemsProcFunc	string (class->method reference)	Display / Proc.
readOnly	boolean	Display
renderType	boolean	Display
validation	array	Proc.

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_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

$jsonField = [
    'config' => [
        'type' => 'check',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];

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 to inline 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 -------------

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_basic.php

[
    '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 maximumRecordsChecked but with the validation scope limited to records stored in the same page.

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'],
],

Use the label key, instead of the numerical index 0 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 checkboxLabeledToggle: Text shown if element is selected / on.
labelUnchecked (string): Mandatory property for renderType checkboxLabeledToggle: Text shown if element is not selected.

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\UserFunction\FormEngine\YourClass::class . '->yourMethod'

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 parameters

items (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)
effectivePid (correct page ID)
site (current site)

The following parameter only exists if the field has a flex parent.

flexParentDatabaseRow

The following parameters are filled if the current record has an inline parent.

inlineParentUid
inlineParentTableName
inlineParentFieldName
inlineParentConfig
inlineTopMostParentUid
inlineTopMostParentTableName
inlineTopMostParentFieldName

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 maximumRecordsChecked and maximumRecordsCheckedInPid the value is expected to be an integer.

TCA column type check

Introduction

Properties of the TCA column type check

behaviour

allowLanguageSynchronization

cols

default

eval

fieldInformation

fieldWizard

defaultLanguageDifferences

localizationStateSelector

otherLanguageContent

invertStateDisplay

items

itemsProcFunc

readOnly

renderType

validation

TCA column type `check`

Properties of the TCA column type `check`