selectSingle

Single select fields display a select field from which only one value can be chosen.

The renderType selectSingle creates a drop-down box with items to select a single value. Only if size is set to a value greater than one, a box is rendered containing all selectable elements from which one can be chosen.

Table of contents

Examples for select fields with renderType `selectSingle`

Simple select drop down with static and database values

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_3' => [
            'label' => 'select_single_3 static values, dividers, foreign_table_where',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Static values',
                        'value' => '--div--',
                    ],
                    [
                        'label' => 'static -2',
                        'value' => -2,
                    ],
                    [
                        'label' => 'static -1',
                        'value' => -1,
                    ],
                    [
                        'label' => 'DB values',
                        'value' => '--div--',
                    ],
                ],
                'foreign_table' => 'tx_styleguide_staticdata',
                'foreign_table_where' => 'AND {#tx_styleguide_staticdata}.{#value_1} LIKE \'%foo%\' ORDER BY uid',
                'foreign_table_prefix' => 'A prefix: ',
            ],
        ],
    ],
]

Select foreign rows with icons

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

Select a single value from a list of elements

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_10' => [
            'label' => 'select_single_10 size=6, three options',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'foo 1',
                        'value' => 1,
                    ],
                    [
                        'label' => 'foo 2',
                        'value' => 2,
                    ],
                    [
                        'label' => 'a divider',
                        'value' => '--div--',
                    ],
                    [
                        'label' => 'foo 3',
                        'value' => 3,
                    ],
                ],
                'size' => 6,
            ],
        ],
    ],
]

Properties of the TCA column type `select` with renderType `selectSingle`

Name	Type	Scope
allowNonIdValues	boolean	Proc.
authMode	string (keyword)	Display / Proc.
autoSizeMax	integer	Display
behaviour
allowLanguageSynchronization	boolean	Proc.
default	string	Display / Proc.
disableNoMatchingValueElement	boolean	Display
fieldControl
fieldInformation
fieldWizard
defaultLanguageDifferences	array
localizationStateSelector	array
otherLanguageContent	array
selectIcons	array	fieldWizard
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.
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	boolean	Proc.
multiple	boolean	Display / Proc.
readOnly	boolean	Display
size	integer	Display
sortItems	array	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

Changed in version 12.0

The only valid value for TCA config option authMode is now explicitAllow. The values explicitDeny and individual are obsolete and no longer evaluated.

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.

Changed in version 12.0

Handling of TCA config option authMode_enforce has been removed.

Migration: Using authMode_enforce='strict'

Extensions with select fields using authMode previously had different handling if authMode_enforce => 'strict' has been set: Let us say an editor accesses a record with an authMode field being set to a value it has no access to. With authMode_enforce not being set to strict, the editor was still able to edit the record and set the value to something it had access to. With authMode_enforce being set to strict, the editor was not allowed to access the record. This has been streamlined: The backend interface no longer renders those records for the editor and an "access denied" message is rendered instead. To prevent this, a group this editor is member of needs to be adapted to allow access to this particular value in the "Explicitly allow field values" (explicit_allowdeny) field.

autoSizeMax

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

The maximum size (height) of the select field.

The size of the select field will be automatically adjusted based on the number of selected items. The select field will never be smaller than the specified size and never larger than the value of autoSizeMax.

Note

Only has an effect if maxitems is greater than 1.

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

$inlineField = [
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingle',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];

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: For details see fieldControl.

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.

selectIcons

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['selectIcons']
Scope: fieldWizard

Render thumbnails of icons below the select drop-down. Disabled by default.

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

Example: A select field with a foreign_table_item_group

<?php

$selectField = [
    'label' => 'select_field',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingle',
        'items' => [
            [
                'label' => 'static item 1',
                'value' => 'static-1',
                'group' => 'group1',
            ],
        ],
        'itemGroups' => [
            'group1' => 'Group 1 with items',
            'group2' => 'Group 2 from foreign table',
        ],
        'foreign_table' => 'tx_myextension_foreign_table',
        'foreign_table_item_group' => 'itemgroup',
    ],
];

foreign_table_prefix

Type: string or LLL reference
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope: Display
RenderType: all

Label prefix to the title of the records from the foreign-table.

Example: Select single field with foreign_prefix and foreign_where

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_3' => [
            'label' => 'select_single_3 static values, dividers, foreign_table_where',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Static values',
                        'value' => '--div--',
                    ],
                    [
                        'label' => 'static -2',
                        'value' => -2,
                    ],
                    [
                        'label' => 'static -1',
                        'value' => -1,
                    ],
                    [
                        'label' => 'DB values',
                        'value' => '--div--',
                    ],
                ],
                'foreign_table' => 'tx_styleguide_staticdata',
                'foreign_table_where' => 'AND {#tx_styleguide_staticdata}.{#value_1} LIKE \'%foo%\' ORDER BY uid',
                'foreign_table_prefix' => 'A prefix: ',
            ],
        ],
    ],
]

