Select

The Select type generates a simple select field.

Settings

Name	Type	Default	Required
renderType	string		true
items	array
default	string
maxitems	integer
minitems	integer
relationship	string	oneToMany
dbFieldLength	int	255
allowedCustomProperties	array	["itemsProcConfig"]
allowNonIdValues	boolean	false
appearance.expandAll	boolean
authMode	string
autoSizeMax	integer
behaviour.allowLanguageSynchronization	boolean	false
disableNoMatchingValueElement	boolean
dontRemapTablesOnCopy	array
exclusiveKeys	string
fieldControl	object
fieldInformation	object
fieldWizard	object
fileFolderConfig.allowedExtensions	string
fileFolderConfig.depth	integer	99
fileFolderConfig.folder	string
foreign_table	string
foreign_table_item_group	string
foreign_table_prefix	string
foreign_table_where	string
itemGroups	object
itemsProcessors	object
itemsProcFunc	string
itemsProcConfig	object
localizeReferencesAtParentLocalization	boolean
MM	string
MM_match_fields	object
MM_opposite_field	string
MM_oppositeUsage	object
MM_table_where	string
multiple	boolean	false
readOnly	boolean	false
size	integer	1
sortItems	object
treeConfig.childrenField	string
treeConfig.parentField	string
treeConfig.dataProvider	string
treeConfig.startingPoints	string
treeConfig.appearance.expandAll	boolean
treeConfig.appearance.maxLevels	integer
treeConfig.appearance.nonSelectableLevels	string
treeConfig.appearance.showHeader	boolean

renderType

Type: string
Required: true

selectSingle
selectCheckBox
selectSingleBox
selectTree
selectMultipleSideBySide

items

Type: array

Contains the elements for the selector box. Each item is an array. An item consists of a label and a value.

Example:

items:
  - label: 'The first'
    value: one
  - label: 'The second'
    value: two
  - label: 'The third'
    value: three

Tip

You can omit the label, if you have the translation already in your labels.xlf file.

items:
  - value: one
  - value: two
  - value: three

Tip

You can also use icons so they are displayed in the backend. See Advanced / use case for a full example.

items:
  - value: image-left
    icon: content-beside-text-img-left
  - value: image-right
    icon: content-beside-text-img-right
  - value: image-above
    icon: content-beside-text-img-above-center

For this you need the following setting according to the TCA documentation.

fieldWizard:
  selectIcons:
    disabled: false

XLF translation keys for items have the following convention:

<body>
    <trans-unit id="FIELD_IDENTIFIER.items.one.label">
        <source>Label for item with value one</source>
    </trans-unit>
    <trans-unit id="FIELD_IDENTIFIER.items.two.label">
        <source>Label for item with value two</source>
    </trans-unit>
    <trans-unit id="FIELD_IDENTIFIER.items.VALUE.label">
        <source>Label for item with value VALUE</source>
    </trans-unit>
    <trans-unit id="FIELD_IDENTIFIER.items.label">
        <source>Label for item with empty value</source>
    </trans-unit>
</body>

default

Type: string

Default value set if a new record is created.

maxitems

Type: integer

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. If maxitems ist set to greater than 1, multiselect is automatically enabled.

minitems

Type: integer

Minimum number of items. Default is no minimum. JavaScript record validation prevents the record from being saved if the limit is not satisfied. The field can be set as required by setting minitems to at least 1.

relationship

Type: string
Default: oneToMany

Note

This can only be used in combination with foreign_table.

The relationship defines the cardinality between the relations. Possible values are oneToMany (default), manyToOne and oneToOne. In case of a [x]toOne relation, the processed field will be filled directly with the record instead of a collection of records. In addition, maxitems will be automatically set to 1. If the renderType is set to selectSingle, a relationship manyToOne is automatically inferred.

dbFieldLength

Type: int
Default: 255

This option can be used to set an alternative size for the database varchar column. The default size is 255.

allowedCustomProperties

Type: array
Default: ["itemsProcConfig"]

Sometimes it is needed to provide custom configuration for the itemsProcFunc functionality. These extra properties need to be explicitly allowed via this option. This option receives an array of those strings. By default, the custom option itemsProcConfig is allowed.

allowNonIdValues

Type: boolean
Default: false

Only useful if foreign_table is set. If enabled, values which are not integer ids will be allowed.

appearance.expandAll

Type: boolean

All select groups are initially expanded.

authMode

Type: string

Authorization mode for the selector box. Possible value:

explicitAllow

autoSizeMax

Type: integer

The select field will never be smaller than size and never larger than this value.

behaviour.allowLanguageSynchronization

Type: boolean
Default: false

Allows to select if localization uses custom or default language value.

disableNoMatchingValueElement

Type: boolean

If set, no placeholder element is inserted when the current value does not match any of the existing items.

dontRemapTablesOnCopy

Type: array

A list of tables which should not be remapped to the new element uids if the field holds elements that are copied in the session.

exclusiveKeys

Type: string

Comma-separated list of keys that exclude any other keys in a multi-select box.

fieldControl

Type: object

See TCA fieldControl.

fieldInformation

Type: object

See TCA fieldInformation.

fieldWizard

Type: object

See TCA fieldWizard.

