Select multiple values (selectSingleBox)¶

This page describes the select type with renderType='selectSingleBox'.

The according database field is generated automatically.

Note

The name is misleading. This is a renderType which allows you to select multiple elements!

Renders a select field to select multiple entries from a given list.

Table of contents

Example: Select multiple values from a box¶

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_singlebox_1' => [
            'label' => 'select_singlebox_1 description',
            'description' => 'field description',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingleBox',
                'items' => [
                    [
                        'label' => 'foo 1',
                        'value' => 1,
                    ],
                    [
                        'label' => 'foo 2',
                        'value' => 2,
                    ],
                    [
                        'label' => 'divider',
                        'value' => '--div--',
                    ],
                    [
                        'label' => 'foo 3',
                        'value' => 3,
                    ],
                    [
                        'label' => 'foo 4',
                        'value' => 4,
                    ],
                ],
            ],
        ],
    ],
]

Properties of the TCA column type `select` with renderType `selectSingleBox`¶

Name	Type	Scope
allowNonIdValues	boolean	Proc.
authMode	string (keyword)	Display / Proc.
behaviour
allowLanguageSynchronization	boolean	Proc.
dbFieldLength	integer	Proc.
default	string	Display / Proc.
disableNoMatchingValueElement	boolean	Display
fieldControl
resetSelection	array	fieldControl
fieldInformation
fieldWizard
defaultLanguageDifferences	array
localizationStateSelector	array
otherLanguageContent	array
fileFolderConfig
allowedExtensions	string	Display / Proc.
depth	integer	Display / Proc.
folder	string	Display / Proc.
foreign_table	string (table name)	Proc. / Display
foreign_table_item_group	string (column name)	Proc. / Display
foreign_table_prefix	string or LLL reference	Display
foreign_table_where	string (SQL WHERE)	Proc. / Display
itemGroups	array	Display / Proc.
items	array	Display / Proc.
itemsProcFunc	string (class->method reference)	Display / Proc.
localizeReferencesAtParentLocalization	boolean	Proc.
maxitems	integer > 0	Display / Proc.
minitems	integer > 0	Display
MM	string (table name)	Proc.
MM_match_fields	array	Display / Proc.
MM_opposite_field	string (field name)	Proc.
MM_oppositeUsage	array	Proc.
MM_table_where	string (SQL WHERE)	Proc.
MM_hasUidField
multiple	boolean	Display / Proc.
readOnly	boolean	Display
size	integer	Display

allowNonIdValues ¶

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc.
RenderType: all

Only useful if foreign_table is enabled.

If set, then values which are not integer ids will be allowed. May be needed if you use itemsProcFunc or just enter additional items in the items array to produce some string-value elements for the list.

Note

If you mix non-database relations with database relations like this, DO NOT use integers for values and DO NOT use "_" (underscore) in values either! Will not work if you also use "MM" relations!

authMode ¶

Type: string (keyword)
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display / Proc.
RenderType: all

Authorization mode for the selector box. The only possible option is:

explicitAllow: All static values from the "items" array of the selector box will be added to a matrix in the backend user configuration where a value must be explicitly selected if a user (other than admin) is allowed to use it!)

Migration: Using authMode='explicitDeny'

The "deny list" approach for single field values has been removed, the only allowed option for authMode is explicitAllow. Extensions using config value explicitDeny should be adapted to switch to explicitAllow instead. The upgrade wizard "Migrate backend groups "explicit_allowdeny" field to simplified format." that transfers existing be_groups rows to the new format, drops any DENY fields and instructs admins to not set new access rights of affected backend groups.

Migration: Using authMode='individual'

Handling of authMode being set to individual has been fully dropped. The Core provides no alternative. This has been an obscure setting ever since and there is no direct migration. Extensions that rely on this handling need to find a substitution based on Core hooks, Core events or other existing Core API functionality.

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

$selectField = [
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingleBox',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];

dbFieldLength ¶

Type: integer
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Default: 255
Scope: Proc.

New in version 13.0

As TYPO3 takes care of generating the according database field for select fields since TYPO3 v13, a developer can adjust the length of the database field with this option in TCA directly.

The TCA config option dbFieldLength contains an integer value that is applied to varchar fields (not text) and defines the length of the database field. It will not be respected for fields that resolve to an integer type. Developers who wish to optimize field length can use dbFieldLength for type=select fields to increase or decrease the default length.

Example: Increase the dbFieldLength for a select field

        Excerpt from EXT:my_extension/Configuration/TCA/myextension_domain_model_mytable.php
    

<?php

$selectField = [
    'label' => 'My field',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingleBox',
        'items' => [
            ['label' => '', 'value' => ''],
            ['label' => 'Some label', 'value' => 'some'],
            ['label' => 'Another label', 'value' => 'another'],
        ],
        'default' => '',
        'dbFieldLength' => 10,
    ],
];