foreign_table_where

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

The items from foreign_table are selected with this WHERE clause. The WHERE clause is effectively appended to the existing WHERE clause (which contains default constraints, such as NOT deleted) and must begin with AND.

Field quoting

The example below uses the special field quoting syntax {#...} around identifiers to be as DBAL-compatible as possible. Note that ORDER BY and GROUP BY should NOT be quoted, since they always receive proper quoting automatically through the API.

Markers inside the WHERE statement

It is possible to use markers in the WHERE clause:

###REC_FIELD_[field name]###: Any field of the current record.

Note

The field name part of the marker is not in upper case letters. It must match the exact case used in the database.

So for example sys_language_uid must be referenced using ###REC_FIELD_sys_language_uid###
###THIS_UID###: Current element uid (zero if new).
###CURRENT_PID###: The current page id (pid of the record).

###SITEROOT###

###PAGE_TSCONFIG_ID###: A value you can set from Page TSconfig dynamically.
###PAGE_TSCONFIG_IDLIST###: A value you can set from Page TSconfig dynamically.
###PAGE_TSCONFIG_STR###: A value you can set from Page TSconfig dynamically.
###SITE:<KEY>.<SUBKEY>###: A value from the site configuration, for example: ###SITE:mySetting.categoryPid### or ###SITE:rootPageId###.

The markers are preprocessed so that the value of CURRENT_PID and PAGE_TSCONFIG_ID are always integers (default is zero), PAGE_TSCONFIG_IDLIST will always be a comma-separated list of integers (default is zero) and PAGE_TSCONFIG_STR will be quoted before substitution (default is blank string).

More information about markers set by Page TSconfig can be found in the TSconfig reference.

Example: Select single field with foreign_prefix and foreign_where

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_3' => [
            'label' => 'select_single_3 static values, dividers, foreign_table_where',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Static values',
                        'value' => '--div--',
                    ],
                    [
                        'label' => 'static -2',
                        'value' => -2,
                    ],
                    [
                        'label' => 'static -1',
                        'value' => -1,
                    ],
                    [
                        'label' => 'DB values',
                        'value' => '--div--',
                    ],
                ],
                'foreign_table' => 'tx_styleguide_staticdata',
                'foreign_table_where' => 'AND {#tx_styleguide_staticdata}.{#value_1} LIKE \'%foo%\' ORDER BY uid',
                'foreign_table_prefix' => 'A prefix: ',
            ],
        ],
    ],
]

itemGroups

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

Contains an array of key-value pairs. The key contains the id of the item group, the value contains the label of the item group or its language reference.

Only groups containing items will be displayed. In the select field first all items with no group defined are listed then the item groups in the order of their definition, each group with the corresponding items.

Item groups are rendered as <optgroup>.

Item groups can also be defined for items in foreign tables.

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.

Items registered for the field CType of table tt_content get automatically added to the New content element wizard. Settings from the items property can be overridden via page TSconfig newContentElement.wizardItems.

Deprecated since version 12.3

Using the numerical indexes 0 - 4 is deprecated. Use the newly introduced keys.

Each element in this array is in itself an associative array.

label (string or LLL reference)

The displayed title.

value (integer or string)

The value stored in the database.

The special value --div-- was used to insert a non-selectable

value that appears as a divider label in the selector box. It is kept for backwards-compatible reasons. Use item groups for custom selects instead.
Values must not contain , (comma) and | (vertical bar). If you want to use authMode, you should

also refrain from using : (colon).

icon (EXT: path or icon identifier)

Optional icon. For custom icons use a path prepended with EXT: to refer to an image file found inside an extension or use an registered icon identifier. If configured on the foreign_table, selicon-field is respected.

group (string)

The key of the item group.

description (string or array)

Fifth value is an optional description text. This is only shown when the list is shown with renderType='selectCheckBox'.

Note

When having a zero as value and the field is of type int(10) in the database, make sure to define the default value as well in TCA: 'default' => 0. Otherwise issues may arise, e.g. with MySQL strict mode.

Example: Simple items definition with label and value

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_1' => [
            'label' => 'select_single_1 two items, long text description',
            'description' => 'field description',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'foo and this here is very long text that maybe does not really fit into the form in one line. Ok let us add even more text to see how this looks like if wrapped. Is this enough now? No? Then let us add some even more useless text here!',
                        'value' => 1,
                    ],
                    [
                        'label' => 'bar',
                        'value' => 'bar',
                    ],
                ],
            ],
        ],
    ],
]

Example: Items definition with label, value and icon

