TCA column type check

New in version 13.0

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.

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.

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
boolean Proc.
integer/string Display
integer Display / Proc.
string (list of keywords) Proc. / Display
array
array
array
boolean Display
array Display
string (class->method reference) Display / Proc.
boolean Display
boolean Display
array Proc.

behaviour

behaviour

allowLanguageSynchronization

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,
        ],
    ],
];
Copied!

cols

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

default

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

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

fieldInformation

For details see fieldInformation.

fieldWizard

fieldWizard

defaultLanguageDifferences

defaultLanguageDifferences
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['defaultLanguageDifferences']

For details see defaultLanguageDifferences.

localizationStateSelector

localizationStateSelector
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']

For details see localizationStateSelector.

otherLanguageContent

otherLanguageContent
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['otherLanguageContent']

For details see otherLanguageContent.

invertStateDisplay

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

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.

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

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

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.

renderType

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

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.