fileFolderConfig.allowedExtensions

Type: string

List of file extensions to select. If blank, all files are selected.

fileFolderConfig.depth

Type: integer
Default: 99

Depth of directory recursion when listing files from fileFolderConfig.folder.

fileFolderConfig.folder

Type: string

Path to the folder from which files are added to the item array.

foreign_table

Type: string

The item array will be filled with records from this table.

foreign_table_item_group

Type: string

References a field in the foreign table that holds an item group identifier.

foreign_table_prefix

Type: string

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

foreign_table_where

Type: string

WHERE clause used when selecting items from foreign_table.

itemGroups

Type: object

Key-value pairs of item group identifiers and their labels. Items can reference a group via the group key.

itemsProcessors

Type: object

A list of PHP classes called to fill or manipulate the items array. Each entry is keyed by a numeric index and requires a class property. An optional parameters object can be passed to the processor.

Example:

itemsProcessors:
  0:
    class: 'Vendor\Extension\ItemsProcessor\MyProcessor'
    parameters:
      foo: bar

itemsProcFunc

Type: string

Deprecated since version 2.3.0

Use itemsProcessors instead.

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

itemsProcConfig

Type: object

Additional configuration passed to itemsProcFunc. Must be listed in allowedCustomProperties (included by default).

localizeReferencesAtParentLocalization

Type: boolean

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

MM

Type: string

Table name for storing the MM relation. Used together with foreign_table.

MM_match_fields

Type: object

Field-value pairs to both insert and match against when writing/reading MM relations.

MM_opposite_field

Type: string

Enables bidirectional MM relations. Set to the field name on the local side when configuring the foreign side.

MM_oppositeUsage

Type: object

Required on the opposite side of a bidirectional MM relation that uses match fields.

MM_table_where

Type: string

Additional WHERE clause used when reading MM relations.

multiple

Type: boolean
Default: false

Allows the same item to be selected more than once in a list.

readOnly

Type: boolean
Default: false

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

size

Type: integer
Default: 1

If set to 1, displays a select drop-down. A higher value renders a select box of the given number of visible rows.

sortItems

Type: object

Sorts the items by label or value in ascending (asc) or descending (desc) order.

Example:

sortItems:
  label: asc

treeConfig.childrenField

Type: string

Field name of the foreign_table that references the uid of the child records. Required when renderType is selectTree and no treeConfig.parentField is set.

treeConfig.parentField

Type: string

Field name of the foreign_table that references the uid of the parent record. Required when renderType is selectTree and no treeConfig.childrenField is set.

treeConfig.dataProvider

Type: string

Custom data provider class for use cases where special data preparation is necessary.

treeConfig.startingPoints

Type: string

Allows setting multiple records as roots for tree records.

treeConfig.appearance.expandAll

Type: boolean

All tree nodes are initially expanded.

treeConfig.appearance.maxLevels

Type: integer

The maximum number of levels to render. Can be used to prevent recursion.

treeConfig.appearance.nonSelectableLevels

Type: string

Comma-separated list of levels that cannot be selected. Defaults to "0" (the root node).

treeConfig.appearance.showHeader

Type: boolean

Whether to show the tree header containing a filter field and expand/collapse-all buttons.

Example

Minimal

Select single:

name: example/select
fields:
  - identifier: select
    type: Select
    renderType: selectSingle
    items:
      - label: 'The first'
        value: one
      - label: 'The second'
        value: two

Select multiple:

name: example/select
fields:
  - identifier: select_side_by_side
    type: Select
    renderType: selectMultipleSideBySide
    items:
      - label: 'The first'
        value: one
      - label: 'The second'
        value: two

Advanced / use case

Select single:

name: example/select
fields:
  - identifier: select
    type: Select
    renderType: selectSingle
    default: 'one'
    items:
      - label: 'The first'
        value: one
      - label: 'The second'
        value: two
      - label: 'The third'
        value: three
    foreign_table: pages
    foreign_table_where: 'AND {#pages}.{#pid} = 123 ORDER BY uid'

Select multiple:

name: example/select
fields:
  - identifier: select_side_by_side
    type: Select
    renderType: selectMultipleSideBySide
    default: 'one'
    minitems: 1
    maxitems: 3
    items:
      - label: 'The first'
        value: one
      - label: 'The second'
        value: two
      - label: 'The third'
        value: three
    foreign_table: pages
    foreign_table_where: 'AND {#pages}.{#pid} = 123 ORDER BY uid'

Select tree:

name: example/select
fields:
  - identifier: select_tree
    type: Select
    renderType: selectTree
    size: 5
    foreign_table: 'pages'
    foreign_table_where: 'ORDER BY pages.uid'
    treeConfig:
      parentField: pid

Select with icons:

name: example/select
fields:
  - identifier: select_icons
    type: Select
    renderType: selectSingle
    fieldWizard:
      selectIcons:
        disabled: false
    default: 'image-left'
    items:
      - label: 'Image beside text (left)'
        value: image-left
        icon: content-beside-text-img-left
      - label: 'Image beside text (right)'
        value: image-right
        icon: content-beside-text-img-right
      - label: 'Image above text (center)'
        value: image-above
        icon: content-beside-text-img-above-cent