Attention

TYPO3 v8 has reached its end-of-life March 31st, 2020 and is not maintained by the community anymore. Looking for a stable version? Use the version switch on the top left.

There is no further ELTS support. It is recommended that you upgrade your project and use a supported version of TYPO3.

type = 'select'

Introduction

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.

There are various shapes of the select type, the images below give an overview. The basic idea is that all possible child elements are always listed. This is in contrast to the group type which lists only selected elements and helps with selecting others via element browser and other tools.

The select type is pretty powerful, there are a lot of options to steer both rendering and database handling.

Note

For this type, a renderType is mandatory!

Examples

Simple select drop down with static and database values (select_single_3)

Select foreign rows which have icons configured (select_single_12)

Select a single value from a list of elements (select_single_10)

Select multiple values from a box (select_singlebox_1)

Select values from a checkbox list (select_checkbox_3)

Side-by-side view with filter (select_multiplesidebyside_5)

A happy little tree! (select_tree_1)

'select_single_3' => [
    'label' => 'select_single_3 static values, dividers, foreign_table_where',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingle',
        'items' => [
            ['Static values', '--div--'],
            ['static -2', -2],
            ['static -1', -1],
            ['DB values', '--div--'],
        ],
        'foreign_table' => 'tx_styleguide_staticdata',
        'foreign_table_where' => 'AND tx_styleguide_staticdata.value_1 LIKE \'%foo%\' ORDER BY uid',
        // @todo: docu of rootLevel says, foreign_table_where is *ignored*, which is NOT true.
        'rootLevel' => 1,
        'foreign_table_prefix' => 'A prefix: ',
    ],
],

'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_single_10' => [
    'label' => 'select_single_10 size=6, three options',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingle',
        'items' => [
            ['foo 1', 1],
            ['foo 2', 2],
            ['a divider', '--div--'],
            ['foo 3', 3],
        ],
        'size' => 6,
    ],
],

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

'select_checkbox_3' => [
    'label' => 'select_checkbox_3 icons, description',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectCheckBox',
        'items' => [
            ['foo 1', 1, '', 'optional description'],
            ['foo 2', 2, 'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg', 'description'],
            ['foo 3', 3, 'EXT:styleguide/Resources/Public/Icons/tx_styleguide.svg'],
            ['foo 4', 4],
        ],
    ],
],

'select_multiplesidebyside_5' => [
    'label' => 'select_multiplesidebyside_5 multiSelectFilterItems, enableMultiSelectFilterTextfield=true',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectMultipleSideBySide',
        'items' => [
            ['foo 1', 1],
            ['foo 2', 2],
            ['foo 3', 3],
            ['bar', 4],
        ],
        'enableMultiSelectFilterTextfield' => true,
        'multiSelectFilterItems' => [
            ['', ''],
            ['foo', 'foo'],
            ['bar', 'bar'],
        ],
    ],
],

'select_tree_1' => [
    'label' => 'select_tree_1 pages, showHeader=true, expandAll=true, size=20, order by sorting, static items',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectTree',
        'foreign_table' => 'pages',
        'foreign_table_where' => 'ORDER BY pages.sorting',
        'size' => 20,
        'items' => [
            [ 'static from tca 4711', 4711 ],
            [ 'static from tca 4712', 4712 ],
        ],
        'treeConfig' => [
            'parentField' => 'pid',
            'appearance' => [
                'expandAll' => true,
                'showHeader' => true,
            ],
        ],
    ],
],

Properties renderType default

allowNonIdValues

Datatype

boolean

Scope

Proc.

Description

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.

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! Will not work if you also use "MM" relations!

authMode

Datatype

string (keyword)

Scope

Display / Proc.

Description

Authorization mode for the selector box. Keywords are:

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). Items without any of these keywords can be selected as usual without any access restrictions applied.

Note

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.

authMode_enforce

Datatype

string (keyword)

Scope

Display / Proc.

Description

Various additional enforcing options for authMode, keywords:

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!

behaviour

Datatype

array

Scope

Proc.

Description

The behaviour array contains various sub properties to specify processing options like localization overlay behaviour and children behaviour for relation types. Available properties vary by type and renderType combination.

allowLanguageSynchronization

| Scope: Proc. | Type: boolean | Default: false |

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.

default

Datatype

string

Scope

Display / Proc.

Description

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

disableNoMatchingValueElement

Datatype

boolean

Scope

Display

Description

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.

dontRemapTablesOnCopy

Datatype

string (list of tables)

Scope

Proc.

Description

Only with internal_type='db'

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

Datatype

string (list of)

Scope

Display / Proc.

Description

List of keys that exclude any other keys in a select box where multiple items could be selected.

"Show at any login" of "fe_groups" (tables "pages" and "tt_content") is an example where such a configuration is used.

fieldInformation

Datatype

array

Scope

Display

Description

Show information between an element label and the main element input area. Configuration works identical to the "fieldWizard" property, no default configuration in the core exists (yet). In contrast to "fieldWizard", HTML returned by fieldInformation is limited, see FormEngine docs for more details.

fieldWizard

Datatype

array

Scope

Display

Description

Specifies wizards rendered below the main input area of an element. Single type / renderType elements can register default wizards which are merged with this property.

As example, type='check' comes with this default wizards configuration:

protected $defaultFieldWizard = [
    'localizationStateSelector' => [
        'renderType' => 'localizationStateSelector',
    ],
    'otherLanguageContent' => [
        'renderType' => 'otherLanguageContent',
        'after' => [
            'localizationStateSelector'
        ],
    ],
    'defaultLanguageDifferences' => [
        'renderType' => 'defaultLanguageDifferences',
        'after' => [
            'otherLanguageContent',
        ],
    ],
];

This is be merged with the configuration from TCA, if there is any. Below example disables the default localizationStateSelector wizard.

'aField' => [
    'config' => [
        'fieldWizard' => [
            'localizationStateSelector' => [
                'disabled' => true,
            ],
        ],
    ],
],

It is possible to add own wizards by adding them to the TCA of the according field and pointing to a registered renderType, to resort wizards by overriding the before and after keys, to hand over additional options in the optional options array to specific wizards, and to disable single wizards using the disabled key. Developers should have a look at the FormEngine docs for details.

defaultLanguageDifferences

Datatype

array

Scope

fieldWizard

Description

Show a "diff-view" if the content of the default language record has been changed after the translation overlay has been created. The ['ctrl'] section property transOrigDiffSourceField has to be specified to enable this wizard in a translated record.

This wizard is important for editors who maintain translated records: They can see what has been changed in their localization parent between the last save operation of the overlay.

A field has been changed in default language record

localizationStateSelector

Datatype

array

Scope

fieldWizard

Description

The localization state selector wizard displays two or three radio buttons in localized records saying: "This field has an own value distinct from my default language or source record", "This field has the same value as the default language record" or "This field has the same value as my source record". This wizard is especially useful for the tt_content table. It will only render, if:

• The record is a localized record (not default language)

• The record is in "translated" (connected), but not in "copy" (free) mode

• The table is localization aware using the ['ctrl'] properties languageField, transOrigPointerField. If the optional property translationSource is also set, and if the record is a translation from another localized record, the third radio appears.

• The property ['config']['behaviour']['allowLanguageSynchronization'] is set to true

Example localization state selector on an type=input field

otherLanguageContent

Datatype

array

Scope

fieldWizard

Description

Show values from the default language record and other localized records if the edited row is a localized record. Often used in tt_content fields. By default, only the value of the default language record is shown, values from further translations can be shown by setting the userTsConfig property additionalPreviewLanguages.

The wizard shows content only for "simple" fields. For instance, it does not work for database relation fields, and if the field is set to readOnly. Additionally, the table has to be language aware by setting up the according fields in ['ctr'] section.

Header field showing values from two other languages

selectIcons

Datatype

array

Scope

fieldWizard

Description

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

fileFolder

Datatype

