Core API

type

string

[Must be set to "select"]

Display / Proc.

items

array

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:

1. First value is the item label (LS)

2. 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).

3. Third value is an optional icon.
   Default from "t3lib/gfx/" but if prepended with "../" it will be taken from any PATH_site directory. You can also prepend the files "ext/" and "sysext/" if they are in global extension directories. And finally - taking precedence over any other value - files prepended with "EXT:" will be found in the respective extension.

4. Forth value is an optional description text. This is only shown when the list is shown by renderMode "checkbox".

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

Example:

A configuration could look like this:

      'type' => 'select',

      'items' => Array (

          Array('English', ''),

          Array('Danish', 'dk'),

          Array('German', 'de'),

      )

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

  'type' => 'select',    

  'items' => Array (

      Array('LLL:EXT:cms/locallang_ttc.php:k1', 0, 'selicons/k1.gif'),

      Array('LLL:EXT:cms/locallang_ttc.php:k2', 1, 'selicons/k2.gif'),

      Array('LLL:EXT:cms/locallang_ttc.php:k3', 2, 'selicons/k3.gif'),

  )

Display

itemsProcFunc

string

(function reference)

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

The function/method will have an array of parameters passed to it (where the item-array is passed by reference in the key 'items'). By modifying the array of items, you alter the list of items.

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

Display

selicon_cols

integer (>0)

The number of rows in which to position the iconimages for the selectorbox. Default is to render as many columns as iconimages.

Display

suppress_icons

string

Lets you disable display of icons. Can be nice to do if icons are coming from foreign database records and you don't want them.

Set it to "IF_VALUE_FALSE" if you only want to see icons when a value (non-blank, non-zero) is selected. Otherwise no icons are shown.

Set it to "ONLY_SELECTED" if you only want to see an icon for the selected item.

Set to "1" (true) if you never want any icons.

Display

iconsInOptionTags

boolean

If set, icons will appear in the <option> tags of the selector box. This feature seems only to work in Mozilla.

foreign_table

string

(tablename)

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

See the other related options below.

Proc. / Display

foreign_table_where

string

(SQL WHERE clause)

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:

You can use markers in the WHERE clause:

1. ###REC_FIELD_[fieldname]###

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

3. ###CURRENT_PID### - is the current page id (pid of the record).

4. ###STORAGE_PID###

5. ###SITEROOT###

6. ###PAGE_TSCONFIG_ID### -  a value you can set from Page TSconfig dynamically.

7. ###PAGE_TSCONFIG_IDLIST### -  a value you can set from Page TSconfig dynamically.

8. ###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 commalist of integers (default is zero) and PAGE_TSCONFIG_STR will be addslashes'ed before substitution (default is blank string).

Proc. / Display

foreign_table_prefix

string

(LS)

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

Display

foreign_table_loadIcons

boolean

If set, then the icons for the records of the foreign table are loaded and presented in the form.

This depends on the 'selicon_field' of the foreign tables [ctrl] section being configured.

Display

neg_foreign_table

neg_foreign_table_where

neg_foreign_table_prefix

neg_foreign_table_loadIcons

neg_foreign_table_imposeValueField

[mixed]

Four options corresponding to the 'foreign_table'-keys but records from this table will be referenced by negative uid-numbers (unless if MM is configured in which case it works like the group-type).

'neg_foreign_table' is active only if 'foreign_table' is defined also.

Display /  Proc.

fileFolder

string

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" (see below) and only files of the extension defined by "fileFolder_extList" is selected (see below).

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' => Array (

      'type' => 'select',

      'items' => Array (

          Array('',0),

      ),

      'fileFolder' => 'EXT:cms/tslib/media/flags/',

      'fileFolder_extList' => 'png,jpg,jpeg,gif',

      'fileFolder_recursions' => 0,

      'selicon_cols' => 8,

      'size' => 1,

      'minitems' => 0,

      'maxitems' => 1,

  )