A more complex example could be this (includes icons):

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_4' => [
            'label' => 'select_single_4 items with icons',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'foo 1',
                        'value' => 'foo1',
                        'icon' => 'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg',
                    ],
                    [
                        'label' => 'foo 2',
                        'value' => 'foo2',
                        'icon' => 'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg',
                    ],
                ],
            ],
        ],
    ],
]

Example: SelectSingle field with itemGroups

A select single field of size 6 with 3 item groups and one item without group.

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

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.

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.

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

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

Type: boolean
Scope: Proc.

If the "multiple" feature is used with MM relations you must set this value to true and include a UID field. Otherwise sorting and removing relations will be buggy.

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.

The property MM_hasUidField has to be defined 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

If set to 1 (default), displays a select drop-down, else a select box of given size.

sortItems

sortItems

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

The property sortItems allows sorting of static select items by their values or labels.

Built-in orderings are to sort items by their labels or values. It is also possible to define custom sorting via PHP code.

When using grouped select fields with itemGroups, sorting happens on a per-group basis - all items within one group are sorted - as the group ordering is preserved.

Examples

Sort items by label

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_18' => [
            'label' => 'select_single_18',
            'description' => 'sortItems label asc',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Plum tree',
                        'value' => 1,
                    ],
                    [
                        'label' => 'Walnut tree',
                        'value' => 2,
                    ],
                    [
                        'label' => 'Apple tree',
                        'value' => 3,
                    ],
                    [
                        'label' => 'Cherry tree',
                        'value' => 4,
                    ],
                ],
                'sortItems' => [
                    'label' => 'asc',
                ],
                'size' => 4,
            ],
        ],
    ],
]

Sort items by value

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_19' => [
            'label' => 'select_single_19',
            'description' => 'sortItems value desc',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Plum tree',
                        'value' => 1,
                    ],
                    [
                        'label' => 'Walnut tree',
                        'value' => 2,
                    ],
                    [
                        'label' => 'Apple tree',
                        'value' => 3,
                    ],
                    [
                        'label' => 'Cherry tree',
                        'value' => 4,
                    ],
                ],
                'sortItems' => [
                    'value' => 'desc',
                ],
                'size' => 4,
            ],
        ],
    ],
]

Sort items by a custom method

The following custom method sorts the items by their reversed labels:

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_select.php

[
    'columns' => [
        'select_single_20' => [
            'label' => 'select_single_20',
            'description' => 'sortItems custom',
            'config' => [
                'type' => 'select',
                'renderType' => 'selectSingle',
                'items' => [
                    [
                        'label' => 'Plum tree',
                        'value' => 1,
                    ],
                    [
                        'label' => 'Walnut tree',
                        'value' => 2,
                    ],
                    [
                        'label' => 'Apple tree',
                        'value' => 3,
                    ],
                    [
                        'label' => 'Cherry tree',
                        'value' => 4,
                    ],
                ],
                'sortItems' => [
                    'tx_styleguide' => 'TYPO3\\CMS\\Styleguide\\UserFunctions\\FormEngine\\SelectItemSorter->sortReverseTitles',
                ],
                'size' => 4,
            ],
        ],
    ],
]

<?php

declare(strict_types=1);

namespace TYPO3\CMS\Styleguide\UserFunctions\FormEngine;

/**
 * This file is part of the TYPO3 CMS project.
 *
 * It is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License, either version 2
 * of the License, or any later version.
 *
 * For the full copyright and license information, please read the
 * LICENSE.txt file that was distributed with this source code.
 *
 * The TYPO3 project - inspiring people to share!
 */

/**
 * A user function to sort ites
 */
class SelectItemSorter
{
    /**
     * Sort items by their reverse titles
     *
     * @param array $items
     */
    public function sortReverseTitles(&$items): void
    {
        @usort(
            $items,
            function ($item1, $item2) {
                return strcasecmp(strrev((string)$item1[0]), strrev((string)$item2[0]));
            }
        );
    }
}

selectSingle

Examples for select fields with renderType selectSingle

Simple select drop down with static and database values

Select foreign rows with icons

Select a single value from a list of elements

Properties of the TCA column type select with renderType selectSingle

allowNonIdValues

authMode

autoSizeMax

behaviour

allowLanguageSynchronization

default

disableNoMatchingValueElement

fieldControl

fieldInformation

fieldWizard

defaultLanguageDifferences

localizationStateSelector

otherLanguageContent

selectIcons

fileFolderConfig

allowedExtensions

depth

folder

foreign_table

foreign_table_item_group

foreign_table_prefix

foreign_table_where

itemGroups

items

itemsProcFunc

maxitems

minitems

MM

MM_match_fields

MM_opposite_field

MM_oppositeUsage

MM_table_where

MM_hasUidField

multiple

readOnly

size

sortItems

sortItems

Examples

Sort items by label

Sort items by value

Sort items by a custom method

Examples for select fields with renderType `selectSingle`

Properties of the TCA column type `select` with renderType `selectSingle`