string

Scope

Display / Proc.

Description

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

Specify the folder relative to the PATH_site, possibly using the prefix "EXT:" to point to an extension folder.

Files from the folder is selected recursively to the level specified by fileFolder_recursions and only files of the extension defined by fileFolder_extList is selected.

Only the file reference relative to the "fileFolder" is stored.

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

Example:

'config' => [
    'type' => 'select',
    'items' => [
        [ '', 0 ],
    ],
    'fileFolder' => 'EXT:cms/tslib/media/flags/',
    'fileFolder_extList' => 'png,jpg,jpeg,gif',
    'fileFolder_recursions' => 0,
    'size' => 1,
    'minitems' => 0,
    'maxitems' => 1,
],

fileFolder_extList

Datatype

string

Scope

Display / Proc.

Description

List of extensions to select. If blank, all files are selected. Specify list in lowercase. Only useful in combination with property fileFolder.

fileFolder_recursions

Datatype

integer

Scope

Display / Proc.

Description

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

foreign_table

Datatype

string (table name)

Scope

Proc. / Display

Description

The item-array will be filled with records from the table defined here. The table must be configured in $GLOBALS['TCA'].

foreign_table_prefix

Datatype

string or LLL reference

Scope

Display

Description

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

foreign_table_where

Datatype

string (SQL WHERE)

Scope

Proc. / Display

Description

The items from foreign_table are selected with this WHERE-clause.

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 = 0 ORDER BY [foreign_table].sorting

Markers:

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.

• ###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.

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.

items

Datatype

array

Scope

Display / Proc.

Description

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. 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 with renderType='selectCheckBox'.

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

Example:

A configuration could look like this:

'type' => 'select',
'items' => [
   [ 'English', '' ],
   [ 'Danish', 'dk' ],
   [ 'German', 'de' ],
]

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

'type' => 'select',
'items' => [
    [ 'LLL:EXT:cms/locallang_ttc.php:k1', 0, 'EXT:myext/Resources/Public/selicons/k1.gif' ],
    [ 'LLL:EXT:cms/locallang_ttc.php:k2', 1, 'tx-myext-selicons-k2' ],
    [ 'LLL:EXT:cms/locallang_ttc.php:k3', 2, 'tx-myext-selicons-k3' ],
]

itemsProcFunc

Datatype

string (class->method reference)

Scope

Display / Proc.

Description

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

[classname]->[methodname]

The function/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.

See extension styleguide for a couple of examples on different config type's.

localizeReferencesAtParentLocalization

Datatype

boolean

Scope

Proc.

Description

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

minitems

Datatype

integer > 0

Scope

Display

Description

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

MM

Datatype

string (table name)

Scope

Proc.

Description

Means that the relation to the records of foreign_table is done with a M-M relation with a third "join" table.

That table has three columns as a minimum:

uid_local, uid_foreign (Required)

Storing uids of both sides. If done right, this is reflected in the table name - tx_foo_local_foreign_mm

sorting (Required)

Is a required field used for ordering the items.

sorting_foreign

Is required if the relation is bidirectional (see description and example below table)

tablenames

Is used if multiple tables are allowed in the relation.

uid (auto-incremented and PRIMARY KEY)

May be used if you need the "multiple" feature (which allows the same record to be references multiple times in the box. See MM_hasUidField for type='select' and MM_hasUidField for type='group' fields.

further fields

May exist, in particular if MM_match_fields / MM_match_fields is involved in the set up.

Example SQL #1

Most simple MM table

CREATE TABLE tx_testmmrelations_one_rel_mm (
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign)
);

Example SQL #2

Advanced with uid field, "ident" used with MM_match_fields and "sorting_foreign" for bidirectional MM relations:

CREATE TABLE tx_testmmrelations_two_rel_mm (
    uid int(11) NOT NULL auto_increment,
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    tablenames varchar(30) DEFAULT '' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,
    sorting_foreign int(11) DEFAULT '0' NOT NULL,
    ident varchar(30) DEFAULT '' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign),
    PRIMARY KEY (uid)
);

Value of field

The field name of the config is not used for data-storage anymore but rather it's set to the number of records in the relation on each update, so the field should be an integer.

MM relations and flexforms

MM relations has been tested to work with flexforms if not in a repeated element in a section.

Note

Using MM relations you can ONLY store real relations for foreign tables in the list - no additional string values or non-record values.

MM_hasUidField

Datatype

boolean

Scope

Proc.

Description

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.

MM_insert_fields

Datatype

array

Scope

Proc.

Description

Array of field=>value pairs to insert when writing new MM relations.

MM_table_where

Datatype

string (SQL WHERE)

Scope

Proc.

Description

Additional where clause used when reading MM relations.

MM_match_fields

Datatype

array

Scope

Display / Proc.

Description

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

MM_opposite_field

Datatype

string (field name)

Scope

Proc.

Description

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

MM_oppositeUsage

Datatype

array

Scope

Proc.

Description

In a MM bidirectional relation using select match fields / group 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 whichfields 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:

$GLOBALS['TCA']['sys_category']['columns']['items']['config']['MM_oppositeUsage'] = [
    'pages' => ['tx_examples_cats', 'categories'],
    'sys_file_metadata' => ['categories'],
    'tt_content' => ['categories'],
];

multiple

Datatype

boolean

Scope

Display / Proc.

Description

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. Also, with MM relations in general you must use a UID field in the join table, see description for "MM".

readOnly

Datatype

boolean

Scope

Display

Description

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.

Warning

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

rootLevel

Datatype

boolean

Scope

Display

Description

If set, the foreign_table_where will be ignored and a "pid=0" will be added to the query to select only records from root level of the page tree.

size

Datatype

integer

Scope

Display

Description

Height of the box in FormEngine.

With type='select' and renderType='selectSingle', the default is 1, but if set to a number greater than 1, the select drop down will be displayed as box where only one item can be selected.

With type='select' and renderType='selectSingleBox', this value should not be set to a number smaller than 2.

With type='group', the "box" collapses to a single element input and should then be combined with a maxitems=1, the default is 5.

special

Datatype

string (keyword)

Scope

Display / Proc.

Description

This configures the selector box to fetch content from some predefined internal source. These options are used for backend user management and pretty worthless for most other purposes. Keywords:

tables

The list of TCA tables is added to the selector (excluding "adminOnly" tables).

pagetypes

All "doktype"-values for the "pages" table are added.

exclude

The list of "excludeFields" as found in $GLOBALS['TCA'] is added.

modListGroup

Module-lists added for groups.

modListUser

Module-lists added for users.

explicitValues

List values that require explicit permissions to be allowed or denied, see authMode.

languages

List system languages ("sys_language" records from page tree root + Default language)

custom

Custom values set by backend modules (see TYPO3_CONF_VARS[BE][customPermOptions])

Properties renderType = 'selectSingleBox'

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

allowNonIdValues

Datatype

boolean

Scope

Proc.

Description

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.

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! Will not work if you also use "MM" relations!

authMode

Datatype

string (keyword)

Scope

Display / Proc.

Description

Authorization mode for the selector box. Keywords are:

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). Items without any of these keywords can be selected as usual without any access restrictions applied.

Note

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.

authMode_enforce

Datatype

string (keyword)

Scope

Display / Proc.

Description

Various additional enforcing options for authMode, keywords:

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!

autoSizeMax

Datatype

integer

Scope

Display

Description

If set, then the height of element listing selector box 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.

behaviour

Datatype

array

Scope

Proc.

Description

The behaviour array contains various sub properties to specify processing options like localization overlay behaviour and children behaviour for relation types. Available properties vary by type and renderType combination.

allowLanguageSynchronization

| Scope: Proc. | Type: boolean | Default: false |

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.

default

Datatype

string

Scope

Display / Proc.

Description

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

disableNoMatchingValueElement

Datatype

boolean

Scope

Display

Description

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.

dontRemapTablesOnCopy

