Selectors boxes are very common elements in forms. By the "select"
type you can create selector boxes. In the most simple form this is a
list of values among which you can chose only one. In that way it is
similar to the "radio" type above.

A simple selector box with a few options

More complex configurations are possible, see the
examples section for more details.

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.

Each element in this array is in itself an array where:

First value is the item label (string or LLL reference)

Second value is the value of the item .

The special value --div-- is used to insert a non-selectable value
that appears as a divider label in the selector box (only for maxitems
<=1)

Values must not contain "," (comma) and "|" (vertical bar). If you
want to use "authMode" you should also refrain from using ":" (colon).

Third value is an optional icon. Default path is
typo3/sysext/t3skin/icons/gfx/ but is deprecated since TYPO3 CMS 7,
and will be removed with TYPO3 CMS 8.
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.

Fourth value is an optional description text. This is only shown when
the list is shown by renderTypeselectCheckBox.

Fifth value is reserved as keyword "EXPL_ALLOW" or "EXPL_DENY". See
option "authMode" / "individual" for more details.

Note

Usage of path in the third property is deprecated.
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, which is the
prefered way.

PHP function which is called to fill / manipulate the array with
elements.

The function/method will have an array of parameters passed to it
(where the item-array is passed by reference in the key 'items'). By
modifying the array of items, you alter the list of items.
Since TYPO3 CMS 6.2, your function/method may throw an exception which
will be displayed as a proper error message.

For more information, see how user-functions are specified in the
section about wizards some pages below here.

The table is joined with the "pages"-table and items are selected only
from pages where the user has read access! (Not checking DB mount
limitations!)

Example:

AND[foreign_table].pid=0ORDERBY[foreign_table].sorting

Markers:

You can 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.

###THIS_UID### - is current element uid (zero if new).

###CURRENT_PID### - is 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.

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
addslashes'ed before substitution (default is blank string).

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

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.

Notice: 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!

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.

E.g. 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".

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.

This is used by the Core for system categories. Whenever a table
is registered as being categorizable, an entry in MM_oppositeUsage
is created for the "sys_category" table.

Example

With "pages", "tt_content" and "sys_file_metadata" all registered
as categorizable (using the default name of "categories" for the
relations field) plus extension "examples" installed, the TCA
for "sys_category" contains the following definition once
fully assembled:

If set, then the height of multiple-item selector boxes (maxitems > 1)
will automatically be adjusted to the number of selected elements,
however never less than "size" and never larger than the integer value
of "autoSizeMax" itself (takes precedence over "size"). So
"autoSizeMax" is the maximum height the selector can ever reach.

This setting specifies how the select field should be displayed. Available options are:

selectSingle - Normal select field for selecting a single value.

selectSingleBox - Normal select field for selecting multiple values.

selectCheckBox - List of checkboxes for selecting muliple values.

selectMultipleSideBySide - Two select fields, items can be selected from the right
field, selected items are displayed in the left select.

selectTree - A tree for selecting hierarchical data.

Note

Properties "maxitems" and "minitems" are not enforced in the browser
for any of the render types here! However they will be on the server.
It is recommended to set "minitems" to zero and "maxitems" to a very
large number exceeding the possible number of values you can select
(for instance set it to 1000 or so).

Configuration if the renderType
is set to "selectTree". Either childrenField or parentField
has to be set - childrenField takes precedence.

Sub-properties:

dataProvider: Allows to define a custom data provider class for usecases where special data preparation
is necessary. By default \TYPO3\CMS\Core\Tree\TableConfiguration\DatabaseTreeDataProvider is used.

childrenField (string) : Field name of the foreign_table that
references the uid of the child records (either child

parentField (string) : Field name of the foreign_table that
references the uid of the parent record

rootUid (integer, optional) : uid of the record that shall be
considered as the root node of the tree. In general this might be set
by Page TSconfig

appearance (array, optional) :

showHeader (boolean) : Whether to show the header of the tree that
contains a field to filter the records and allows to expand or
collapse all nodes

expandAll (boolean) : Whether to show the tree with all nodes
expanded

maxLevels (integer) : The maximal amount of levels to be rendered
(can be used to stop possible recursions)

nonSelectableLevels (list, default "0") : Comma-separated list of
levels that will not be selectable, by default the root node (which is
"0") cannot be selected

allowRecursiveMode (boolean) : If set to true, the selection
of a node will trigger the selection of all child nodes too (recursively).

width(since TYPO3 CMS 6.0): Set a custom width of the tree select field in pixels.

If used with bidirectional MM relations it must be set for both the
native and foreign field configuration. Also, with MM relations in
general you must use a UID field in the join table, see description
for "MM"

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 explicitlyselected if a user
(other than admin) is allowed to use it!)

explicitDeny – 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 explicitlyselected if a user
should be denied access.

individual – State is individually set for each item in the
selector box. This is done by the keywords " EXPL_ALLOW " and "
EXPL_DENY " entered at the 5. position in the item array (see
"items" configuration above). Items without any of these keywords can
be selected as usual without any access restrictions applied.

Notice: The authentication modes will work only with values that
are statically present in the "items" configuration. Any values added
from foreign tables, file folder or by user processing will not be
configurable and the evaluation of such values is not guaranteed for!

maxitems > 1

"authMode" works also for selector boxes with maxitems > 1. In this
case the list of values is traversed and each value is evaluated. Any
disallowed values will be removed.

