[‘columns’][fieldname][‘config’] / TYPE: “select”
http://typo3.org/documentation/document-library/core-documentation/doc_core_api/4.2.0/view/4/2/#id4425347
fieldname
Selectors boxes are very common elements in forms. By the “select” type you can create selector boxes. In the most simple form this is a list of values among which you can chose only one. In that way it is similar to the “radio” type above.
It is also possible to configure more complex types where the values from from a look up in another database table and you can even have a type where more than one value can be selected in any given order you like.
Here follow some code listings as examples:
Example – A simple selector box:
This is the most simple selector box you can get. It contains a static set of options you can select from:
1: ‘type’ => Array (
2: ‘label’ => ‘Test’,
3: ‘config’ => Array (
4: ‘type’ => ‘select’,
5: ‘items’ => Array (
6: Array(”, ‘0’),
7: Array(‘Option 1’, ‘1’),
8: Array(‘Option 2’, ‘2’),
9: Array(‘__Final option:__’, ‘–div–‘),
10: Array(‘Option 3’, ‘3’),
11: ),
12: )
13: ),
In the configuration the elements are configured by the “items” array. Each entry in the array contains pairs of label/value. Notice line 9; this entry is a divider. This value is not possible to select – it only helps to divide the list of options with a label indicating a new section.
Example – A multiple value selector with contents from a database table
1: ‘include_static’ => Array (
2: ‘label’ => ‘Include static:’,
3: ‘config’ => Array (
4: ‘type’ => ‘select’,
5: ‘foreign_table’ => ‘static_template’,
6: ‘foreign_table_where’ => ‘ORDER BY static_template.title DESC’,
7: ‘size’ => 10,
8: ‘maxitems’ => 20,
9: ‘default’ => ”
10: )
11: ),
This shows a simple configuration where the values are fetched from a foreign database table ordered by the title (line 5-6). Notice line 7 setting the size to 10 (the height of the selector boxes) and line 8 setting the maximum number of values you can select to 20.
The value stored in the database will be a comma list of uid numbers of the records selected.
Example – Using a look up table for single value
In this case the selector box looks up languages in a static table from an extension “static_info_tables”:
The configuration looks like this:
1: ‘static_lang_isocode’ => Array (
2: ‘exclude’ => 1,
3: ‘label’ => ‘LLL:EXT:cms/locallang_tca.php:sys_language.isocode’,
4: ‘displayCond’ => ‘EXT:static_info_tables:LOADED:true’,
5: ‘config’ => Array (
6: ‘type’ => ‘select’,
7: ‘items’ => Array (
8: Array(”,0),
9: ),
10: ‘foreign_table’ => ‘static_languages’,
11: ‘foreign_table_where’ => ‘AND static_languages.pid=0 ORDER BY static_languages.lg_name_en’,
12: ‘size’ => 1,
13: ‘minitems’ => 0,
14: ‘maxitems’ => 1,
15: )
16: ),
Notice how line 4 will set a condition that this box should only be displayed if the extension it belongs to exists! That is very important since otherwise the table will not be in the database and we will get SQL errors.
In line 11 we see how a condition to the look up apply. Finally in line 12 and 14 it is explicitly configured that the selector box can contain only one value (line 14) and therefore should be only one row high (line 12)
Example – Mixing lookup values with static values
This is the well known selector for frontend user group access restriction. It contains all user groups the backend user can access (here: “group”) plus additional static values (“Hide at login”, “Show at any login”) and a divider (“__Usergroups:__”)
The configuration looks like this:
1: ‘fe_group’ => Array (
2: ‘exclude’ => 1,
3: ‘label’ => ‘LLL:EXT:lang/locallang_general.php:LGL.fe_group’,
4: ‘config’ => Array (
5: ‘type’ => ‘select’,
6: ‘items’ => Array (
7: Array(”, 0),
8: Array(‘LLL:EXT:lang/locallang_general.php:LGL.hide_at_login’, -1),
9: Array(‘LLL:EXT:lang/locallang_general.php:LGL.any_login’, -2),
10: Array(‘LLL:EXT:lang/locallang_general.php:LGL.usergroups’, ‘–div–‘)
11: ),
12: ‘foreign_table’ => ‘fe_groups’
13: )
14: ),
Example – Adding icons for selection
This example shows how you can add icons to the selection choice very easily. Each icon is associated with an option in the selector box and clicking the icon will automatically select the option in the selector box and more the black arrow:
The configuration looks like this.
1: ‘imageorient’ => Array (
2: ‘label’ => ‘LLL:EXT:cms/locallang_ttc.php:imageorient’,
3: ‘config’ => Array (
4: ‘type’ => ‘select’,
5: ‘items’ => Array (
6: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.0’, 0, ‘selicons/above_center.gif’),
7: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.1’, 1, ‘selicons/above_right.gif’),
8: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.2’, 2, ‘selicons/above_left.gif’),
9: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.3’, 8, ‘selicons/below_center.gif’),
10: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.4’, 9, ‘selicons/below_right.gif’),
11: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.5’, 10, ‘selicons/below_left.gif’),
12: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.6’, 17, ‘selicons/intext_right.gif’),
13: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.7’, 18, ‘selicons/intext_left.gif’),
14: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.8’, ‘–div–‘),
15: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.9’, 25, ‘selicons/intext_right_nowrap.gif’),
16: Array(‘LLL:EXT:cms/locallang_ttc.php:imageorient.I.10’, 26, ‘selicons/intext_left_nowrap.gif’)
17: ),
18: ‘selicon_cols’ => 6,
19: ‘default’ => ‘8’
20: )
21: ),
Notice how each label/value pair contains an icon reference on the third position and how line 18 configures that the icons should be arranged in 6 columns.
Also, notice the default value (line 19) set to 8 meaning that the option with value “8” (line 9) will be selected by default.
Example – Adding wizards
This example shows how wizards can be added to a selector box. The three typical wizards for a selector box is edit, add and list items. This enables the user to create new items in the look up table while being right at the selector box where he want to select them:
The configuration is rather long and looks like this (notice, that wizards are not exclusively available for selector boxes!)
1: ‘file_mountpoints’ => Array (
2: ‘label’ => ‘File Mounts:’,
3: ‘config’ => Array (
4: ‘type’ => ‘select’,
5: ‘foreign_table’ => ‘sys_filemounts’,
6: ‘foreign_table_where’ => ‘ AND sys_filemounts.pid=0 ORDER BY sys_filemounts.title’,
7: ‘size’ => ‘3’,
8: ‘maxitems’ => ’10’,
9: ‘autoSizeMax’ => 10,
10: ‘show_thumbs’ => ‘1’,
11: ‘wizards’ => Array(
12: ‘_PADDING’ => 1,
13: ‘_VERTICAL’ => 1,
14: ‘edit’ => Array(
15: ‘type’ => ‘popup’,
16: ‘title’ => ‘Edit filemount’,
17: ‘script’ => ‘wizard_edit.php’,
18: ‘icon’ => ‘edit2.gif’,
19: ‘popup_onlyOpenIfSelected’ => 1,
20: ‘JSopenParams’ => ‘height=350,width=580,status=0,menubar=0,scrollbars=1’,
21: ),
22: ‘add’ => Array(
23: ‘type’ => ‘script’,
24: ‘title’ => ‘Create new filemount’,
25: ‘icon’ => ‘add.gif’,
26: ‘params’ => Array(
27: ‘table’=>’sys_filemounts’,
28: ‘pid’ => ‘0’,
29: ‘setValue’ => ‘prepend’
30: ),
31: ‘script’ => ‘wizard_add.php’,
32: ),
33: ‘list’ => Array(
34: ‘type’ => ‘script’,
35: ‘title’ => ‘List filemounts’,
36: ‘icon’ => ‘list.gif’,
37: ‘params’ => Array(
38: ‘table’=>’sys_filemounts’,
39: ‘pid’ => ‘0’,
40: ),
41: ‘script’ => ‘wizard_list.php’,
42: )
43: )
44: )
45: ),
From line 11 the configuration of the wizards takes place. See the wizard section in this document for more information.
Notice the configuration of “autoSizeMax” in line 9. This value will make the height of the selector boxes adjust themselves automatically depending on the content in them.
Example – User processing and advanced look ups
In this example some more advanced features are used. On of them is that the look up for other database records is limited to the PID of the host record. In other words, all entries are records located in the same page as the record we are editing here:
Configuration looks like this:
4: ‘config’ => Array (
5: ‘type’ => ‘select’,
6: ‘items’ => Array (
7: Array(”,0),
8: ),
9: ‘foreign_table’ => ‘tx_templavoila_datastructure’,
10: ‘foreign_table_where’ => ‘AND tx_templavoila_datastructure.pid=###CURRENT_PID### ORDER BY tx_templavoila_datastructure.uid’,
11: ‘size’ => 1,
12: ‘minitems’ => 0,
13: ‘maxitems’ => 1,
14: ‘itemsProcFunc’ => ‘tx_templavoila_handleStaticdatastructures->main’,
15: ‘allowNonIdValues’ => 1,
16: ‘suppress_icons’ => ‘ONLY_SELECTED’,
In line 10 you see how the marker “###CURRENT_PID###” is used to limit the look up to the current page id.
In line 14 it is also defined that the array of options should be processed by a user defined function, namely the method “main()” in the class “tx_templavoila_handleStaticdatastructures”. For this to work, the class must be included during configuration (typically in ext_localconf.php files)
Line 15 configures that non-integer values are allowed. Normally values are restricted to integers if we are dealing with database look ups.
Line 16 means that even if icons can be displayed for each of the records in the look up, an icon will be displayed only for the selected record (if any).
Example – Bidrectional MM relations
For a table, “user_testmmrelations_two”, we have a field “rel” with configured with MM relations:
"rel" => Array (
"exclude" => 1,
"label" => "Relations:",
"config" => Array (
"type" => "select",
"foreign_table" => "user_testmmrelations_one",
"foreign_table_where" => "ORDER BY user_testmmrelations_one.uid",
"size" => 10,
"minitems" => 0,
"maxitems" => 10,
"MM" => "user_testmmrelations_two_rel_mm",
'MM_match_fields' => array('ident'=>'table_two')
)
),
The MM table is called “user_testmmrelations_two_rel_mm”, and the field “ident” is used to match on with the word “table_two”. Doing this enables us to use the same MM table for other fields using other keywords for the “ident” field.
In another table “user_testmmrelations_one” a field called “rel2” constitutes the foreign side of the bidirectional relation:
"rel2" => Array (
"label" => "Foreign relation:",
"config" => Array (
"type" => "select",
"foreign_table" => "user_testmmrelations_two",
"foreign_table_where" => "ORDER BY user_testmmrelations_two.uid",
"size" => 10,
"minitems" => 0,
"maxitems" => 10,
"MM" => "user_testmmrelations_two_rel_mm",
'MM_match_fields' => array('ident'=>'table_two'),
"MM_opposite_field" => "rel"
)
),
Notice how in both cases “ foreign_table” points to the table name of the other. Also they use the exact same set up except in the foreign side case above the field “MM_opposite_field” is set to “rel” – the name of the field in table “user_testmmrelations_two”!
The SQL looks like:
#
# Table structure for table 'user_testmmrelations_two_rel_mm'
#
#
CREATE TABLE user_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),
);
In the backend the form could look like:
So, from a record in table two (native) there are two relations made to records in table one.
If we look at one of the records from table one we see the relation made from “TWO (1)”:
In the database it looks like this:
Example – FlexForms and MM relations
MM relations can be used with flexforms. Here is an example:
The flexform field configuration looks like this:
<rel1>
<TCEforms>
<label>Relation:</label>
<config>
<type>group</type>
<internal_type>db</internal_type>
<allowed>user_testmmrelations_three</allowed>
<size>10</size>
<minitems>0</minitems>
<maxitems>10</maxitems>
<MM>user_testmmrelations_two_rel_mm</MM>
<MM_match_fields>
<ident>table_one_flex</ident>
</MM_match_fields>
<multiple>1</multiple>
<MM_hasUidField>1</MM_hasUidField>
</config>
</TCEforms>
</rel1>
As you can see the same element (titled “3-3 (UID-3)”) is selected twice (the “<multiple>” flag has been set) – and as a consequence <MM_hasUidField>1</MM_hasUidField> is set as well. In fact this configuration is sharing the MM table with another field (see the previous example) so the configuration
<MM_match_fields>
<ident>table_one_flex</ident>
</MM_match_fields>
makes sure all MM relations for this flexform field is marked with the string “table_one_flex”.
In the database the entry looks like:
(The first two entries belong to that other field, see previous example).
Of course you can specify a dedicated join table to the flexform instead of sharing it.
What will not work in flexforms is if you put MM relation fields in elements that can get repeated, like in sections:
Here I have added three sections and tried to add entries to each. However, when saved the two last entries are loaded for all of them. The result of the save was:
The reason is that the fields all use the same uid (that of the record) to find the MM records. This could work when MM fields were used outside sections of flexform fields which could only occur one time per record, but here it’s not possible.
Data format of “select” elements
Since the “select” element allows to store references to multiple elements we might want to look at how these references are stored internally. The principle is the same as with the “group” type (see below).