Datatype

string (list of tables)

Scope

Proc.

Description

Only with internal_type='db'

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

Datatype

string (list of)

Scope

Display / Proc.

Description

List of keys that exclude any other keys in a select box where multiple items could be selected.

"Show at any login" of "fe_groups" (tables "pages" and "tt_content") is an example where such a configuration is used.

fieldControl

Datatype

array

Scope

Display

Description

Show action buttons next to the element. This is used in various type's to add control buttons right next to the main element. They can open popus, switch the entire view and other things. All must provide a "button" icon to click on, see FormEngine docs for more details. See type=group for examples.

resetSelection

Datatype

array

Scope

fieldControl

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

Datatype

array

Scope

Display

Description

Show information between an element label and the main element input area. Configuration works identical to the "fieldWizard" property, no default configuration in the core exists (yet). In contrast to "fieldWizard", HTML returned by fieldInformation is limited, see FormEngine docs for more details.

fieldWizard

Datatype

array

Scope

Display

Description

Specifies wizards rendered below the main input area of an element. Single type / renderType elements can register default wizards which are merged with this property.

As example, type='check' comes with this default wizards configuration:

protected $defaultFieldWizard = [
    'localizationStateSelector' => [
        'renderType' => 'localizationStateSelector',
    ],
    'otherLanguageContent' => [
        'renderType' => 'otherLanguageContent',
        'after' => [
            'localizationStateSelector'
        ],
    ],
    'defaultLanguageDifferences' => [
        'renderType' => 'defaultLanguageDifferences',
        'after' => [
            'otherLanguageContent',
        ],
    ],
];

This is be merged with the configuration from TCA, if there is any. Below example disables the default localizationStateSelector wizard.

'aField' => [
    'config' => [
        'fieldWizard' => [
            'localizationStateSelector' => [
                'disabled' => true,
            ],
        ],
    ],
],

It is possible to add own wizards by adding them to the TCA of the according field and pointing to a registered renderType, to resort wizards by overriding the before and after keys, to hand over additional options in the optional options array to specific wizards, and to disable single wizards using the disabled key. Developers should have a look at the FormEngine docs for details.

defaultLanguageDifferences

Datatype

array

Scope

fieldWizard

Description

Show a "diff-view" if the content of the default language record has been changed after the translation overlay has been created. The ['ctrl'] section property transOrigDiffSourceField has to be specified to enable this wizard in a translated record.

This wizard is important for editors who maintain translated records: They can see what has been changed in their localization parent between the last save operation of the overlay.

A field has been changed in default language record

localizationStateSelector

Datatype

array

Scope

fieldWizard

Description

The localization state selector wizard displays two or three radio buttons in localized records saying: "This field has an own value distinct from my default language or source record", "This field has the same value as the default language record" or "This field has the same value as my source record". This wizard is especially useful for the tt_content table. It will only render, if:

• The record is a localized record (not default language)

• The record is in "translated" (connected), but not in "copy" (free) mode

• The table is localization aware using the ['ctrl'] properties languageField, transOrigPointerField. If the optional property translationSource is also set, and if the record is a translation from another localized record, the third radio appears.

• The property ['config']['behaviour']['allowLanguageSynchronization'] is set to true

Example localization state selector on an type=input field

otherLanguageContent

Datatype

array

Scope

fieldWizard

Description

Show values from the default language record and other localized records if the edited row is a localized record. Often used in tt_content fields. By default, only the value of the default language record is shown, values from further translations can be shown by setting the userTsConfig property additionalPreviewLanguages.

The wizard shows content only for "simple" fields. For instance, it does not work for database relation fields, and if the field is set to readOnly. Additionally, the table has to be language aware by setting up the according fields in ['ctr'] section.

Header field showing values from two other languages

fileFolder

Datatype

string

Scope

Display / Proc.

Description

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

Specify the folder relative to the PATH_site, possibly using the prefix "EXT:" to point to an extension folder.

Files from the folder is selected recursively to the level specified by fileFolder_recursions and only files of the extension defined by fileFolder_extList is selected.

Only the file reference relative to the "fileFolder" is stored.

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

Example:

'config' => [
    'type' => 'select',
    'items' => [
        [ '', 0 ],
    ],
    'fileFolder' => 'EXT:cms/tslib/media/flags/',
    'fileFolder_extList' => 'png,jpg,jpeg,gif',
    'fileFolder_recursions' => 0,
    'size' => 1,
    'minitems' => 0,
    'maxitems' => 1,
],

fileFolder_extList

Datatype

string

Scope

Display / Proc.

Description

List of extensions to select. If blank, all files are selected. Specify list in lowercase. Only useful in combination with property fileFolder.

fileFolder_recursions

Datatype

integer

Scope

Display / Proc.

Description

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

foreign_table

Datatype

string (table name)

Scope

Proc. / Display

Description

The item-array will be filled with records from the table defined here. The table must be configured in $GLOBALS['TCA'].

foreign_table_prefix

Datatype

string or LLL reference

Scope

Display

Description

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

foreign_table_where

Datatype

string (SQL WHERE)

Scope

Proc. / Display

Description

The items from foreign_table are selected with this WHERE-clause.

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 = 0 ORDER BY [foreign_table].sorting

Markers:

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.

• ###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.

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.

items

Datatype

array

Scope

Display / Proc.

Description

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. 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 with renderType='selectCheckBox'.

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

Example:

A configuration could look like this:

'type' => 'select',
'items' => [
   [ 'English', '' ],
   [ 'Danish', 'dk' ],
   [ 'German', 'de' ],
]

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

'type' => 'select',
'items' => [
    [ 'LLL:EXT:cms/locallang_ttc.php:k1', 0, 'EXT:myext/Resources/Public/selicons/k1.gif' ],
    [ 'LLL:EXT:cms/locallang_ttc.php:k2', 1, 'tx-myext-selicons-k2' ],
    [ 'LLL:EXT:cms/locallang_ttc.php:k3', 2, 'tx-myext-selicons-k3' ],
]

itemsProcFunc

Datatype

string (class->method reference)

Scope

Display / Proc.

Description

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

[classname]->[methodname]

The function/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.

See extension styleguide for a couple of examples on different config type's.

localizeReferencesAtParentLocalization

Datatype

boolean

Scope

Proc.

Description

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

maxitems

Datatype

integer > 0

Scope

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.

Note

Property maxitems is ignored with type='select' and renderType='selectSingle'.

Description

Display / Proc.

minitems

Datatype

integer > 0

Scope

Display

Description

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

MM

Datatype

string (table name)

Scope

Proc.

Description

Means that the relation to the records of foreign_table is done with a M-M relation with a third "join" table.

That table has three columns as a minimum:

uid_local, uid_foreign (Required)

Storing uids of both sides. If done right, this is reflected in the table name - tx_foo_local_foreign_mm

sorting (Required)

Is a required field used for ordering the items.

sorting_foreign

Is required if the relation is bidirectional (see description and example below table)

tablenames

Is used if multiple tables are allowed in the relation.

uid (auto-incremented and PRIMARY KEY)

May be used if you need the "multiple" feature (which allows the same record to be references multiple times in the box. See MM_hasUidField for type='select' and MM_hasUidField for type='group' fields.

further fields

May exist, in particular if MM_match_fields / MM_match_fields is involved in the set up.

Example SQL #1

Most simple MM table

CREATE TABLE tx_testmmrelations_one_rel_mm (
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign)
);

Example SQL #2

Advanced with uid field, "ident" used with MM_match_fields and "sorting_foreign" for bidirectional MM relations:

CREATE TABLE tx_testmmrelations_two_rel_mm (
    uid int(11) NOT NULL auto_increment,
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    tablenames varchar(30) DEFAULT '' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,
    sorting_foreign int(11) DEFAULT '0' NOT NULL,
    ident varchar(30) DEFAULT '' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign),
    PRIMARY KEY (uid)
);