If all submitted values turns out to be removed the result will be
that the field is not written – basically leaving the old value. For
maxitems <=1 (single value) this means that a non-allowed value is
just not written. For multiple values (maxitems >1) it depends on
whether any elements are left in the list after evaluation of each
value.

strict - If set, then permission to edit the record will be
granted only if the "authMode" evaluates OK. The default is that a
record having an authMode configured field with a "non-allowed" value
can be edited – just the value of the authMode field cannot be set to
a value that is not allowed. Notice: This works only when maxitems
<=1 (and no MM relations) since the "raw" value in the record is all
that is evaluated!

In the configuration the elements are configured by the "items" array.
Each entry in the array contains pairs of label/value. Notice the
third entry of the "items" array. It defines a divider. This value
cannot be selected. It only helps to divide the list of options with a
label indicating a new section.

The user group selector is based on the fe_groups table. It appears
as a multiple selector:

User groups selector in the access rights configuration

The corresponding TCA configuration:

'fe_group'=>array('exclude'=>1,'label'=>'LLL:EXT:lang/locallang_general.xlf:LGL.fe_group','config'=>array('type'=>'select','renderType'=>'selectMultipleSideBySide','size'=>5,'maxitems'=>20,'items'=>array(array('LLL:EXT:lang/locallang_general.xlf:LGL.hide_at_login',-1),array('LLL:EXT:lang/locallang_general.xlf:LGL.any_login',-2),array('LLL:EXT:lang/locallang_general.xlf:LGL.usergroups','--div--')),'exclusiveKeys'=>'-1,-2','foreign_table'=>'fe_groups','foreign_table_where'=>'ORDER BY fe_groups.title')),

The value stored in the database will be a comma-separated list of uid numbers
of the selected records.

An interesting point of this example is that it shows that static
values can be mixed with values fetched from a database table.

In this case the selector box looks up languages in a static table
from an extension "static_info_tables":

Language selector based on the static_languages table

The configuration looks like this (taken from the "sys_language" table):

'static_lang_isocode'=>array('exclude'=>1,'label'=>'LLL:EXT:lang/locallang_tca.xlf:sys_language.isocode','displayCond'=>'EXT:static_info_tables:LOADED:true','config'=>array('type'=>'select','renderType'=>'selectSingle','items'=>array(array('',0)),'foreign_table'=>'static_languages','foreign_table_where'=>'AND static_languages.pid=0 ORDER BY static_languages.lg_name_en','size'=>1,'minitems'=>0,'maxitems'=>1)),

Notice how a condition is set that this box should only be displayed
if the extension it relies on exists! This is very important since
otherwise the table will not be in the database and we will get SQL
errors.

This example shows how wizards can be added to a selector box. The
three typical wizards for a selector box is edit, add and list items.
This enables the user to create new items in the look up table while
being right at the selector box where he wants to select them:

The configuration is rather long and looks like this (note that
wizards are not exclusively available for selector boxes!):

'file_mountpoints'=>array('label'=>'LLL:EXT:lang/locallang_tca.xlf:be_users.options_file_mounts','config'=>array('type'=>'select','foreign_table'=>'sys_filemounts','foreign_table_where'=>' AND sys_filemounts.pid=0 ORDER BY sys_filemounts.title','size'=>'3','maxitems'=>25,'autoSizeMax'=>10,'wizards'=>array('_VERTICAL'=>1,'edit'=>array('type'=>'popup','title'=>'LLL:EXT:lang/locallang_tca.xlf:file_mountpoints_edit_title','module'=>array('name'=>'wizard_edit',),'icon'=>'edit2.gif','popup_onlyOpenIfSelected'=>1,'JSopenParams'=>'height=350,width=580,status=0,menubar=0,scrollbars=1'),'add'=>array('type'=>'script','title'=>'LLL:EXT:lang/locallang_tca.xlf:file_mountpoints_add_title','icon'=>'add.gif','params'=>array('table'=>'sys_filemounts','pid'=>'0','setValue'=>'prepend'),'module'=>array('name'=>'wizard_add')),'list'=>array('type'=>'script','title'=>'LLL:EXT:lang/locallang_tca.xlf:file_mountpoints_list_title','icon'=>'list.gif','params'=>array('table'=>'sys_filemounts','pid'=>'0'),'module'=>array('name'=>'wizard_list'))))),

This example demonstrates the use of MM relations. In particular
they are used to relate system categories to a variety of other
records. As such it is necessary to keep track in the MM table of
the nature of each such record. This is achieved by using the
"fieldname" field, referenced in the MM_match_fields
configuration.

The "tablenames" field is also used in the case where multiple
category relation fields are added to the same record type
(as happens to the "pages" table when the "examples" extension
is installed).

'type'=>'select','foreign_table'=>'sys_category','foreign_table_where'=>' AND sys_category.sys_language_uid IN (-1, 0) ORDER BY sys_category.sorting ASC','MM'=>'sys_category_record_mm','MM_opposite_field'=>'items','MM_match_fields'=>array('tablenames'=>'pages','fieldname'=>'categories',),'size'=>10,'autoSizeMax'=>50,'maxitems'=>9999,'renderType'=>'selectTree','treeConfig'=>array('parentField'=>'parent','appearance'=>array('expandAll'=>TRUE,'showHeader'=>TRUE,),),

The selector looks like this:

The categories selector as added by default to pages

The above configuration also defines the MM relation as being
bidirectional, via the MM_opposite_field
property. This means that we can look at a given category and see
which items it is related to. Note that it is perfectly possible to
create relations from that side too.