Display / Proc

fileFolder_extList

string

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

See "t3lib_div::getAllFilesAndFoldersInPath()"

Display / Proc

fileFolder_recursions

integer

Depth of directory recursions. Default is 99. Specify in range from 0-99.

0 (zero) means no recursion into subdirectories.

See "t3lib_div::getAllFilesAndFoldersInPath()"

Display / Proc

allowNonIdValues

boolean

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!

Notice: Will not work if you also use "MM" relations!

Proc.

default

string

Default value.

If empty, the first element in the items array is selected.

Display / Proc.

dontRemapTablesOnCopy

(See same feature for type="group", internal_type="db")

Set it to the exact same value as "foreign_table" if you don't want values to be remapped on copy.

Proc.

rootLevel

boolean

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.

Display

MM

string

(table name)

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

That table typically has three columns:

1. uid_local, uid_foreign for uids respectively.

2. sorting is a required field used for ordering the items.

The fieldname 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.

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

Proc.

MM_opposite_field

string

(field name)

If you want to make an mm relation editable from the foreign side of the relation as well, you need to set MM_opposite_field on the foreign side to the fieldname 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".

Proc.

MM_match_fields

array

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

MM_insert_fields

array

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

MM_table_where

string (SQL WHERE)

Additional where clause used when reading MM relations.

special

string

(any of keywords)

This configures the selector box to fetch content from some predefined internal source. These are the possibilities:

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

2. pagetypes - all  "doktype"-values for the "pages" table are added.

3. exclude - the list of "excludeFields" as found in $TCA is added.

4. modListGroup -  module-lists added for groups.

5. modListUser -  module-lists added for users.

6. explicitValues � List values that require explicit permissions to be allowed or denied. (See "authMode" directive for the "select" type).

7. languages � List system languages (sys_language records from page tree root + Default language)

8. custom � Custom values set by backend modules (see TYPO3_CONF_VARS[BE][customPermOptions])

As you might have guessed these options are used for backend user management and pretty worthless for most other purposes.

Display / Proc.

size

integer

Height of the selectorbox in TCEforms.

Display

autoSizeMax

integer

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

Display

selectedListStyle

string

If set, this will override the default style of the selector box with selected items (which is "width:200px").

Applies for when maxitems is > 1

Display

itemListStyle

string

If set, this will override the default style of the selector box with available items to select (which is "width:200px").

Applies for when maxitems is > 1

Display

renderMode

string (any of keywords)

(Only for maxitems > 1)

Renders the list of multiple options as either a list of checkboxes or as a selector box with multiple choices.

The data type is fully compatible with an ordinary multiple element list except that duplicate values cannot be represented for obvious reasons (option "multiple" does not work) and the order of values is fixed.

Keywords are:

1. checkbox - Renders a list of checkboxes

2. singlebox - Renders a single multiple selector box

When renderMode is "checkbox" or "singlebox" all values selected by "foreign_table" settings will automatically have their icon part in the items array set to the record icon (unless overruled by "selicon_field" of that table).

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

multiple

boolean

Allows the same item more than once in a list.

Display / Proc.

maxitems

integer > 0

Maximum number of items in the selector box. (Default = 1)

Display / Proc

minitems

integer > 0

Minimum number of items in the selector box. (Default = 0)

Display

wizards

array

[See section later for options]

Display

disableNoMatchingValueElement

boolean

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.

Display

authMode

string keyword

Authorization mode for the selector box. Keywords are:

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

2. 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 explicitly selected if a user should be denied access.

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

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

maxitems > 1

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

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

Display / Proc

authMode_enforce

string keyword

Various additional enforcing options for authMode.

Keywords are:

1. 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 an unallowed value.
   Notice: This works only when maxitems <=1 (and no MM relations) since the "raw"  value in the record is all that is evaluated!

Display / Proc

exclusiveKeys

string (list of)

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.