Value of field

The field name of the config is not used for data-storage anymore but rather it's set to the number of records in the relation on each update, so the field should be an integer.

MM relations and flexforms

MM relations has been tested to work with flexforms if not in a repeated element in a section.

Note

Using MM relations you can ONLY store real relations for foreign tables in the list - no additional string values or non-record values.

MM_hasUidField

Datatype

boolean

Scope

Proc.

Description

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.

MM_insert_fields

Datatype

array

Scope

Proc.

Description

Array of field=>value pairs to insert when writing new MM relations.

MM_table_where

Datatype

string (SQL WHERE)

Scope

Proc.

Description

Additional where clause used when reading MM relations.

MM_match_fields

Datatype

array

Scope

Display / Proc.

Description

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

MM_opposite_field

Datatype

string (field name)

Scope

Proc.

Description

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

MM_oppositeUsage

Datatype

array

Scope

Proc.

Description

In a MM bidirectional relation using select match fields / group 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 whichfields 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:

$GLOBALS['TCA']['sys_category']['columns']['items']['config']['MM_oppositeUsage'] = [
    'pages' => ['tx_examples_cats', 'categories'],
    'sys_file_metadata' => ['categories'],
    'tt_content' => ['categories'],
];

multiple

Datatype

boolean

Scope

Display / Proc.

Description

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. Also, with MM relations in general you must use a UID field in the join table, see description for "MM".

readOnly

Datatype

boolean

Scope

Display

Description

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.

Warning

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

rootLevel

Datatype

boolean

Scope

Display

Description

If set, the foreign_table_where will be ignored and a "pid=0" will be added to the query to select only records from root level of the page tree.

size

Datatype

integer

Scope

Display

Description

Height of the box in FormEngine.

With type='select' and renderType='selectSingle', the default is 1, but if set to a number greater than 1, the select drop down will be displayed as box where only one item can be selected.

With type='select' and renderType='selectSingleBox', this value should not be set to a number smaller than 2.

With type='group', the "box" collapses to a single element input and should then be combined with a maxitems=1, the default is 5.

special

Datatype

string (keyword)

Scope

Display / Proc.

Description

This configures the selector box to fetch content from some predefined internal source. These options are used for backend user management and pretty worthless for most other purposes. Keywords:

tables

The list of TCA tables is added to the selector (excluding "adminOnly" tables).

pagetypes

All "doktype"-values for the "pages" table are added.

exclude

The list of "excludeFields" as found in $GLOBALS['TCA'] is added.

modListGroup

Module-lists added for groups.

modListUser

Module-lists added for users.

explicitValues

List values that require explicit permissions to be allowed or denied, see authMode.

languages

List system languages ("sys_language" records from page tree root + Default language)

custom

Custom values set by backend modules (see TYPO3_CONF_VARS[BE][customPermOptions])

Properties renderType = 'selectCheckBox'

Render the list of values as single check box rows in a table. Multiple items can be selected.

allowNonIdValues

Datatype

boolean

Scope

Proc.

Description

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.

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! Will not work if you also use "MM" relations!

authMode

Datatype

string (keyword)

Scope

Display / Proc.

Description

Authorization mode for the selector box. Keywords are:

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). Items without any of these keywords can be selected as usual without any access restrictions applied.

Note

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.

authMode_enforce

Datatype

string (keyword)

Scope

Display / Proc.

Description

Various additional enforcing options for authMode, keywords:

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!

behaviour

Datatype

array

Scope

Proc.

Description

The behaviour array contains various sub properties to specify processing options like localization overlay behaviour and children behaviour for relation types. Available properties vary by type and renderType combination.

allowLanguageSynchronization

| Scope: Proc. | Type: boolean | Default: false |

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.

default

Datatype

string

Scope

Display / Proc.

Description

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

disableNoMatchingValueElement

Datatype

boolean

Scope

Display

Description

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.

dontRemapTablesOnCopy

Datatype

string (list of tables)

Scope

Proc.

Description

Only with internal_type='db'

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

Datatype

string (list of)

Scope

Display / Proc.

Description

List of keys that exclude any other keys in a select box where multiple items could be selected.

"Show at any login" of "fe_groups" (tables "pages" and "tt_content") is an example where such a configuration is used.

fieldInformation

Datatype

array

Scope

Display

Description

Show information between an element label and the main element input area. Configuration works identical to the "fieldWizard" property, no default configuration in the core exists (yet). In contrast to "fieldWizard", HTML returned by fieldInformation is limited, see FormEngine docs for more details.

fieldWizard

Datatype

array

Scope

Display

Description

Specifies wizards rendered below the main input area of an element. Single type / renderType elements can register default wizards which are merged with this property.

As example, type='check' comes with this default wizards configuration:

protected $defaultFieldWizard = [
    'localizationStateSelector' => [
        'renderType' => 'localizationStateSelector',
    ],
    'otherLanguageContent' => [
        'renderType' => 'otherLanguageContent',
        'after' => [
            'localizationStateSelector'
        ],
    ],
    'defaultLanguageDifferences' => [
        'renderType' => 'defaultLanguageDifferences',
        'after' => [
            'otherLanguageContent',
        ],
    ],
];

This is be merged with the configuration from TCA, if there is any. Below example disables the default localizationStateSelector wizard.

'aField' => [
    'config' => [
        'fieldWizard' => [
            'localizationStateSelector' => [
                'disabled' => true,
            ],
        ],
    ],
],

It is possible to add own wizards by adding them to the TCA of the according field and pointing to a registered renderType, to resort wizards by overriding the before and after keys, to hand over additional options in the optional options array to specific wizards, and to disable single wizards using the disabled key. Developers should have a look at the FormEngine docs for details.

defaultLanguageDifferences

Datatype

array

Scope

fieldWizard

Description

Show a "diff-view" if the content of the default language record has been changed after the translation overlay has been created. The ['ctrl'] section property transOrigDiffSourceField has to be specified to enable this wizard in a translated record.

This wizard is important for editors who maintain translated records: They can see what has been changed in their localization parent between the last save operation of the overlay.

A field has been changed in default language record

localizationStateSelector

Datatype

array

Scope

fieldWizard

Description

The localization state selector wizard displays two or three radio buttons in localized records saying: "This field has an own value distinct from my default language or source record", "This field has the same value as the default language record" or "This field has the same value as my source record". This wizard is especially useful for the tt_content table. It will only render, if:

• The record is a localized record (not default language)

• The record is in "translated" (connected), but not in "copy" (free) mode

• The table is localization aware using the ['ctrl'] properties languageField, transOrigPointerField. If the optional property translationSource is also set, and if the record is a translation from another localized record, the third radio appears.

• The property ['config']['behaviour']['allowLanguageSynchronization'] is set to true

Example localization state selector on an type=input field

otherLanguageContent

Datatype

array

Scope

fieldWizard

Description

Show values from the default language record and other localized records if the edited row is a localized record. Often used in tt_content fields. By default, only the value of the default language record is shown, values from further translations can be shown by setting the userTsConfig property additionalPreviewLanguages.

The wizard shows content only for "simple" fields. For instance, it does not work for database relation fields, and if the field is set to readOnly. Additionally, the table has to be language aware by setting up the according fields in ['ctr'] section.

Header field showing values from two other languages

fileFolder

Datatype

string

Scope

Display / Proc.

Description

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

Specify the folder relative to the PATH_site, possibly using the prefix "EXT:" to point to an extension folder.

Files from the folder is selected recursively to the level specified by fileFolder_recursions and only files of the extension defined by fileFolder_extList is selected.

Only the file reference relative to the "fileFolder" is stored.

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

Example:

'config' => [
    'type' => 'select',
    'items' => [
        [ '', 0 ],
    ],
    'fileFolder' => 'EXT:cms/tslib/media/flags/',
    'fileFolder_extList' => 'png,jpg,jpeg,gif',
    'fileFolder_recursions' => 0,
    'size' => 1,
    'minitems' => 0,
    'maxitems' => 1,
],