default ¶

Type: string
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display / Proc.
RenderType: all

Default value set if a new record is created. If empty, the first element in the items array is selected.

disableNoMatchingValueElement ¶

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display
RenderType: all

If set, then no element is inserted if the current value does not match any of the existing elements. A corresponding options is also found in Page TSconfig.

fieldControl ¶

resetSelection ¶

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']
Scope: fieldControl
Types: Description

Render a button next to the select box to reset a changed selection to the state before it was manipulated by the user.

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.

fileFolderConfig ¶

allowedExtensions ¶

Type: string
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fileFolderConfig']['allowedExtensions']
Scope: Display / Proc.

List of file extensions to select. If blank, all files are selected. Specify list in lowercase.

This configuration can be overridden by Page TSconfig.

depth ¶

Type: integer
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fileFolderConfig']['depth']
Scope: Display / Proc.
RenderType: all

Depth of directory recursions. Default is 99. Specify in range from 0-99. 0 (zero) means no recursion into subdirectories. Only useful in combination with property folder.

This configuration can be overridden by Page TSconfig.

folder ¶

Type: string
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fileFolderConfig']['folder']
Scope: Display / Proc.

Specifying a folder from where files are added to the item array.

Specify the folder relative to the \TYPO3\CMS\Core\Core\Environment::getPublicPath(). See getPublicPath() . Alternatively use the prefix "EXT:" to point to an extension folder.

Files from the folder are selected recursively to the level specified by depth and only files of the extensions defined by allowedExtensions are listed in the select box.

Only the file reference relative to the folder is stored.

If the files are images (gif,png,jpg) they will be configured as icons (third parameter in items array).

This configuration can be overridden by Page TSconfig.

Examples: Select SVGs recursively from a folder

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_7' => [
            'label' => 'select_single_7 fileFolder, dummy first entry, selectIcons',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => '',
                        'value' => 0,
                    ],
                ],
                'fileFolderConfig' => [
                    'folder' => 'EXT:styleguide/Resources/Public/Icons',
                    'allowedExtensions' => 'svg',
                    'depth' => 1,
                ],
                'fieldWizard' => [
                    'selectIcons' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

foreign_table ¶

Type: string (table name)
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc. / Display
RenderType: all

The item-array will be filled with records from the table defined here. The table must have a TCA definition.

The uids of the chosen records will be saved in a comma separated list by default.

Use property MM <columns-select-singlebox-properties-mm> to store the values in an intermediate MM table instead.

Deprecated since version 11.2

Usage of the foreign_table relation with the table sys_language Has been deprecated. Use TCA field type called language instead.

Example: Select singe field with enabled selectIcons

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_12' => [
            'label' => 'select_single_12 foreign_table selicon_field',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'foreign_table' => 'tx_styleguide_elements_select_single_12_foreign',
                'fieldWizard' => [
                    'selectIcons' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Example: Select field with foreign table via MM table

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_15' => [
            'label' => 'select_single_15 foreign_table',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'foreign_table' => 'tx_styleguide_staticdata',
                'MM' => 'tx_styleguide_elements_select_single_15_mm',
            ],
        ],
    ],
]

foreign_table_item_group ¶

Type: string (column name)
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc. / Display
RenderType: all

New in version 13.0

This property references a specific field in the foreign table, which holds an item group identifier.

See also Item group API methods

Example: SelectSingle field with itemGroups

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_16' => [
            'label' => 'select_single_16',
            'description' => 'itemGroups',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'item 1',
                        'value' => 1,
                        'group' => 'group1',
                    ],
                    [
                        'label' => 'item 2',
                        'value' => 2,
                        'group' => 'group1',
                    ],
                    [
                        'label' => 'item 3',
                        'value' => 3,
                        'group' => 'group3',
                    ],
                    [
                        'label' => 'item 4',
                        'value' => 3,
                    ],
                ],
                'itemGroups' => [
                    'group1' => 'Group 1 with items',
                    'group2' => 'Group 2 with no items',
                    'group3' => 'Group 3 with items',
                ],
            ],
        ],
    ],
]