fileFolder_extList

Datatype

string

Scope

Display / Proc.

Description

List of extensions to select. If blank, all files are selected. Specify list in lowercase. Only useful in combination with property fileFolder.

fileFolder_recursions

Datatype

integer

Scope

Display / Proc.

Description

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

foreign_table

Datatype

string (table name)

Scope

Proc. / Display

Description

The item-array will be filled with records from the table defined here. The table must be configured in $GLOBALS['TCA'].

foreign_table_prefix

Datatype

string or LLL reference

Scope

Display

Description

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

foreign_table_where

Datatype

string (SQL WHERE)

Scope

Proc. / Display

Description

The items from foreign_table are selected with this WHERE-clause.

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 = 0 ORDER BY [foreign_table].sorting

Markers:

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.

• ###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.

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.

items

Datatype

array

Scope

Display / Proc.

Description

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. 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 with renderType='selectCheckBox'.

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

Example:

A configuration could look like this:

'type' => 'select',
'items' => [
   [ 'English', '' ],
   [ 'Danish', 'dk' ],
   [ 'German', 'de' ],
]

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

'type' => 'select',
'items' => [
    [ 'LLL:EXT:cms/locallang_ttc.php:k1', 0, 'EXT:myext/Resources/Public/selicons/k1.gif' ],
    [ 'LLL:EXT:cms/locallang_ttc.php:k2', 1, 'tx-myext-selicons-k2' ],
    [ 'LLL:EXT:cms/locallang_ttc.php:k3', 2, 'tx-myext-selicons-k3' ],
]

itemsProcFunc

Datatype

string (class->method reference)

Scope

Display / Proc.

Description

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

[classname]->[methodname]

The function/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.

See extension styleguide for a couple of examples on different config type's.

localizeReferencesAtParentLocalization

Datatype

boolean

Scope

Proc.

Description

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

maxitems

Datatype

integer > 0

Scope

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.

Note

Property maxitems is ignored with type='select' and renderType='selectSingle'.

Description

Display / Proc.

minitems

Datatype

integer > 0

Scope

Display

Description

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

MM

Datatype

string (table name)

Scope

Proc.

Description

Means that the relation to the records of foreign_table is done with a M-M relation with a third "join" table.

That table has three columns as a minimum:

uid_local, uid_foreign (Required)

Storing uids of both sides. If done right, this is reflected in the table name - tx_foo_local_foreign_mm

sorting (Required)

Is a required field used for ordering the items.

sorting_foreign

Is required if the relation is bidirectional (see description and example below table)

tablenames

Is used if multiple tables are allowed in the relation.

uid (auto-incremented and PRIMARY KEY)

May be used if you need the "multiple" feature (which allows the same record to be references multiple times in the box. See MM_hasUidField for type='select' and MM_hasUidField for type='group' fields.

further fields

May exist, in particular if MM_match_fields / MM_match_fields is involved in the set up.

Example SQL #1

Most simple MM table

CREATE TABLE tx_testmmrelations_one_rel_mm (
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign)
);

Example SQL #2

Advanced with uid field, "ident" used with MM_match_fields and "sorting_foreign" for bidirectional MM relations:

CREATE TABLE tx_testmmrelations_two_rel_mm (
    uid int(11) NOT NULL auto_increment,
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    tablenames varchar(30) DEFAULT '' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,
    sorting_foreign int(11) DEFAULT '0' NOT NULL,
    ident varchar(30) DEFAULT '' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign),
    PRIMARY KEY (uid)
);

Value of field

The field name of the config is not used for data-storage anymore but rather it's set to the number of records in the relation on each update, so the field should be an integer.

MM relations and flexforms

MM relations has been tested to work with flexforms if not in a repeated element in a section.

Note

Using MM relations you can ONLY store real relations for foreign tables in the list - no additional string values or non-record values.

MM_hasUidField

Datatype

boolean

Scope

Proc.

Description

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.

MM_insert_fields

Datatype

array

Scope

Proc.

Description

Array of field=>value pairs to insert when writing new MM relations.

MM_table_where

Datatype

string (SQL WHERE)

Scope

Proc.

Description

Additional where clause used when reading MM relations.

MM_match_fields

Datatype

array

Scope

Display / Proc.

Description

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

MM_opposite_field

Datatype

string (field name)

Scope

Proc.

Description

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

MM_oppositeUsage

Datatype

array

Scope

Proc.

Description

In a MM bidirectional relation using select match fields / group 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 whichfields 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:

$GLOBALS['TCA']['sys_category']['columns']['items']['config']['MM_oppositeUsage'] = [
    'pages' => ['tx_examples_cats', 'categories'],
    'sys_file_metadata' => ['categories'],
    'tt_content' => ['categories'],
];

multiple

Datatype

boolean

Scope

Display / Proc.

Description

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. Also, with MM relations in general you must use a UID field in the join table, see description for "MM".

readOnly

Datatype

boolean

Scope

Display

Description

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.

Warning

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

rootLevel

Datatype

boolean

Scope

Display

Description

If set, the foreign_table_where will be ignored and a "pid=0" will be added to the query to select only records from root level of the page tree.

size

Datatype

integer

Scope

Display

Description

Height of the box in FormEngine.

With type='select' and renderType='selectSingle', the default is 1, but if set to a number greater than 1, the select drop down will be displayed as box where only one item can be selected.

With type='select' and renderType='selectSingleBox', this value should not be set to a number smaller than 2.

With type='group', the "box" collapses to a single element input and should then be combined with a maxitems=1, the default is 5.

special

Datatype

string (keyword)

Scope

Display / Proc.

Description

This configures the selector box to fetch content from some predefined internal source. These options are used for backend user management and pretty worthless for most other purposes. Keywords:

tables

The list of TCA tables is added to the selector (excluding "adminOnly" tables).

pagetypes

All "doktype"-values for the "pages" table are added.

exclude

The list of "excludeFields" as found in $GLOBALS['TCA'] is added.

modListGroup

Module-lists added for groups.

modListUser

Module-lists added for users.

explicitValues

List values that require explicit permissions to be allowed or denied, see authMode.

languages

List system languages ("sys_language" records from page tree root + Default language)

custom

Custom values set by backend modules (see TYPO3_CONF_VARS[BE][customPermOptions])

Properties renderType = 'selectMultipleSideBySide'

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

allowNonIdValues

Datatype

boolean

Scope

Proc.

Description

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.

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! Will not work if you also use "MM" relations!

authMode

Datatype

string (keyword)

Scope

Display / Proc.

Description

Authorization mode for the selector box. Keywords are:

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). Items without any of these keywords can be selected as usual without any access restrictions applied.

Note

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.

authMode_enforce

Datatype

string (keyword)

Scope

Display / Proc.

Description

Various additional enforcing options for authMode, keywords:

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!

autoSizeMax

Datatype

integer

Scope

Display

Description

If set, then the height of element listing selector box 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.

behaviour

Datatype

array

Scope

Proc.

Description

The behaviour array contains various sub properties to specify processing options like localization overlay behaviour and children behaviour for relation types. Available properties vary by type and renderType combination.

allowLanguageSynchronization

| Scope: Proc. | Type: boolean | Default: false |

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.

default

Datatype

string

Scope

Display / Proc.

Description

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

disableNoMatchingValueElement

Datatype

boolean

Scope

Display

Description

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.

dontRemapTablesOnCopy

Datatype

string (list of tables)

Scope

Proc.

Description

Only with internal_type='db'

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.

enableMultiSelectFilterTextfield

Datatype

boolean

Scope

Display

Description

If set, a textual field is shown above the available items in which one can type words to filter the list of available items, see multiSelectFilterItems.

exclusiveKeys

Datatype

string (list of)

Scope

Display / Proc.

Description

List of keys that exclude any other keys in a select box where multiple items could be selected.

"Show at any login" of "fe_groups" (tables "pages" and "tt_content") is an example where such a configuration is used.

fieldControl

Datatype

array

Scope

Display

Description

Show action buttons next to the element. This is used in various type's to add control buttons right next to the main element. They can open popus, switch the entire view and other things. All must provide a "button" icon to click on, see FormEngine docs for more details. See type=group for examples.

addRecord

Datatype

array

Scope

fieldControl

Description

Control button to directly add a related record. Leaves the current view and opens a new form to add a new record. On 'Save and close', the record is directly selected as referenced element in the type='group' field. If muliple tables are allowed, the first table from the allowed list is selected, if not specific table option is given.

Note

The add record control is disabled by default, enable it if needed. It is shown below the edit popup control if not changed by below or after settings.

Options:

pid (string)

pid of the new record. Can be an hard pid setting, or one of these markers, see select foreign_table_where. Falls back to "current pid" if not set, forces pid=0 if records of this table are only allowed on root level.

• ###CURRENT_PID###

• ###THIS_UID###

• ###SITEROOT###

• ###PAGE_TSCONFIG_ID###

• ###PAGE_TSCONFIG_IDLIST###

• ###PAGE_TSCONFIG_STR###

table (string)

Add a record to this table, falls back to first table from allowed list if not set for type='group' fields and to foreign_table for type='select' fields.

title (string or LLL reference)

Allows to set a different 'title' attribute to the popup icon, defaults to LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.createNew

setValue (string, keyword)

Can be one of 'set', 'prepend' or 'append'. With 'set' the given selection is substituted with the new record, 'prepend' adds the new record on top of the list, 'append' adds it at the bottom. Default: 'append'.

Add a new record icon

Add a new record view

editPopup

Datatype

array

Scope

fieldControl

Description

The edit popup field control gives a shortcut to edit referenced elements directly a popup. When a record is selected and the edit button is clicked, that record opens in a new window for modification.

Note

The edit popup control is pre-configured, but disabled by default. Enable it if you need it, the button is by default shown below element browser and insert clipboard.

Options:

title (string or LLL reference)

Allows to set a different 'title' attribute to the popup icon, defaults to LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.edit

windowOpenParameters (string)

Allows to set a different size of the popup, defaults to height=800,width=600,status=0,menubar=0,scrollbars=1.

Edit a related record directly thanks to the Edit wizard

Example

'myField' => [
    'type' => 'group',
    // ...
    'config' => [
        'fieldControl' => [
            'editPopup' => [
                'disabled' => false,
                'options' => [
                    'title' => 'Edit a selected record!',
                ],
            ],
        ],
    ],
],

listModule

Datatype

array

Scope

fieldControl

Description

The list module control button opens the Web > List module for only one table and allows the user to manipulate stuff there.

Note

The list module control is disabled by default, enable it if needed. It is shown below the add record control if not changed by below or after settings.

Options:

pid (string)

pid of the new record. Can be an hard pid setting, or one of these markers, see select foreign_table_where. Falls back to "current pid" if not set, forces pid=0 if records of this table are only allowed on root level.

• ###CURRENT_PID###

• ###THIS_UID###

• ###SITEROOT###

• ###PAGE_TSCONFIG_ID###

• ###PAGE_TSCONFIG_IDLIST###

• ###PAGE_TSCONFIG_STR###

table (string)

List records of this table only, falls back to first table from allowed list if not set for type='group' fields and to foreign_table for type='select' fields.

title (string or LLL reference)

Allows to set a different 'title' attribute to the popup icon, defaults to LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.list

fieldInformation

Datatype

array

Scope

Display

Description

Show information between an element label and the main element input area. Configuration works identical to the "fieldWizard" property, no default configuration in the core exists (yet). In contrast to "fieldWizard", HTML returned by fieldInformation is limited, see FormEngine docs for more details.

fieldWizard

Datatype

array

Scope

Display

Description

Specifies wizards rendered below the main input area of an element. Single type / renderType elements can register default wizards which are merged with this property.

As example, type='check' comes with this default wizards configuration:

protected $defaultFieldWizard = [
    'localizationStateSelector' => [
        'renderType' => 'localizationStateSelector',
    ],
    'otherLanguageContent' => [
        'renderType' => 'otherLanguageContent',
        'after' => [
            'localizationStateSelector'
        ],
    ],
    'defaultLanguageDifferences' => [
        'renderType' => 'defaultLanguageDifferences',
        'after' => [
            'otherLanguageContent',
        ],
    ],
];

This is be merged with the configuration from TCA, if there is any. Below example disables the default localizationStateSelector wizard.

'aField' => [
    'config' => [
        'fieldWizard' => [
            'localizationStateSelector' => [
                'disabled' => true,
            ],
        ],
    ],
],

It is possible to add own wizards by adding them to the TCA of the according field and pointing to a registered renderType, to resort wizards by overriding the before and after keys, to hand over additional options in the optional options array to specific wizards, and to disable single wizards using the disabled key. Developers should have a look at the FormEngine docs for details.

defaultLanguageDifferences

Datatype

array

Scope

fieldWizard

Description

Show a "diff-view" if the content of the default language record has been changed after the translation overlay has been created. The ['ctrl'] section property transOrigDiffSourceField has to be specified to enable this wizard in a translated record.

This wizard is important for editors who maintain translated records: They can see what has been changed in their localization parent between the last save operation of the overlay.

A field has been changed in default language record

localizationStateSelector

Datatype

array

Scope

fieldWizard

Description

The localization state selector wizard displays two or three radio buttons in localized records saying: "This field has an own value distinct from my default language or source record", "This field has the same value as the default language record" or "This field has the same value as my source record". This wizard is especially useful for the tt_content table. It will only render, if:

• The record is a localized record (not default language)

• The record is in "translated" (connected), but not in "copy" (free) mode

• The table is localization aware using the ['ctrl'] properties languageField, transOrigPointerField. If the optional property translationSource is also set, and if the record is a translation from another localized record, the third radio appears.

• The property ['config']['behaviour']['allowLanguageSynchronization'] is set to true

Example localization state selector on an type=input field

otherLanguageContent

Datatype

array

Scope

fieldWizard

Description

Show values from the default language record and other localized records if the edited row is a localized record. Often used in tt_content fields. By default, only the value of the default language record is shown, values from further translations can be shown by setting the userTsConfig property additionalPreviewLanguages.

The wizard shows content only for "simple" fields. For instance, it does not work for database relation fields, and if the field is set to readOnly. Additionally, the table has to be language aware by setting up the according fields in ['ctr'] section.

Header field showing values from two other languages

fileFolder

Datatype

string

Scope

Display / Proc.

Description

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

Specify the folder relative to the PATH_site, possibly using the prefix "EXT:" to point to an extension folder.

Files from the folder is selected recursively to the level specified by fileFolder_recursions and only files of the extension defined by fileFolder_extList is selected.

Only the file reference relative to the "fileFolder" is stored.

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

Example:

'config' => [
    'type' => 'select',
    'items' => [
        [ '', 0 ],
    ],
    'fileFolder' => 'EXT:cms/tslib/media/flags/',
    'fileFolder_extList' => 'png,jpg,jpeg,gif',
    'fileFolder_recursions' => 0,
    'size' => 1,
    'minitems' => 0,
    'maxitems' => 1,
],

fileFolder_extList

Datatype

string

Scope

Display / Proc.

Description

List of extensions to select. If blank, all files are selected. Specify list in lowercase. Only useful in combination with property fileFolder.

fileFolder_recursions

Datatype

integer

Scope

Display / Proc.

Description

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

foreign_table

Datatype

string (table name)

Scope

Proc. / Display

Description

The item-array will be filled with records from the table defined here. The table must be configured in $GLOBALS['TCA'].

foreign_table_prefix

Datatype

string or LLL reference

Scope

Display

Description

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

foreign_table_where

Datatype

string (SQL WHERE)