Example: SelectSingle field with itemGroups, size=6

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_17' => [
            'label' => 'select_single_16',
            'description' => 'itemGroups, size=6',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'item 1',
                        'value' => 1,
                        'group' => 'group1',
                    ],
                    [
                        'label' => 'item 2',
                        'value' => 2,
                        'group' => 'group1',
                    ],
                    [
                        'label' => 'item 3',
                        'value' => 3,
                        'group' => 'group3',
                    ],
                    [
                        'label' => 'item 4',
                        'value' => 3,
                    ],
                ],
                'itemGroups' => [
                    'group1' => 'Group 1 with items',
                    'group2' => 'Group 2 with no items',
                    'group3' => 'Group 3 with items',
                ],
                'size' => 6,
            ],
        ],
    ],
]

items ¶

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display / Proc.
RenderType: all

Contains the elements for the selector box unless the property foreign_table or special has been set in which case automated values are set in addition to any values listed in this array.

For examples see also property items of singleSelect.

itemsProcFunc ¶

Type: string (class->method reference)
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display / Proc.

PHP method which is called to fill or manipulate the items array. See itemsProcFunc about details.

localizeReferencesAtParentLocalization ¶

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc.

Defines whether referenced records should be localized when the current record gets localized. This only applies if references are not stored using MM tables.

maxitems ¶

Type: integer > 0
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display / Proc.

Maximum number of child items. Defaults to a high value. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

minitems ¶

Type: integer > 0
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display

Minimum number of child items. Defaults to 0. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

New in version 11.4

TCA table column fields that define ['config']['MM'] can omit the specification of the intermediate MM table layout in ext_tables.sql. The TYPO3 database analyzer takes care of proper schema definition.

Extensions are strongly encouraged to drop CREATE TABLE definitions from the ext_tables.sql file for those intermediate tables referenced by TCA table columns. Dropping these definitions allows the Core to adapt and migrate definitions if needed.

MM ¶

Type: string (table name)
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc.

This value contains the name of the table in which to store a MM relation. It is used together with foreign_table.

The database field with a MM property only stores the number of records in the relation.

Please have a look into the additional information in the MM common property description.

MM_match_fields ¶

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display / Proc.

Array of field => value pairs to both insert and match against when writing/reading MM relations.

MM_opposite_field ¶

Type: string (field name)
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc.

If you want to make a MM relation editable from the foreign side (bidirectional) of the relation as well, you need to set MM_opposite_field on the foreign side to the field name on the local side.

For example, if the field companies.employees is your local side and you want to make the same relation editable from the foreign side of the relation in a field called persons.employers, you would need to set the MM_opposite_field value of the TCA configuration of the persons.employers field to the string "employees".

Note

Bidirectional references only get registered once on the native side in sys_refindex.

MM_oppositeUsage ¶

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc.

In a MM bidirectional relation using match fields the opposite side needs to know about the match fields for certain operations (for example, when a copy is created in a workspace) so that relations are carried over with the correct information.

MM_oppositeUsage is an array which references which fields contain the references to the opposite side, so that they can be queried for match field configuration.

MM_table_where ¶

Type: string (SQL WHERE)
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Proc.

Additional where clause used when reading MM relations.

Example:

{#uid_local} = ###THIS_UID###

The above example uses the special field quoting syntax {#...} around identifiers to be as DBAL-compatible as possible.

MM_hasUidField ¶: Changed in version 13.0

This setting is obsolete. Remove all occurrences of MM_hasUidField from TCA. The uid column is added as primary key automatically, if multiple = true is set, otherwise a combined primary key of fields uid_local, uid_foreign plus eventually tablenames and fieldname is used.

multiple ¶

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display / Proc.

Allows the same item more than once in a list.

If used with bidirectional MM relations it must be set for both the native and foreign field configuration.

Changed in version 13.0

The property MM_hasUidField is obsolete. It had to be defined previously when using multiple.

readOnly ¶

Type: boolean
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['readOnly']
Scope: Display

Renders the field in a way that the user can see the value but cannot edit it.

Warning

This property affects only the display. It is still possible to write to those fields when using the DataHandler.

size ¶

Type: integer
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display
Default: 1

Height of the box in FormEngine. This value should not be set to a number smaller than 2.

Select multiple values (selectSingleBox)¶

Example: Select multiple values from a box¶

Properties of the TCA column type select with renderType selectSingleBox¶

Properties of the TCA column type `select` with renderType `selectSingleBox`¶