Scope

Proc. / Display

Description

The items from foreign_table are selected with this WHERE-clause.

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 = 0 ORDER BY [foreign_table].sorting

Markers:

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.

• ###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.

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.

items

Datatype

array

Scope

Display / Proc.

Description

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. 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 with renderType='selectCheckBox'.

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

Example:

A configuration could look like this:

'type' => 'select',
'items' => [
   [ 'English', '' ],
   [ 'Danish', 'dk' ],
   [ 'German', 'de' ],
]

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

'type' => 'select',
'items' => [
    [ 'LLL:EXT:cms/locallang_ttc.php:k1', 0, 'EXT:myext/Resources/Public/selicons/k1.gif' ],
    [ 'LLL:EXT:cms/locallang_ttc.php:k2', 1, 'tx-myext-selicons-k2' ],
    [ 'LLL:EXT:cms/locallang_ttc.php:k3', 2, 'tx-myext-selicons-k3' ],
]

itemsProcFunc

Datatype

string (class->method reference)

Scope

Display / Proc.

Description

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

[classname]->[methodname]

The function/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.

See extension styleguide for a couple of examples on different config type's.

localizeReferencesAtParentLocalization

Datatype

boolean

Scope

Proc.

Description

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

maxitems

Datatype

integer > 0

Scope

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.

Note

Property maxitems is ignored with type='select' and renderType='selectSingle'.

Description

Display / Proc.

minitems

Datatype

integer > 0

Scope

Display

Description

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

MM

Datatype

string (table name)

Scope

Proc.

Description

Means that the relation to the records of foreign_table is done with a M-M relation with a third "join" table.

That table has three columns as a minimum:

uid_local, uid_foreign (Required)

Storing uids of both sides. If done right, this is reflected in the table name - tx_foo_local_foreign_mm

sorting (Required)

Is a required field used for ordering the items.

sorting_foreign

Is required if the relation is bidirectional (see description and example below table)

tablenames

Is used if multiple tables are allowed in the relation.

uid (auto-incremented and PRIMARY KEY)

May be used if you need the "multiple" feature (which allows the same record to be references multiple times in the box. See MM_hasUidField for type='select' and MM_hasUidField for type='group' fields.

further fields

May exist, in particular if MM_match_fields / MM_match_fields is involved in the set up.

Example SQL #1

Most simple MM table

CREATE TABLE tx_testmmrelations_one_rel_mm (
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign)
);

Example SQL #2

Advanced with uid field, "ident" used with MM_match_fields and "sorting_foreign" for bidirectional MM relations:

CREATE TABLE tx_testmmrelations_two_rel_mm (
    uid int(11) NOT NULL auto_increment,
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    tablenames varchar(30) DEFAULT '' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,
    sorting_foreign int(11) DEFAULT '0' NOT NULL,
    ident varchar(30) DEFAULT '' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign),
    PRIMARY KEY (uid)
);

Value of field

The field name of the config is not used for data-storage anymore but rather it's set to the number of records in the relation on each update, so the field should be an integer.

MM relations and flexforms

MM relations has been tested to work with flexforms if not in a repeated element in a section.

Note

Using MM relations you can ONLY store real relations for foreign tables in the list - no additional string values or non-record values.

MM_hasUidField

Datatype

boolean

Scope

Proc.

Description

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.

MM_insert_fields

Datatype

array

Scope

Proc.

Description

Array of field=>value pairs to insert when writing new MM relations.

MM_table_where

Datatype

string (SQL WHERE)

Scope

Proc.

Description

Additional where clause used when reading MM relations.

MM_match_fields

Datatype

array

Scope

Display / Proc.

Description

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

MM_opposite_field

Datatype

string (field name)

Scope

Proc.

Description

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

MM_oppositeUsage

Datatype

array

Scope

Proc.

Description

In a MM bidirectional relation using select match fields / group 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 whichfields 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:

$GLOBALS['TCA']['sys_category']['columns']['items']['config']['MM_oppositeUsage'] = [
    'pages' => ['tx_examples_cats', 'categories'],
    'sys_file_metadata' => ['categories'],
    'tt_content' => ['categories'],
];

multiple

Datatype

boolean

Scope

Display / Proc.

Description

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. Also, with MM relations in general you must use a UID field in the join table, see description for "MM".

multiSelectFilterItems

Datatype

array

Scope

Display

Description

Contains predefined elements for the filter field enabled by enableMultiSelectFilterTextfield. On selecting an item, the list of available items gets automatically filtered.

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

• First value is the filter value of the item .

• Second value is the item label (string or LLL reference)

Example configuration:

'related_content' => [
    'label' => 'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.related_content',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectMultipleSideBySide',
        'foreign_table' => 'tt_content',
        'foreign_table_where' => 'ORDER BY header ASC',
        'size' => 5,
        'minitems' => 0,
        'enableMultiSelectFilterTextfield' => TRUE,
        'multiSelectFilterItems' => [
            [
                'image',
                'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.related_content.image'
            ],
            [
                'typo3',
                'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.related_content.typo3'
            ],
        ],
    ],
],

Filtering available items with both predefined keywords and free input

readOnly

Datatype

boolean

Scope

Display

Description

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.

Warning

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

rootLevel

Datatype

boolean

Scope

Display

Description

If set, the foreign_table_where will be ignored and a "pid=0" will be added to the query to select only records from root level of the page tree.

size

Datatype

integer

Scope

Display

Description

Height of the box in FormEngine.

With type='select' and renderType='selectSingle', the default is 1, but if set to a number greater than 1, the select drop down will be displayed as box where only one item can be selected.

With type='select' and renderType='selectSingleBox', this value should not be set to a number smaller than 2.

With type='group', the "box" collapses to a single element input and should then be combined with a maxitems=1, the default is 5.

special

Datatype

string (keyword)

Scope

Display / Proc.

Description

This configures the selector box to fetch content from some predefined internal source. These options are used for backend user management and pretty worthless for most other purposes. Keywords:

tables

The list of TCA tables is added to the selector (excluding "adminOnly" tables).

pagetypes

All "doktype"-values for the "pages" table are added.

exclude

The list of "excludeFields" as found in $GLOBALS['TCA'] is added.

modListGroup

Module-lists added for groups.

modListUser

Module-lists added for users.

explicitValues

List values that require explicit permissions to be allowed or denied, see authMode.

languages

List system languages ("sys_language" records from page tree root + Default language)

custom

Custom values set by backend modules (see TYPO3_CONF_VARS[BE][customPermOptions])

Properties renderType = 'selectTree'

A tree for selecting hierarchical data items.

Note

This section needs a validation of the single properties - probably some of the relation properties like MM are not valid.

allowNonIdValues

Datatype

boolean

Scope

Proc.

Description

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.

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! Will not work if you also use "MM" relations!

authMode

Datatype

string (keyword)

Scope

Display / Proc.

Description

Authorization mode for the selector box. Keywords are:

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). Items without any of these keywords can be selected as usual without any access restrictions applied.

Note

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.

authMode_enforce

Datatype

string (keyword)

Scope

Display / Proc.

Description

Various additional enforcing options for authMode, keywords:

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!

behaviour

Datatype

array

Scope

Proc.

Description

The behaviour array contains various sub properties to specify processing options like localization overlay behaviour and children behaviour for relation types. Available properties vary by type and renderType combination.

allowLanguageSynchronization

| Scope: Proc. | Type: boolean | Default: false |

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.

default

Datatype

string

Scope

Display / Proc.

Description

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

disableNoMatchingValueElement

Datatype

boolean

Scope

Display

Description

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.

dontRemapTablesOnCopy

Datatype

string (list of tables)

Scope

Proc.

Description

Only with internal_type='db'

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

Datatype

string (list of)

Scope

Display / Proc.

Description

List of keys that exclude any other keys in a select box where multiple items could be selected.

"Show at any login" of "fe_groups" (tables "pages" and "tt_content") is an example where such a configuration is used.

fieldInformation

Datatype

array

Scope

Display

Description

Show information between an element label and the main element input area. Configuration works identical to the "fieldWizard" property, no default configuration in the core exists (yet). In contrast to "fieldWizard", HTML returned by fieldInformation is limited, see FormEngine docs for more details.

fieldWizard

Datatype

array

Scope

Display

Description

Specifies wizards rendered below the main input area of an element. Single type / renderType elements can register default wizards which are merged with this property.

As example, type='check' comes with this default wizards configuration:

protected $defaultFieldWizard = [
    'localizationStateSelector' => [
        'renderType' => 'localizationStateSelector',
    ],
    'otherLanguageContent' => [
        'renderType' => 'otherLanguageContent',
        'after' => [
            'localizationStateSelector'
        ],
    ],
    'defaultLanguageDifferences' => [
        'renderType' => 'defaultLanguageDifferences',
        'after' => [
            'otherLanguageContent',
        ],
    ],
];

This is be merged with the configuration from TCA, if there is any. Below example disables the default localizationStateSelector wizard.

'aField' => [
    'config' => [
        'fieldWizard' => [
            'localizationStateSelector' => [
                'disabled' => true,
            ],
        ],
    ],
],

It is possible to add own wizards by adding them to the TCA of the according field and pointing to a registered renderType, to resort wizards by overriding the before and after keys, to hand over additional options in the optional options array to specific wizards, and to disable single wizards using the disabled key. Developers should have a look at the FormEngine docs for details.

fileFolder

Datatype

string

Scope

Display / Proc.

Description

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

Specify the folder relative to the PATH_site, possibly using the prefix "EXT:" to point to an extension folder.

Files from the folder is selected recursively to the level specified by fileFolder_recursions and only files of the extension defined by fileFolder_extList is selected.

Only the file reference relative to the "fileFolder" is stored.

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

Example:

'config' => [
    'type' => 'select',
    'items' => [
        [ '', 0 ],
    ],
    'fileFolder' => 'EXT:cms/tslib/media/flags/',
    'fileFolder_extList' => 'png,jpg,jpeg,gif',
    'fileFolder_recursions' => 0,
    'size' => 1,
    'minitems' => 0,
    'maxitems' => 1,
],

fileFolder_extList

Datatype

string

Scope

Display / Proc.

Description

List of extensions to select. If blank, all files are selected. Specify list in lowercase. Only useful in combination with property fileFolder.

fileFolder_recursions

Datatype

integer

Scope

Display / Proc.

Description

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

foreign_table

Datatype

string (table name)

Scope

Proc. / Display

Description

The item-array will be filled with records from the table defined here. The table must be configured in $GLOBALS['TCA'].

foreign_table_prefix

Datatype

string or LLL reference

Scope

Display

Description

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

foreign_table_where

Datatype

string (SQL WHERE)

Scope

Proc. / Display

Description

The items from foreign_table are selected with this WHERE-clause.

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 = 0 ORDER BY [foreign_table].sorting

Markers:

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.

• ###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.

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.

items

Datatype

array

Scope

Display / Proc.

Description

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. 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 with renderType='selectCheckBox'.

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

Example:

A configuration could look like this:

'type' => 'select',
'items' => [
   [ 'English', '' ],
   [ 'Danish', 'dk' ],
   [ 'German', 'de' ],
]

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

'type' => 'select',
'items' => [
    [ 'LLL:EXT:cms/locallang_ttc.php:k1', 0, 'EXT:myext/Resources/Public/selicons/k1.gif' ],
    [ 'LLL:EXT:cms/locallang_ttc.php:k2', 1, 'tx-myext-selicons-k2' ],
    [ 'LLL:EXT:cms/locallang_ttc.php:k3', 2, 'tx-myext-selicons-k3' ],
]

itemsProcFunc

Datatype

string (class->method reference)

Scope

Display / Proc.

Description

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

[classname]->[methodname]

The function/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.

See extension styleguide for a couple of examples on different config type's.

localizeReferencesAtParentLocalization

Datatype

boolean

Scope

Proc.

Description

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

maxitems

Datatype

integer > 0

Scope

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.

Note

Property maxitems is ignored with type='select' and renderType='selectSingle'.

Description

Display / Proc.

minitems

Datatype

integer > 0

Scope

Display

Description

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

MM

Datatype

string (table name)

Scope

Proc.

Description

Means that the relation to the records of foreign_table is done with a M-M relation with a third "join" table.

That table has three columns as a minimum:

uid_local, uid_foreign (Required)

Storing uids of both sides. If done right, this is reflected in the table name - tx_foo_local_foreign_mm

sorting (Required)

Is a required field used for ordering the items.

sorting_foreign

Is required if the relation is bidirectional (see description and example below table)

tablenames

Is used if multiple tables are allowed in the relation.

uid (auto-incremented and PRIMARY KEY)

May be used if you need the "multiple" feature (which allows the same record to be references multiple times in the box. See MM_hasUidField for type='select' and MM_hasUidField for type='group' fields.

further fields

May exist, in particular if MM_match_fields / MM_match_fields is involved in the set up.

Example SQL #1

Most simple MM table

CREATE TABLE tx_testmmrelations_one_rel_mm (
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign)
);

Example SQL #2

Advanced with uid field, "ident" used with MM_match_fields and "sorting_foreign" for bidirectional MM relations:

CREATE TABLE tx_testmmrelations_two_rel_mm (
    uid int(11) NOT NULL auto_increment,
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    tablenames varchar(30) DEFAULT '' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,
    sorting_foreign int(11) DEFAULT '0' NOT NULL,
    ident varchar(30) DEFAULT '' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign),
    PRIMARY KEY (uid)
);

Value of field

The field name of the config is not used for data-storage anymore but rather it's set to the number of records in the relation on each update, so the field should be an integer.

MM relations and flexforms

MM relations has been tested to work with flexforms if not in a repeated element in a section.

Note

Using MM relations you can ONLY store real relations for foreign tables in the list - no additional string values or non-record values.

MM_hasUidField

Datatype

boolean

Scope

Proc.

Description

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.

MM_insert_fields

Datatype

array

Scope

Proc.

Description

Array of field=>value pairs to insert when writing new MM relations.

MM_table_where

Datatype

string (SQL WHERE)

Scope

Proc.

Description

Additional where clause used when reading MM relations.

MM_match_fields

Datatype

array

Scope

Display / Proc.

Description

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

MM_opposite_field

Datatype

string (field name)

Scope

Proc.

Description

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

MM_oppositeUsage

Datatype

array

Scope

Proc.

Description

In a MM bidirectional relation using select match fields / group 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 whichfields 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:

$GLOBALS['TCA']['sys_category']['columns']['items']['config']['MM_oppositeUsage'] = [
    'pages' => ['tx_examples_cats', 'categories'],
    'sys_file_metadata' => ['categories'],
    'tt_content' => ['categories'],
];

multiple

Datatype

boolean

Scope

Display / Proc.

Description

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. Also, with MM relations in general you must use a UID field in the join table, see description for "MM".

readOnly

Datatype

boolean

Scope

Display

Description

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.

Warning

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

rootLevel

Datatype

boolean

Scope

Display

Description

If set, the foreign_table_where will be ignored and a "pid=0" will be added to the query to select only records from root level of the page tree.

size

Datatype

integer

Scope

Display

Description

Height of the box in FormEngine.

With type='select' and renderType='selectSingle', the default is 1, but if set to a number greater than 1, the select drop down will be displayed as box where only one item can be selected.

With type='select' and renderType='selectSingleBox', this value should not be set to a number smaller than 2.

With type='group', the "box" collapses to a single element input and should then be combined with a maxitems=1, the default is 5.

treeConfig

Datatype

array

Scope

Display

Description

Either childrenField or parentField has to be set - childrenField takes precedence. Keywords:

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.

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