Platinum sponsors
Core Documentation
The "ctrl" section contains properties for the table in general.
These properties are basically divided into two main categories:
properties which affect how the table is displayed and handled in the backend interface . This includes which icon, what name, which columns contains the title value, which column defines the type value etc.
properties which determines how it is processed by the system (TCE).This includes publishing control, "deleted" flag, if the table can only be edited by admin-users, may only exist in the tree root etc.
Key | Datatype | Description | Scope |
|---|---|---|---|
title | string (LS) | Contains the system name of the table. Is used for display in the backend. For instance the "tt_content" table is of course named "tt_content" technically. However in the backend display it will be shown as "Pagecontent" when the backend language is english. When another language is chosen, like Danish, then the label "Sideindhold" is shown instead. This value is managed by the "title" value. You can insert plain text values, you can also add values for many languages by the obsolete concept of "language-splitting" (where you separate each language label by a vertical bar, "|") but please don't! In modern times it is always recommended to put the label values into an external file/array (local_lang files) and let the "title" field contain a reference to that value. See the example below. You should also have a look at the localization section in "Inside TYPO3" Example: $TCA['static_template'] = Array ( 'ctrl' => Array ( 'label' => 'title', 'tstamp' => 'tstamp', 'title' => 'LLL:EXT:cms/locallang_tca.php:static_template', In the above example the "LLL:" prefix tells the system to look up a label from the localization engine. The next prefix "EXT:cms" will look for the data source in the extension with the key "cms". In that extension the file "locallang_tca.php" will contain a $LOCAL_LANG array inside of which the label key "static_template" should contain the value, one for each language TYPO3 offers. | Display |
label | string (fieldname) | Required! Points to the fieldname of the table which should be used as the "title" when the record is displayed in the system. | Display |
label_alt | string | Commalist of fieldnames, which are holding alternative values to the value from the field pointed to by "label" (see above) if that value is empty. May not be used consistently in the system, but should apply in most cases. Example: $TCA['tt_content'] = Array ( 'ctrl' => Array ( 'label' => 'header', 'label_alt' => 'subheader,bodytext', See t3lib_BEfunc::getRecordTitle() Also see "label_alt_force" | Display |
label_alt_force | boolean | If set, then the "label_alt" fields are always shown in the title separated by comma. See t3lib_BEfunc::getRecordTitle() | Display |
type | string (fieldname) | Fieldname, which defines the "record type". The value of this field determines which one of the 'types' configurations are used for displaying the fields in the TCEforms. It will probably also affect how the record is used in the context where it belongs. The most widely known usage of this feature is the Content Elements where the "Type:" selector is defined as the "type" field and when you change that selector you will also get another rendering of the form:
It is also used by the "doktype" field in the "pages" table. Example: Here we will create an imaginary example to explain what the "type" property does. Imagine a table with four user editable fields:
We want the form in the backend to display only the fields "title" and "description" when the "displaytype" selector has the value "1" ("Regular display"). When the selector is set to value "2" ("Regular display + link") we want the form to show all three fields. This is done by first setting the "displaytype" field as the type field in [ctrl] section: script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'type' => 'displaytype',Then in the "types" section of the $TCA configuration (see later) we set up the fields for display: 'types' => Array ( '1' => Array('showitem' => 'title, description'), '2' => Array('showitem' => 'title, description, title_link') ) The backend will select the "showitem" list for ...["types"][2] when the field "displaytype" contains the value two. And likewise when "displaytype" is 1, then the first list is used to display fields in the backend. | Display / Proc. |
hideTable | boolean | Hide this table in record listings. | |
requestUpdate | string (list of fieldnames) | This is a list of fields additional to the type field which will request the user to update the form due to some content having change and which til affect the layout. For example you could add any of the subtype fields you might have configured. | Proc. |
iconfile | string | Pointing to the icon file to use for the table. Icons should be dimensioned 18x16 pixels (the last two right-most pixel columns in the width should preferably be empty) and of the GIF or PNG file type. The value of the option can be any of these:
Example: How to assign an icon from an extension In the ext_tables.php files of your extension you normally define the "ctrl" section of the tables you have added to the system. Here you can add a local icon from the extension like this: $TCA["tx_mininews_news"] = Array ( "ctrl" => Array ( "iconfile" => t3lib_extMgm::extRelPath($_EXTKEY)."icon_tx_mininews_news.gif", | Display |
typeicon_column | string (fieldname) | Fieldname, whose value decides alternative icons for the table (The default icon is the one defined with the 'iconfile' value.) An icon in the 'typeicons' array may override the default icon if an entry is found for the key having the value of the field pointed to by "typeicon_column" (this feature). Notice: These options ("typoicon_column" and "typeicons") does not work for the pages-table, which is configured by the PAGES_TYPES array. Related "typeicons" This feature is used by for instance the "tt_content" table (Content Elements) where each type of content element has its own icon. Example: See "typeicons" | Display |
typeicons | array | (See "typeicon_column") Example of configuration (from the "tt_content" table): 'typeicon_column' => 'CType', 'typeicons' => Array ( 'header' => 'tt_content_header.gif', 'textpic' => 'tt_content_textpic.gif', 'image' => 'tt_content_image.gif', 'bullets' => 'tt_content_bullets.gif', 'table' => 'tt_content_table.gif', 'splash' => 'tt_content_news.gif', 'uploads' => 'tt_content_uploads.gif', 'multimedia' => 'tt_content_mm.gif', 'menu' => 'tt_content_menu.gif', 'list' => 'tt_content_list.gif', 'mailform' => 'tt_content_form.gif', 'search' => 'tt_content_search.gif', 'login' => 'tt_content_login.gif', 'shortcut' => 'tt_content_shortcut.gif', 'script' => 'tt_content_script.gif', 'div' => 'tt_content_div.gif', 'html' => 'tt_content_html.gif' ), | Display |
thumbnail | string (fieldname) | Fieldname, which contains the value for any thumbnails of the records . This could be a type of the "group" type containing a list of file names. Example: For the "tt_content" table this option points to the field "image" which contains the list of images that can be attached to the content element: script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'thumbnail' => 'image',The effect of the field can be see in listings in eg. the "List" module:
(You might have to enable "Show Thumbnails by default" in the Setup module first to see this display). | Display |
selicon_field | string (fieldname) | Fieldname, which contains the thumbnail image used to represent the record visually whereever it is shown in TCEforms as a foreign reference selectable from a selectorbox. Only images of the ordinary webformat, like gif,png,jpeg,jpg, is allowed. No scaling is done. You should consider this a feature where you can attach an "icon" to a record which is typically selected as a reference in other records. For example a "category". In such a case this field points out the icon image which will then be shown. This feature can thus enrich the visual experience of selecting the relation in other forms. The feature is seldomly used. Related: "selicon_field_path" | Display |
selicon_field_path | string | The path prefix of the value from 'selicon_field'. This must be similar to the upload_path of that field (and thereby redundant). | Display |
sortby | string (fieldname) | Fieldname, which is used to manage the order the records. The field will contain an integer value which positions it at the correct position between other records from the same table on the current page. NOTICE: The field should not be editable by the user since the TCE will manage the content automatically in order to manage the order of records. This feature is used by eg. the "pages" table and "tt_content" table (Content Elements) in order to control the manually determined listing order of those records. Typically the fieldname "sorting" is dedicated to this feature. Related: "default_sortby" | Display/Proc. |
default_sortby | string | If a fieldname for "sortby" is defined, then this is ignored. Otherwise this is used as the 'ORDER BY' statement to sort the records in the table when listed in TBE. A few examples: "default_sortby" => "ORDER BY title", "default_sortby" => "ORDER BY tstamp DESC", "default_sortby" => "ORDER BY parent,crdate DESC", | Display |
mainpalette | comma seperated list of integers (pointing to multiple palette keys) | Points to the palette-number(s) that should always be shown in the bottom of the TCEform. Example: For many records you can find the last section of the form looking something like this:
This box displays the fields from the "main palette". In the case above (table: "tt_content") the main palette is "1" configured like this in $TCA for "tt_content": 'palettes' => Array ( '1' => Array('showitem' => 'hidden,starttime,endtime,fe_group'),And in the "ctrl" section it looks like this: 'mainpalette' => '1', | Display |
canNotCollapse | boolean | If set, then the "Show secondary options" check box will not affect this table - no matter what, all fields and palettes are displayed in the main form at all times. Just like if the check box was always set.
| Display |
tstamp | string (fieldname) | Fieldname, which is automatically updated to the current timestamp (UNIX-time in seconds) each time the record is updated/saved in the system. Typically the field name "tstamp" is used for the time stamp value. Example: This example shows the configuration for the "fe_users" table and how the tstamp, crdate and cruser_id fields have been configured: $TCA['fe_users'] = Array ( 'ctrl' => Array ( 'label' => 'username', 'tstamp' => 'tstamp', 'crdate' => 'crdate', 'cruser_id' => 'cruser_id', | Proc. |
crdate | string (fieldname) | Fieldname, which is automatically set to the current timestamp when the record is created. Is never modified again. Typically the field name "crdate" is used for the time stamp value. | Proc. |
cruser_id | string (fieldname) | Fieldname, which is automatically set to the uid of the backend user (be_users) who originally created the record. Is never modified again. Typically the field name "cruser_id" is used for the time stamp value. | Proc. |
rootLevel | [0, 1, -1] | Determines where a record may exist in the page tree. There are three options depending on the value:
Notice: The setting for "rootLevel" is ignored for records in the "pages" table (they are hardcoded to be allowed anywhere, equal to a "-1" setting of rootLevel) | Proc. / Display |
readOnly | boolean | Records may not be changed. This makes a table "static". In TYPO3 the most wellknown static table is "static_template" which contains pre-configured TypoScript code snippets. But you can also find a number of extensions which contains static table information like zip-codes, airport codes, country, currency codes etc. | Proc. / Display |
adminOnly | boolean | Records may be changed only by "admin"-users (having the "admin" flag set). Examples from the "cms" extension are the tables "sys_template" and "static_template" (the latter is also "readOnly"). | Proc. / Display |
editlock | string (fieldname) | Fieldname, which – if set – will prevent all editing of the record for non-admin users. The field should be configured as a checkbox type. Non-admins could be allowed to edit the checkbox but if they set it, they will effectively lock the record so they cannot edit it again – and they need an Admin-user to remove the lock. If this feature is used on the pages table it will also prevent editing of records on that page (except other pages)! Also, no new records (including pages) can be created on the page. This flag is cleared when a new copy or version of the record is created. | Proc / Display |
origUid | string (fieldname) | Fieldname, which will contain the UID of the original record in case a record is created as a copy or new version of another record. Is used when new versions are created from elements and enables the backend to display a visual comparison between a new version and its original. | Proc |
delete | string (fieldname) | Fieldname, which indicates if a record is considered deleted or not. If this feature is used, then records are not really deleted, but just marked 'deleted' by setting the value of the fieldname to "1". And in turn the whole system must strictly respect the record as deleted. This means that any SQL query must exclude records where this field is true. This is a very common feature. | Proc. / Display |
enablecolumns | array | Specifies which publishing control features are automatically implemented for the table. This includes that records can be "disabled" or "hidden", have a starting and/or ending time and be access controlled so only a certain front end user group can access them In the frontend libraries the enableFields() function automatically detects which of these fields are configured for a table and returns the proper WHERE clause SQL code for creating select queries. There are the keys in the array you can use. Each of the values must be a field name in the table which should be used for the feature: "disabled": defining hidden-field of record "starttime": defining starttime-field of record "endtime": defining endtime-field of record "fe_group": defining fe_group-field of record Notice: In general these fields does not affect the access or display in the backend! They are primarily related to the frontend. However the icon of records having these features enabled will normally change as these examples show: [INSERT IMAGE] See also the "delete" feature which is related, but is active for both frontend and backend. Example: Typically the "enablecolumns" could be configured like this (here for the "tt_content" table): 'enablecolumns' => Array ( 'disabled' => 'hidden', 'starttime' => 'starttime', 'endtime' => 'endtime', 'fe_group' => 'fe_group', ), | Proc. / Display |
hideAtCopy | boolean | If set, and the "disabled" field from "enablecolumns" (see below) is specified, then records will be disabled/hidden when they are copied. | Proc. |
prependAtCopy | string (LS) | This string will be prepended the records title field when the record is inserted on the same PID as the original record (thus you can distinguish them). Usually the value is something like " (copy %s)" which tells that it was a copy that was just inserted (The token "%s" will take the copy number). | Proc. |
copyAfterDuplFields | string (list of fieldnames) | The fields in this list will automatically have the value of the same field from the 'previous' record transferred when they are copied or moved to the position after another record from same table. Example: script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'copyAfterDuplFields' => 'colPos,sys_language_uid', | Proc. |
setToDefaultOnCopy | string (list of fieldnames) | These fields are restored to the default value of the record when they are copied. Example: $TCA["sys_action"] = Array ( "ctrl" => Array ( "setToDefaultOnCopy" => "assign_to_groups", | Proc. |
useColumnsForDefaultValues | string (list of fieldnames) | When a new record is created, this defines the fields from the 'previous' record that should be used as default values. Example: $TCA['sys_filemounts'] = Array ( 'ctrl' => Array ( 'useColumnsForDefaultValues' => 'path,base', | Proc. |
shadowColumnsForNewPlaceholders | string (list of fieldnames) | When a new element is created in a draft workspace a placeholder element is created in the Live workspace. Certain values of the draft element can be necessary to transfer to the live element, such as sys_language_uid typically. This list of fields will define which values are "shadowed" to the Live record. All fields listed for this option must be defined in $TCA[<table>]"[columns"] as well. Further, fields which are listed in transOrigPointerField, languageField, label and type are automatically added to this list of fields and do not have to re-appear in the list. Example: $TCA['tt_content'] = Array ( 'ctrl' => Array ( 'shadowColumnsForNewPlaceholders' => 'sys_language_uid,l18n_parent,colPos', | |
is_static | boolean | This marks a table to be "static". A "static table" means that it should not be updated for individual databases because it is meant to be centrally updated and distributed. For instance static tables could contain country-codes used in many systems. The foremost property of a static table is that the uid's used are the SAME across systems. Import/Export of records expect static records to be common for two systems. Example (also including the features "rootLevel", "readOnly" and "adminOnly" above): $TCA['static_template'] = Array ( 'ctrl' => Array ( 'label' => 'title', 'tstamp' => 'tstamp', 'title' => 'LLL:EXT:cms/locallang_tca.php:static_template', 'readOnly' => 1, // Prevents the table from being altered 'adminOnly' => 1, // Only admin, if any 'rootLevel' => 1, 'is_static' => 1, | Used by import/export |
fe_cruser_id | string (fieldname) | Fieldname, which is used to store the uid of a front-end user if he is created the record through fe_adminLib | FE |
fe_crgroup_id | string (fieldname) | Fieldname, which is used for storing the uid of a fe_group record, where the members of that record are allowed to edit through fe_adminLib . | FE |
fe_admin_lock | string (fieldname) | Fieldname, which points to the fieldname which - as a boolean - will prevent any editing by the fe_adminLib, if set. Say if the "fe_cruser_id" field matches the current fe_user normally the field is editable. But with this option, you could make a check-box in the backend that would lock this option. | FE |
languageField | string (fieldname) | Localization access control. Fieldname, which contains the pointer to the language of the records content. Languages for a record is defined by an integer pointing to a “sys_language” record (found in the page tree root). Backend users can be limited to have edit access for only certain of these languages and if this option is set, edit access for languages will be enforced for this table. Pointers to a language has this value range: -1 : (ALL) The record does not represent any specific language. Localization access control is never carried out for such a record. Typically this is used if the record has content (such as flexforms in itself containing the localization or a plugin with general purpose) which internally contain localized values – hence making such a flag for the container record futile. 0 : The default language of the system. Localization access control applies. Values > 0 : Points to a uid of a sys_language record representing a possible language for translation. Localization access control applies. The fieldname pointed to should be a single value selector box (maxitems <=1) saving its value into an integer field in the database. | Proc / Display |
transOrigPointerField | string (fieldname) | Fieldname, which contains the uid of the record which this record is a translation of. If this value is found being set together with “languageField” then TCEforms will show the default translation value under the fields in the main form. This is very neat if translators are to see what they are translating of course... Must be configured in “columns”, at least as a passthrough type. | Proc / Display |
transOrigPointerTable | string (tablename) | Optional table name for the table where record uids in “transOrigPointerField” comes from. This is needed in very rare applications where the original language is found in another table of the database. In such cases the field names must match between the tables. An example of this is the pages table and “pages_language_overlay”. WARNING: This is unsupported almost everywhere except for the “pages” table for which it was originally invented. | Proc / Display |
transOrigDiffSourceField | string (fieldname) | Fieldname which will be updated with the value of the original language record whenever the translation record is updated. This information is later used to compare the current values of the default record with those stored in this field and if they differ there will be a display in the form of the difference visually. This is a big help for translators so they can quickly grasp the changes that happened to the default language text. The field type in the database should be a large text field (clob/blob). You don't have to configure this field in the “columns” section of TCA, but if you do, select the “passthrough” type. That will enable that the undo function also works on this field. | Proc / Display |
transForeignTable | string (tablename) | Points to the table which holds translations of the records in this table. This feature must be used in pair with transOrigPointerTable but on separate tables of course: transForeignTable must point to the tablename for which transOrigPointerTable is set to point to the table which has transForeignTable set. Example: The table “pages” has “transForeignTable“ set to “pages_language_overlay” because it holds the translations for pages. The table “pages_language_overlay” has “transOrigPointerTable” set to “pages”. WARNING: This is still highly unsupported for all other tables than the “pages” table. If this is to work well for any table you wish to configure, some more work needs to get done! | |
versioningWS | boolean / keyword | If set, versioning is enabled for this table. Versioning in TYPO3 is based on this scheme: [Online version, pid>=0] 1- * [Offline versions, pid=-1] Offline versions are identified by having a pid value = -1 and they refer to their online version by the field “t3ver_oid”. In the backend “Offline” is labeled “Draft” while “Online” is labeled “Live”. In order for versioning to work on a table there are certain requirements; Tables supporting versioning must have these fields:
SQL definitions: t3ver_oid int(11) DEFAULT '0' NOT NULL, t3ver_id int(11) DEFAULT '0' NOT NULL, t3ver_wsid int(11) DEFAULT '0' NOT NULL, t3ver_label varchar(30) DEFAULT '' NOT NULL, t3ver_state tinyint(4) DEFAULT '0' NOT NULL, t3ver_stage tinyint(4) DEFAULT '0' NOT NULL, t3ver_count int(11) DEFAULT '0' NOT NULL, t3ver_tstamp int(11) DEFAULT '0' NOT NULL, Special “t3ver_swapmode” field for pages When pages are versioned it is an option whether content and even the branch of the page is versioned. This is determined by the parameter “treeLevels” set when the page is versioned. “-1” means swap only record, 0 means record and content and >0 means full branch. When the version is later published the swapping will happen accordingly. | Proc. |
versioning_followPages | boolean | (Only for other tables than “pages”) If set, content from this table will get copied along when a new version of a page is created. Tracking Originals It is highly recommended to use the “origUid” feature for tables whose records are copied with pages that are versioned with content or subtree since this will enable the possibility of content comparison between current and future versions. | Proc. |
versioning | [OBSOLETE] | In version 3.7 and 3.8 this was used to activate versioning for a table. However large changes in the API made it easier to simply disable this feature and introduce “versioningWS”. Migration: The migration is very easy: Simply set “versioningWS” instead of “versioning” for your table AND upgrade the SQL fields as defined for “versioningWS”! | |
dividers2tabs | boolean | If set, all “--div--” fieldnames in the types configuration will be interpreted as starting a new tab in a tab-menu for the record. The second part after “--div--” will be the title of the tab then. If you place a “--div--” field as the very first element in the types configuration it will just be used to set the title of the first tab (which is by default “General”). If you like to place the main palette on its own tab in the end, simply add “--div--” as the very last field. Example: A types configuration for a table looks like this: "types" => Array ( "0" => Array("showitem" => "--div--;Basis valg, hidden;;1;;1-1-1, title;;;;2-2-2, type;;;;3-3-3, template, --div--;Frekvens, freq, time1, time2, time3, time4, time5, time6, time7, time8, --div--;Details, sourceurl, inputparser, position, dailysubpage, newpageishidden, notify_on_creation_email, logimportsonly") ), This will render a tab menu for the record where the fields are distributed on the various pads:
Here another tab is activated and another part of the form is shown:
| |
dynamicConfigFile | string | Reference to the complete $TCA entry content. Filename of the PHP file which contains the full configuration of the table in $TCA. The [ctrl] part (and [feInterface] if used) are always mandatory, but the rest may be placed in such a file in order to limit the amount of memory consumed by the $TCA array (when eg. the columns definitions are not needed). The format of the value is as follows:
Example: This is the typical configuration in an extension where the file named "tbl.php" contains all configuration for the "columns", "types" and "palettes": $TCA["tx_mininews_news"] = Array ( "ctrl" => Array ( "dynamicConfigFile" => t3lib_extMgm::extPath($_EXTKEY)."tca.php", ), "feInterface" => Array ( "fe_admin_fieldList" => "hidden, starttime, front_page", ) ); In the file "tca.php" in the extension you will find this PHP code which completes the $TCA entry for the table: <?php if (!defined ("TYPO3_MODE")) die ("Access denied."); $TCA["tx_mininews_news"] = Array ( "ctrl" => $TCA["tx_mininews_news"]["ctrl"], "interface" => Array ( "showRecordFieldList" => "hidden,starttime,front_page" ), "feInterface" => $TCA["tx_mininews_news"]["feInterface"], "columns" => Array ( "hidden" => Array ( "exclude" => 1, "label" => $LANG_GENERAL_LABELS["hidden"], "config" => Array ( "type" => "check", "default" => "0" ) ), ... etc | API |
EXT[extension_key] | array | User defined content for extensions. You can use this as you like. Lets say you have an extension with the key "myext", then you have the right to define properties for: ...['ctrl']['EXT']['myext'] = ... (whatever you define) | Ext. |
Here are a few examples of configurations of the control section.
1: $TCA['pages'] = Array (
2: 'ctrl' => Array (
3: 'label' => 'title',
4: 'tstamp' => 'tstamp',
5: 'sortby' => 'sorting',
6: 'title' => 'LLL:EXT:lang/locallang_tca.php:pages',
7: 'type' => 'doktype',
8: 'delete' => 'deleted',
9: 'crdate' => 'crdate',
10: 'hideAtCopy' => 1,
11: 'prependAtCopy' => 'LLL:EXT:lang/locallang_general.php:LGL.prependAtCopy',
12: 'cruser_id' => 'cruser_id',
13: 'useColumnsForDefaultValues' => 'doktype'
14: ),
The pages table has the configuration you see above (found in t3lib/stddb/tables.php). Here are a few notes:
Line 3: When pages are displayed in the backend you will see the content from the field named "title" shown as the title of the page record.
Line 5: This configures the field "sorting" as the field which determines the order in which pages are displayed within each branch of the page tree.
Line 6: The title for the pages table as shown in the backend (eg. "Pages" in english, "Sider" in danish etc...) is defined here to come from a "locallang" file.
Line 7: Defines which field will be the "type" field. This determines the set of fields shown in the edit forms in the backend.
Line 10: Defines that pages should be hidden when copied.
The tt_content table (Content Elements) looks like this in the "ctrl" section (sysext/cms/ext_tables.php):
1: // ******************************************************************
2: // This is the standard TypoScript content table, tt_content
3: // ******************************************************************
4: $TCA['tt_content'] = Array (
5: 'ctrl' => Array (
6: 'label' => 'header',
7: 'label_alt' => 'subheader,bodytext',
8: 'sortby' => 'sorting',
9: 'tstamp' => 'tstamp',
10: 'title' => 'LLL:EXT:cms/locallang_tca.php:tt_content',
11: 'delete' => 'deleted',
12: 'type' => 'CType',
13: 'prependAtCopy' => 'LLL:EXT:lang/locallang_general.php:LGL.prependAtCopy',
14: 'copyAfterDuplFields' => 'colPos,sys_language_uid',
15: 'useColumnsForDefaultValues' => 'colPos,sys_language_uid',
16: 'enablecolumns' => Array (
17: 'disabled' => 'hidden',
18: 'starttime' => 'starttime',
19: 'endtime' => 'endtime',
20: 'fe_group' => 'fe_group',
21: ),
22: 'typeicon_column' => 'CType',
23: 'typeicons' => Array (
24: 'header' => 'tt_content_header.gif',
25: 'textpic' => 'tt_content_textpic.gif',
26: 'image' => 'tt_content_image.gif',
27: 'bullets' => 'tt_content_bullets.gif',
28: 'table' => 'tt_content_table.gif',
29: 'splash' => 'tt_content_news.gif',
30: 'uploads' => 'tt_content_uploads.gif',
31: 'multimedia' => 'tt_content_mm.gif',
32: 'menu' => 'tt_content_menu.gif',
33: 'list' => 'tt_content_list.gif',
34: 'mailform' => 'tt_content_form.gif',
35: 'search' => 'tt_content_search.gif',
36: 'login' => 'tt_content_login.gif',
37: 'shortcut' => 'tt_content_shortcut.gif',
38: 'script' => 'tt_content_script.gif',
39: 'div' => 'tt_content_div.gif',
40: 'html' => 'tt_content_html.gif'
41: ),
42: 'mainpalette' => '1',
43: 'thumbnail' => 'image',
44: 'dynamicConfigFile' => t3lib_extMgm::extPath($_EXTKEY).'tbl_tt_content.php'
45: )
46: );
Line 7: Here additional fields are defined to be used if no content is found in the "header" field (defined in line 6)
Line 16-21: The "enablecolumns" section is extensive for this table since it is a front end related table. Typically they use the "enablecolumns" a lot.
Line 22-41: For each content element type a new icon is defined. This helps the users to easily recognize which type of content element they are looking at when they see the element in a list of records.
Line 43: The column "image" is used to fetch any thumbnails there are to show for the record.
Contains configuration for display and listing in various parts of the core backend:
Key | Datatype | Description |
|---|---|---|
showRecordFieldList | string (list of fieldnames) | Defines which fields are shown in the show-item dialog. Eg. 'doktype,title,alias,hidden,....' |
always_description | boolean | If set, the description/helpicons are always shown regardless of the configuration of the user. Works only in TCEforms and for tables loaded via t3lib_BEfunc::loadSingleTableDescription()
|
maxDBListItems | integer | Max number of items shown in the List module |
maxSingleDBListItems | integer | Max number of items shown in the List module, if this table is listed in Extended mode (listing only a single table) |
The "feInterface" section contains properties related to Front End Editing of the table, mostly related to the feAdmin_lib.
Is depricated in the sense that it will still exist, but will not be (and should not be) extended further.
Key | Datatype | Description |
|---|---|---|
editableRecordFields | string (list of fieldnames) | List of fields, example: '*name, *type, biography, filmography'. Used for front-end edit module created by Rene Fritz <r.fritz@colorcube.de> |
fe_admin_fieldList | string (list of fieldnames) | List of fields allowed for editing/creation with the fe_adminLib module, see media/scripts/fe_adminLib, example: 'pid,name,title,address' |
The "columns" section contains configuration for each table field (also called "column") which can be edited by the backend.
The configuration includes both properties for the display in the backend as well as the processing of the submitted data.
Each field can be configured as a certain "type" (eg. checkbox, selector, iinput field, text area, file or db-relation field, user defined etc.) and for each type a separate set of additional properties applies. These properties are clearly explained below for each type.
This table showns the keys of the ['columns'][fieldname] array:
Key | Datatype | Description | Scope |
|---|---|---|---|
label | string (LS) | Required! The name of the field as it is shown in the interface:
| Display |
exclude | boolean | If set, all backend users are prevented from editing the field unless they are members of a backend usergroup with this field added as an "Allowed Excludfield" (or "admin" user). | Proc. |
l10n_mode | string (keyword) | Localization mode. Only active if the ctrl-directive “languageField” is set. The main relevance is when a record is localized by an API call in tcemain that makes a copy of the default language record. You can think of this process as copying all fields from the source record, except if a special mode applies as defined below: Keywords are:
(Doesn't apply to flexform fields.) | Display / Proc. |
l10n_display | list of keywords | Localization display. see: l10n_mode This option can be used to define the language related field rendering. This has nothing to do with the processing of language overlays and data storage but the display of form fields. Keywords are:
| Display |
l10n_cat | string (keyword) | Localization category. Keywords: text,media When localization mode is set for a TCEforms, it must be either of these values. Only the fields that have l10n_cat set to the localization mode is show. Used to limit display so only most relevant fields are shown to translators. It doesn't prevent editing of other fields if records are edited outside localization mode, it merely works as a display condition. It is also used in localization export (pending at this moment). | Display |
config | array | Contains the actual configuration properties of the fields display and processing behaviour. The possibilities for this array depend on the value of the array key "type" within the array. Each valid value for "type" is shown below in a separate table. Notice: For all configuration types, the
| - |
displayCond | string | Contains a condition rule for whether to display the field or not. A rule is a string divided into several parts by ":" (colons). The first part is the rule-type and the subsequent parts will depend on the rule type. Currently these rule values can be used:
For FlexForm elements the fields are tags on same level. If <langChildren> is enabled, then the value of other fields on same level is taken from the same language. Example: This example will require the field named "tx_templavoila_ds" to be true, otherwise the field for which this rule is set will not be displayed: 'displayCond' => 'FIELD:tx_templavoila_ds:REQ:true', This example requires the extension "static_info_tables" to be loaded, otherwise the field is not displayed. (This is useful if the field makes a look-up on a table coming from another extension!) 'displayCond' => 'EXT:static_info_tables:LOADED:true', | Display |
defaultExtras | string | In the “types” configuration of a field you can specify on position 4 a string of "extra configuration". This string will be the default string of extra options for a field regardless of types configuration. For instance this can be used to create an RTE field without having to worry about special configuration in “types” config. This is also the way by which you can enable the RTE for FlexForm fields. Example value: richtext[cut|copy|paste|formatblock|textcolor|bold|italic|underline|left|center|right|orderedlist|unorderedlist|outdent|indent|link|table|image|line|chMode]:rte_transform[mode=ts_css|imgpath=uploads/tx_mininews/rte/] |
The type "input" generates an <input> field, possibly with additional features applied.
Key | Datatype | Description | Scope |
|---|---|---|---|
type | string | [Must be set to "input"] | Display / Proc. |
size | integer | Abstract value for the width of the <input> field. To set the input field to the full width of the form area, use the value 48. Default is 30. | Display |
max | integer | Value for the "maxlength" attribute of the <input> field. If the form element edits a varchar(40) field in the database you should also set this value to 40. | Display |
default | string | The default value | Display / Proc. |
eval | list of keywords | Configuration of field evaluation. Some of these evaluation keywords will trigger a JavaScript pre-evaluation in the form. Other evaluations will be performed in the backend. The eval-functions will be executed in the list-order. Keywords:
All the above evaluations (unless noted) are done by JavaScript with the functions found in the script t3lib/jsfunc.evalfield.js "(TCE)" means the evaluation is done in the TCE on the server. The class used for this is t3lib_TCEmain. Example: Setting the field to evaluate the input to a date returned to the database in UNIX-time (seconds) 'eval' => 'date', Trimming the value for white space before storing in the database (important for varchar fields!) 'eval' => 'trim', By this configuration the field will be stripped for any space characters, converted to lowercase, only accepted if filled in and on the server the value is required to be unique for all records from this table: 'eval' => 'nospace,lower,unique,required' User defined form evaluations: You can supply your own form evaluations in an extension by creating a class with two functions, one which returns the JavaScript code for client side validation called returnFieldJS() and one which does the server side validation called evaluateFieldValue(). The function evaluateFieldValue() has 3 arguments:
Example: class.tx_exampleextraevaluations_extraeval1.php: <?php class tx_exampleextraevaluations_extraeval1 {function returnFieldJS() {return ' return value + " [added by JS]"; '; } function evaluateFieldValue($value, $is_in, &$set) {return $value.' [added by PHP]'; } } ?> ext_localconf.php <?php // here we register "tx_exampleextraevaluations_extraeval1" $TYPO3_CONF_VARS['SC_OPTIONS']['tce']['formevals']['tx_exampleextraevaluations_extraeval1'] = 'EXT:example_extraevaluations/ class.tx_exampleextraevaluations_extraeval1.php'; ?> Feel free to download the example extension as a T3X file. | Display / Proc. |
is_in | string | If the evaluation type "is_in" (see above, under key "eval") is used for evaluation, then the characters in the input string should be found in this string as well. | Display / Proc. |
checkbox | string | If defined (even empty), a checkbox is placed before the input field. If a value other than the value of 'checkbox' (this value) appears in the input-field the checkbox is checked. Example: 'checkbox' => '123', If you set this value then entering "12345" in the field will render this:
But if you either uncheck the checkbox or just enter the value "123" you will an empty input field and no checkbox set - however the value of the field will be "123":
This feature is useful for date-fields for instance. In such cases the checkbox will allow people to quickly remove the date setting (equal to setting the date to zero which actually means 1-1 1970 or something like that). Example listing: script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'config' => Array ('type' => 'input', 'size' => '8', 'max' => '20', 'eval' => 'date', 'checkbox' => '0', 'default' => '0' ) Will create a field like this below. Checking the checkbox will insert the date of the current day. Unchecking the checkbox will just remove the value and silently sent a zero to the server (since the value of the key "checkbox" is set to "0").
| Display / Proc. |
range | array | An array which defines an integer range within which the value must be. Keys: "lower": Defines the lower integer value. "upper": Defines the upper integer value. You can specify both or only one of them. Notice: This feature is evaluated on the server only so any regulation of the value will have happend after saving the form. Example: Limits an integer to be within the range 10 to 1000: script_ended = 0; function jumpToUrl(URL) { document.location = URL; } 'eval' => 'int', 'range' => array('lower' => 10,'upper' => 1000), In this example the upper limit is set to the last day in year 2020 while the lowest possible value is set to the date of yesterday. script_ended = 0; function jumpToUrl(URL) { document.location = URL; } 'range' => Array ( 'upper' => mktime(0,0,0,12,31,2020), 'lower' => mktime(0,0,0,date('m')-1,date('d'),date('Y')) ) | Proc. |
wizards | array | [See section later for options] | Display |
Now follows some codelistings as examples:
This is the typical configuration for a date field, like "starttime":
script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'starttime' => Array ('exclude' => 1,
'label' => 'LLL:EXT:lang/locallang_general.php:LGL.starttime',
'config' => Array (
'type' => 'input',
'size' => '8',
'max' => '20',
'eval' => 'date',
'checkbox' => '0',
'default' => '0'
)
),
In this example the field is for entering a username (from "fe_users"). A number of requirements are imposed onto the field, namely that it must be unique within the page where the record is stored, must be in lowercase and without spaces in it:
script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'username' => Array ('label' => 'LLL:EXT:cms/locallang_tca.php:fe_users.username',
'config' => Array (
'type' => 'input',
'size' => '20',
'max' => '50',
'eval' => 'nospace,lower,uniqueInPid,required'
)
),
This is just a very typical configuration which sets the size and a character limit to the field. In addition the input value is trimmed for surrounding whitespace which is a very good idea when you enter values into varchar fields.
script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'name' => Array ('exclude' => 1,
'label' => 'LLL:EXT:lang/locallang_general.php:LGL.name',
'config' => Array (
'type' => 'input',
'size' => '40',
'eval' => 'trim',
'max' => '80'
)
),
Here the field is required to be filled in:
script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'title' => Array ('label' => 'LLL:EXT:cms/locallang_tca.php:fe_groups.title',
'config' => Array (
'type' => 'input',
'size' => '20',
'max' => '20',
'eval' => 'trim,required'
)
),
This field type generates a <textarea> field or inserts a RTE (Rich Text Editor).
Such a field looks like this:
Key | Datatype | Description | Scope |
|---|---|---|---|
type | string | [Must be set to "text"] | Display / Proc. |
cols | integer | Abstract value for the width of the <textarea> field. To set the textarea to the full width of the form area, use the value 48. Default is 30. | Display |
rows | integer | The number of rows in the textarea. May be corrected for harmonisation between browsers. Will also automatically be increased if the content in the field is found to be of a certain length, thus the field will automatically fit the content. Default is 5. Max value is 20. | Display |
wrap | ["off", "virtual"] | Determines the wrapping of the textarea field. There are two options: "virtual": (Default) The textarea will automatically wrap the lines like it would be expected for editing a text. "off": The textarea will not wrap the lines as you would expect when editing some kind of code. Notice: If the string "nowrap" is found among options in the fields extra configuration from the "types" listing this will override the setting here to "off". Example: This configuration will create a textarea useful for entry of code lines since it will not wrap the lines: "config" => Array ( "type" => "text", "cols" => "40", "rows" => "15", 'wrap' => 'off', ) | Display |
default | string | Default value | Display / Proc. |
wizards | array | [See section later for options] | Display |
Now follows some codelistings as examples:
This is the typical configuration for a textare field:
script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'message' => Array ('label' => 'LLL:EXT:sys_note/locallang_tca.php:sys_note.message',
'config' => Array (
'type' => 'text',
'cols' => '40',
'rows' => '15'
)
),
This type creates checkbox(es). Such elements might look like this:
You can also configure checkboxes to appear in an array:
You can have between 1 and 10 checkboxes and the field type in the database must be an integer. No matter how many checkboxes you have each check box will correspond to a single bit in the integer value. Even if there is only one checkbox (which in turn means that you should theoretically check the bit-0 of values from single-checkbox fields and not just whether it is true or false!).
Key | Datatype | Description | Scope |
|---|---|---|---|
type | string | [Must be set to "check"] | Display / Proc. |
items | array | If set, this array will create an array of checkboxes instead of just a single "on/off" checkbox. Notice: You can have a maximum of 10 checkboxes in such an array and each element is represented by a single bit in the integer value which ultimately goes into the database. In this array each entry is itself an array where the first entry is the label (LS) and the second entry is a blank value. The value sent to the database will be an integer where each bit represents the state of a checkbox in this array. Example: 'items' => Array ( Array('Green tomatoes', ''), Array('Red peppers', '')), | Display |
cols | integer | How many columns the checkbox array are shown in. Range is 1-10, 1 being default. (Makes sense only if the 'array' key is defining a checkbox array) | Display |
showIfRTE | boolean | If set, this field will show only if the RTE editor is enabled (which includes correct browserversion and user-rights altogether.) | Display |
default | integer | Setting the default value of the checkbox(es). Notice: Each bit corresponds to a check box (even if only one checkbox which maps to bit-0). | Display / Proc. |
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 |
Now follows some codelistings as examples:
A totally unfancy checkbox:
script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'personal' => Array ('label' => 'LLL:EXT:sys_note/locallang_tca.php:sys_note.personal',
'config' => Array (
'type' => 'check'
)
)
This is an example of a checkbox array with two checkboxes in it. The first checkbox will have bit-0 and the second bit-1. The default value is set to '3' which means that each checkbox will be enabled by default (since the value three contains both bit-0 and bit-1):
script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'sendOptions' => Array ('label' => 'LLL:EXT:direct_mail/locallang_tca.php:sys_dmail.sendOptions',
'config' => Array (
'type' => 'check',
'items' => Array (
Array('LLL:EXT:direct_mail/locallang_tca.php:sys_dmail.sendOptions.I.0', ''), Array('LLL:EXT:direct_mail/locallang_tca.php:sys_dmail.sendOptions.I.1', '')),
'default' => '3'
)
),
Radio buttons are seldom used, but sometimes they can be more attractive than their more popular sisters (selector boxes).
Here you see radio buttons in action for the "Filemounts" records:
Key | Datatype | Description | Scope |
|---|---|---|---|
type | string | [Must be set to "radio"] | Display / Proc. |
items | array | Required. An array of the values which can be selected. Each entry is in itself an array where the first entry is the title (LS) and the second entry is the value of the radiobutton. See example below. | Display |
default | mixed | Default value. | Display / Proc. |
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 |
An example of radio buttons configuration from "sys_filemounts" (see above):
script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'base' => Array ('label' => 'BASE',
'config' => Array (
'type' => 'radio',
'items' => Array (
Array('absolute (root) / ', 0), Array('relative ../fileadmin/', 1)),
'default' => 0
)
)
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 amoung 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.
Key | Datatype | Description | Scope |
|---|---|---|---|
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:
Example: A configuration could look like this: script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'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:
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:
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:
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:
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:
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:
| 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. |
Here follow some code listings as examples:
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.
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.
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)
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: ),
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.
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.
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).
The group element in TYPO3 makes it possible to create references to records from multiple tables in the system. This is especially useful (compared to the "select" type) when records are scattered over the page tree and requires the Element Browser to be selected. In this example, Content Element records are attached:
The "group" element It is also the element you can use to bind files to records in TYPO3. In this case image files:
One thing to notice about attaching files is that the files are actually moved into an internal file folder for TYPO3! It doesn't merely create a reference to the files original position!
Key | Datatype | Description | Scope |
|---|---|---|---|
type | string | [Must be set to "group"] | Display / Proc. |
internal_type | string | Required! Configures the internal type of the "group" type of element. There are two options for a value:
The default value is none of them - you must specify one of the values correctly! | Display / Proc. |
allowed | string (list of) | For the "file" internal type (Optional): A lowercase comma list of file extensions that are permitted. Eg. 'jpg,gif,txt'. Also see 'disallowed'. For the "db" internal type (Required!): A comma list of tables from $TCA. For example the value could be "pages,be_users". Value from these tables are always the 'uid' field. First table in list is understood as the default table, if a table-name is not prepended to the value. If the value is '*' then all tables are allowed (in this case you should set "prepend_tname" so all tables are prepended with their table name for sure). | Proc. / Display |
disallowed | string (list of) | [internal_type = file ONLY] Default value is '*' which means that anything file-extension which is not allowed is denied. If you set this value (to for example "php,php3") AND the "allowed" key is an empty string all extensions are permitted except ".php" and ".php3" files (works like the [BE][fileExtensions] config option). In other words:
| Proc. / Display |
MM | string (table name) | Defines MM relation table to use. Means that the relation to the files/db is done with a M-M relation through a third "join" table. A MM-table must have these four columns:
The fieldname of the config is not used for data-storage any more but rather it's set to the number of records in the relation on each update, so the field should be an integer. Sample SQL table definitions for MM relations look like: # # Example MM table for database relations # CREATE TABLE example_db_mm ( 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, KEY uid_local (uid_local), KEY uid_foreign (uid_foreign) ) TYPE=MyISAM; # # Example MM table for file attachments # CREATE TABLE example_files_mm ( uid_local int(11) DEFAULT '0' NOT NULL, uid_foreign varchar(60) DEFAULT '' NOT NULL, sorting int(11) DEFAULT '0' NOT NULL, KEY uid_local (uid_local), KEY uid_foreign (uid_foreign) ) TYPE=MyISAM; | Proc. |
MM_opposite_field | string (field name) | see ['columns'][fieldname]['config'] / TYPE: "select" => MM_opposite_field | Proc. |
MM_match_fields | array | see ['columns'][fieldname]['config'] / TYPE: "select" => MM_match_fields | |
MM_insert_fields | array | see ['columns'][fieldname]['config'] / TYPE: "select" => MM_insert_fields | |
MM_table_where | string (SQL WHERE) | see ['columns'][fieldname]['config'] / TYPE: "select" => MM_table_where | |
max_size | integer | [internal_type = file ONLY] Files: Maximum filesize allowed in KB | Proc. |
uploadfolder | string | [internal_type = file ONLY] Filefolder under PATH_site in which the files are stored. Example: 'uploads' or 'uploads/pictures' Notice: TYPO3 does NOT create a reference to the file in its original position! It makes a copy of the file into this folder and from that moment that file is not supposed to be manipulated from outside. Being in the upload folder means that files are understood as a part of the database content and should be managed by TYPO3 only. | Proc. |
prepend_tname | boolean | [internal_type = db ONLY] Will prepend the table name to the stored relations (so instead of storing "23" you will store eg. "tt_content_23"). | Proc. |
dontRemapTablesOnCopy | string (list of tables) | [internal_type = db ONLY] 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. | Proc. |
show_thumbs | boolean | Show thumbnails for the field in the TCEform | Display |
size | integer | Height of the selectorbox in TCEforms. | Display |
autoSizeMax | integer | 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. | Display |
selectedListStyle | string | If set, this will override the default style of element selector box (which is “width:200px”). | Display |
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 / Proc? |
wizards | array | [See section later for options] | Display |
Here follow some code listings as examples:
In this example up to 200 references to Content Elements can be made:
1: 'records' => Array (
2: 'label' => 'LLL:EXT:cms/locallang_ttc.php:records',
3: 'config' => Array (
4: 'type' => 'group',
5: 'internal_type' => 'db',
6: 'allowed' => 'tt_content',
7: 'size' => '5',
8: 'maxitems' => '200',
9: 'minitems' => '0',
10: 'show_thumbs' => '1'
11: )
12: ),
In line 5 it is configured that the internal type of the group field is "db" and then it follows that the allowed tables you can select from is "tt_content" (Content Elements table). This could be a list of tables which means you can mix references as you like!
Line 8 defines that there can be only 200 references and line 10 shows that they should be listed with their icons to the right of the selector box list.
In this case it wouldn't have made sense to use a "select" type field since the situation implies that records might be found all over the system in a table which could potentially carry thousands of entries. In such a case the right thing to do is to use the "group" field so you have the Element Browser available for selector of the records.
You will often see "group" type fields used when a reference to another page is required. This makes sense since pages can hardly be presented effectively in a big selector box and thus the Element Browser that follows the "group" type fields is useful. An example is the "General Record Storage page" reference:
The configuration looks like:
1: 'storage_pid' => Array (
2: 'exclude' => 1,
3: 'label' => 'LLL:EXT:lang/locallang_tca.php:storage_pid',
4: 'config' => Array (
5: 'type' => 'group',
6: 'internal_type' => 'db',
7: 'allowed' => 'pages',
8: 'size' => '1',
9: 'maxitems' => '1',
10: 'minitems' => '0',
11: 'show_thumbs' => '1'
12: )
13: ),
Notice how "maxitems" in line 9 is used to enforce that only one relation is created despite the ability of the "group" type field to create multiple references.
When you want to attach files to a database record it is done by the group field like this:
Notice how the same image has apparently been added twice - or at least the filename was the same ("DSC_7102_background.jpg"). In the second case the name has been made unique by appending "_01" before the extension. This happens because all files attached to records through the group type are copied to a location defined by the "uploadfolder" setting in the configuration (see line 8 below). Therefore, having two files with identical names means one of them must be renamed automatically.
1: 'image' => Array (
2: 'label' => 'LLL:EXT:lang/locallang_general.php:LGL.images',
3: 'config' => Array (
4: 'type' => 'group',
5: 'internal_type' => 'file',
6: 'allowed' => $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext'],
7: 'max_size' => '1000',
8: 'uploadfolder' => 'uploads/pics',
9: 'show_thumbs' => '1',
10: 'size' => '3',
11: 'maxitems' => '200',
12: 'minitems' => '0',
13: 'autoSizeMax' => 40,
14: )
15: ),
Notice how line 5 defines the "group" type to contain files.
In line 6 the list of allowed file extensions are defined (here, taking the default list of image types for TYPO3).
Line 7 defines the maximum kb size of files allowed.
Line 8 defines the storage folder in the filesystem where the files are copied to when attached to the record. The path is relative to the PATH_site of TYPO3, one directory below PATH_typo3
Since the "group" element allows to store references to multiple elements we might want to look at how these references are stored internally.
Storage methods
There are two main methods for this:
Stored in a comma list
Stored with a join table (MM relation)
The default and most wide spread method is the comma list.
Reserved tokens
In the comma list the token "," is used to separate the values. In addition the pipe sign "|" is used to separate value from label value when delivered to the interface. Therefore these tokens are not allowed in reference values, not even if the MM method is used.
The "Comma list" method (default)
When storing references as a comma list the values are simply stored one after another, separated by a comma in between (with no space around!). The database field type is normally a varchar, text or blob field in order to handle this.
From the examples above the four Content Elements will be stored as "26,45,49,1" which is the UID values of the records. The images will be stored as their filenames in a list like "DSC_7102_background.jpg,DSC_7181.jpg,DSC_7102_background_01.jpg".
Since "db" references can be stored for multiple tables the rule is that uid numbers without a table name prefixed are implicitly from the first table in the allowed table list! Thus the list "26,45,49,1" is implicitly understood as "tt_content_26,tt_content_45,tt_content_49,tt_content_1". That would be equally good for storage, but by default the "default" table name is not prefixed in the stored string. As an example, lets say you wanted a relation to a Content Element and a Page in the same list. That would look like "tt_content_26,pages_123" or alternatively "26,pages_123" where "26" implicitly points to a "tt_content" record given that the list of allowed tables were "tt_content,pages".
The "MM" method
Using the MM method you have to create a new database table which you configure with the key "MM". The table must contain a field, "uid_local" which contains the reference to the uid of the record that contains the list of elements (the one you are editing). The "uid_foreign" field contains the uid of the reference record you are referring to. In addition a "tablename" and "sorting" field exists if there are references to more than one table.
Lets take the examples from before and see how they would be stored in an MM table:
uid_local | uid_foreign | tablename | sorting |
|---|---|---|---|
[uid of the record you are editing] | 26 | tt_content | 1 |
[uid of the record you are editing] | 45 | tt_content | 2 |
[uid of the record you are editing] | 49 | tt_content | 3 |
[uid of the record you are editing] | 1 | tt_content | 4 |
Or for "tt_content_26,pages_123":
uid_local | uid_foreign | tablename | sorting |
|---|---|---|---|
[uid of the record you are editing] | 26 | tt_content | 1 |
[uid of the record you are editing] | 123 | pages | 2 |
Or for "DSC_7102_background.jpg,DSC_7181.jpg,DSC_7102_background_01.jpg":
uid_local | uid_foreign | tablename | sorting |
|---|---|---|---|
[uid of the record you are editing] | DSC_7102_background.jpg | N/A | 1 |
[uid of the record you are editing] | DSC_7181.jpg | N/A | 2 |
[uid of the record you are editing] | DSC_7102_background_01.jpg | N/A | 3 |
API for getting the reference list
In t3lib/ the class "t3lib_loaddbgroup" is designed to transform the stored reference list values into an array where all uids are paired with the right table name. Also, this class will automatically retrieve the list of MM relations. In other words, it provides an API for getting the references from "group" elements into a PHP array regardless of storage method.
Passing the list of references to TCEforms
Regardless of storage method, the reference list has to be "enriched" with proper title values when given to TCEforms for rendering. In particular this is important for database records. Passing the list "26,45,49,1" will not give TCEforms a chance to render the titles of the records.
The t3lib/ class "t3lib_transferdata" is doing such transformations (among other things) and this is how the transformation happens:
Int. type: | In Database: | When given to TCEforms: |
|---|---|---|
"db" | 26,45,49,1 | tt_content_26|%20adfs%20asdf%20asdf%20,tt_content_45|This%20is%20a%20test%20%28copy%203%29,tt_content_49|%5B...%5D,tt_content_1|%5B...%5D |
"file" | DSC_7102_background.jpg,DSC_7181.jpg,DSC_7102_background_01.jpg | DSC_7102_background.jpg|DSC_7102_background.jpg,DSC_7181.jpg|DSC_7181.jpg,DSC_7102_background_01.jpg|DSC_7102_background_01.jpg |
The syntax is:
[ref. value]|[ref. label rawurlencoded],[ref. value]|[ref. label rawurlencoded],....
Values are transferred back to the database as a comma separated list of values without the labels but if labels are in the value they are automatically removed.
Alternatively you can also submit each value as an item in an array; TCEmain will detect an array of values and implode it internally to a comma list. (This is used for the "select" type, in renderMode "singlebox" and "checkbox").
Managing file references
When a new file is attached to a record the TCE will detect the new file based on whether it has a path prefixed or not. New files are copied into the upload folder that has been configured and the final value list going into the database will contain the new filename of the copy.
If images are removed from the list that is detected by simply comparing the original file list with the one submitted. Any files not listed anymore are deleted.
Examples:
Current DB value: | Submitted data from TCEforms | New DB value: | Processing done |
|---|---|---|---|
first.jpg,second.jpg | first.jpg,/www/typo3/fileadmin/newfile.jpg,second.jpg | first.jpg,newfile_01.jpg,second.jpg | /www/typo3/fileadmin/newfile.jpg was copied to "/uploads/[some-dir]/newfile_01.jpg". The filename was appended with "_01" because another file with the name "newfile.jpg" already existed in the location. |
first.jpg,second.jpg | first.jpg | first.jpg | "/uploads/[some-dir]/second.jpg" was deleted from the location. |
This type will just show the value of the field in the backend. The field is not editable.
Key | Datatype | Description |
|---|---|---|
type | string | [Must be set to "" (blank string!)] |
pass_content | boolean | If set, then content from the field is directly outputted in the <div> section. Otherwise the content will be passed through htmlspecialchars() and possibly nl2br() if there is configuration for rows. Be careful to set this flag since it allows HTML from the field to be outputted on the page, thereby creating the possibility of XSS security holes. |
rows | integer | If this value is greater than 1 the display of the non-editable content will be shown in a <div> area trying to simulate the rows/columns known from a "text" type element. |
cols | integer | See "rows" and "size" |
fixedRows | boolean | If this is set the <div> element will not automatically try to fit the content length but rather respect the size selected by the value of the "rows" key. |
size | integer | If rows is less than one, the "cols" value is used to set the width of the field and if "cols" is not found, then "size" is used to set the width. The measurements corresponds to those of "input" and "text" type fields. |
Can be saved/updated through TCE but the value is not evaluated in any way and the field has no rendering in the TCEforms.
You can use this to send values directly to the database fields without any automatic evaluation. But still the update gets logged and the history/undo function will work with such values.
Since there is no rendering mode for this field type it is specifically fitted for direct API usage with the TCEmain class.
Key | Datatype | Description |
|---|---|---|
type | string | [Must be set to "passthrough"] |
Now follows a codelisting as example:
This field is found in a number of table, eg. the "pages" table. It is apparently used by the extension "impexp" to store some information.
script_ended = 0; function jumpToUrl(URL) { document.location = URL; } 'tx_impexp_origuid' => Array('config'=>array('type'=>'passthrough')),
In this example the extension "direct_mail" is adding some fields to the "tt_address" table but the fields are not editable through TCEforms, just able to manipulate through TCE directly.
script_ended = 0; function jumpToUrl(URL) { document.location = URL; } // tt_address modified
t3lib_div::loadTCA('tt_address');
t3lib_extMgm::addTCAcolumns('tt_address',array(
'module_sys_dmail_category' => Array('config'=>array('type'=>'passthrough')),
'module_sys_dmail_html' => Array('config'=>array('type'=>'passthrough'))
));
Allows you to render a whole form field by a user function or class method.
Key | Datatype | Description |
|---|---|---|
type | string | [Must be set to "user"] |
userFunc | string | Function or method reference. If you want to call a function, just enter the function name. The function name must be prefixed "user_" or "tx_". If you want to call a method in a class, enter "[classname]->[methodname]". The class name must be prefixed "user_" or "tx_". Two arguments will be passed to the function/method: The first argument is an array (passed by reference) which contains the current information about the current field being rendered. The second argument is a reference to the parent object (an instance of the t3lib_TCEforms class). Notice: You must include the class manually on beforehand! |
noTableWrapping | boolean | If set, then the output from the user function will not be wrapped in the usual table - you will have to do that yourself. |
Now follows a codelisting as example:
This field is rended by custom PHP code:
The configuration in TCA is as simple as this:
1: 'TEST02' => Array (
2: 'label' => 'TEST02: ',
3: 'config' => Array (
4: 'type' => 'user',
5: 'userFunc' => 'user_class->user_TCAform_test',
6: )
7: ),
In addition you have to make sure the class "user_class" is included and has the method "user_TCAform_test". This the example above it looked like this:
1: class user_class {
2: function user_TCAform_test($PA, $fobj) {
3: return '
4: <div style="
5: border: 2px dashed #666666;
6: width : 90%;
7: margin: 5px 5px 5px 5px;
8: padding: 5px 5px 5px 5px;"
9: >
10: <h2>My Own Form Field:</h2>
11: <input
12: name="'.$PA['itemFormElName'].'"
13: value="'.htmlspecialchars($PA['itemFormElValue']).'"
14: onchange="'.htmlspecialchars(implode('',$PA['fieldChangeFunc'])).'"
15: '.$PA['onFocus'].'
16: />
17: </div>';
18: }
19: }
This is not the place to dig into more details about user defined forms. By this example you can start yourself up but you will have to figure out by yourself what options are available in the $PA array and how to use them.
Rendering a FlexForm element - essentially this consists of a hierarchically organized set of fields which will have their values saved into a single field in the database, stored as XML.
Key | Datatype | Description |
|---|---|---|
type | string | [Must be set to "flex"] |
ds_pointerField | string | Fieldname in the record which points to the field where the key for “ds” is found |
ds | string | Data Structure(s) defined in an array. Each key is a value that can be pointed to by “ds_pointerField”. Default key is “default” which is what you should use if you do not have a “ds_pointerField” value of course. For each value in the array there are two options:
Example with XML directly entered: 'config' => Array ( 'type' => 'flex', 'ds_pointerField' => 'list_type', 'ds' => array( 'default' => ' <T3DataStructure> <ROOT> <type>array</type> <el> <xmlTitle> <TCEforms> <label>The Title:</label> <config> <type>input</type> <size>48</size> </config> </TCEforms> </xmlTitle> </el> </ROOT> </T3DataStructure> ', ) ) Example with XML in external file: (File reference is relative) 'config' => Array ( 'type' => 'flex', 'ds_pointerField' => 'list_type', 'ds' => array( 'default' => 'FILE:EXT:mininews/flexform_ds.xml', ) ) |
ds_tableField | string | Contains the value “[table]:[fieldname]” from which to fetch Data Structure XML. “ds_pointerField” is in this case the pointer which should contain the uid of a record from that table. This is used by TemplaVoila extension for instance where a field in the tt_content table points to a TemplaVoila Data Structure record: 'tx_templavoila_flex' => Array ( 'exclude' => 1, 'label' => '...', 'displayCond' => 'FIELD:tx_templavoila_ds:REQ:true', 'config' => Array ( 'type' => 'flex', 'ds_pointerField' => 'tx_templavoila_ds', 'ds_tableField' => 'tx_templavoila_datastructure:dataprot', ) ), |
ds_pointerField_searchParent | string | Used to search for Data Structure recursively back in the table assuming that the table is a tree table. This value points to the “pid” field. See “templavoila” for example - uses this for the Page Template. |
ds_pointerField_searchParent_subField | string | Points to a field in the “rootline” which may contain a pointer to the “next-level” template. See “templavoila” for example - uses this for the Page Template. |
Basically the configuration for a FlexForm field is all about pointing to the Data Structure which will contain form rendering information in the application specific tag “<TCEforms>”.
For general information about the backbone of a Data Structure, please see the <T3DataStructure> chapter in the Data Formats section.
FlexForms create a form-in-a-form. The content coming from this form is still stored in the associated database field - but as an XML structure (stored by t3lib_div::array2xml())!
The “TCA” information needed to generate the FlexForm fields are found inside a <T3DataStructure> XML document. When you configure a FlexForm field in a Data Structure (DS) you can use basically all column types documented here for TCA. The limitations are:
“unique” and “uniqueInPid” evaluation is not available
You cannot nest FlexForm configurations inside of FlexForms.
Charset follows that of the current backend (that is “forceCharset” or the backend users language selection)
For FlexForms the DS is extended with a tag, “<TCEforms>” which define all settings specific to the FlexForms usage.
Also a few meta tag features are used.
Sometimes it may be necessary to reload flexform if content of the field in the flexform is changed. This is accomplished by adding “<onChange>reload</onChange>” inside <TCEforms>. A typical example for that is a field that defines operational modes for an extension. When the mode changes, a flexform may need to show a new set of fields. By combining the <onChange> tag for mode fields with <displayCond> tag for other fields, it is possible to create truly dynamic flexforms.
Notice that changing the mode does not delete hidden field values of the flexform. Always use the “mode” field to determine which parameters to use.
The tables below document the extension elements:
“Array” Elements:
Element | Description | Child elements |
|---|---|---|
<meta> | Can contain application specific meta settings. For FlexForms this means a definition of how languages are handled in the form. | <langChildren> <langDisable> |
<[application tag]> | In this case the application tag is “<TCEforms>” | A direct reflection of a ['columns']['fieldname']['config'] PHP array configuring a field in TCA. As XML this is expressed by array2xml()'s output. See example below. |
<ROOT><TCEforms> | For <ROOT> elements in the DS you can add application specific information about the sheet that the <ROOT> element represents. | <sheetTitle> <sheetDescription> <sheetShortDescr> |
“Value” Elements:
Element | Format | Description |
|---|---|---|
<langDisable> | Boolean, 0/1 | If set, then handling of localizations is disabled. Otherwise FlexForms will allow editing of additional languages than the default according to “sys_languages” table contents. The language you can select from is the language configured in “sys_languages” but they must have ISO country codes set - see example below. |
<langChildren> | Boolean, 0/1 | If set, then localizations are bound to the default values 1-1 (“value” level). Otherwise localizations are handled on “structure level” |
<sheetTitle> | string | Specifies the title of the sheet. Language splitted. |
<sheetDescription> | string | Specifies a description for the sheet shown in the flexform. Language splitted. |
<sheetShortDescr> | string | Specifies a short description of the sheet used in the tab-menu. Language splitted. |
FlexForms always resolve sheet definitions in a Data Structure. If only one sheet is defined that must be the “sDEF” sheet (default). In that case no tab-menu for sheets will appear (see examples below).
When saving FlexForm elements the content is stored as XML using t3lib_div::array2xml() to convert the internal PHP array to XML format. The structure is as follows:
“Array” Elements:
Element | Description | Child elements |
|---|---|---|
<T3FlexForms> | Document tag | <meta> <data> |
<meta> | Meta data for the content. For instance information about which sheet is active etc. | <currentSheetId> <currentLangId> |
<data> | Contains the data; sheets, language sections, field and values | <sheet> |
<sheet> | Contains the data for each sheet in the form. If there are no sheets, the default sheet “<sDEF>” is always used. | <sDEF> <s_[sheet keys]> |
<sDEF> <[sheet keys]> | For each sheet it contains elements for each language. If <meta><langChildren> is false then all languages are stored on this level, otherwise only the <lDEF> tag is used. | <lDEF> <l[ISO language code]> |
<lDEF> <[language keys]> | For each language the fields in the form will be available on this level. | <[fieldname]> |
<[fieldname]> | For each fieldname there is at least one element with the value, <vDEF>. If <meta><langChildren> is true then there will be a <v*> tag for each language holding localized values. | <vDEF> <v[ISO language code]> |
<currentLangId> | Numerical array of language ISO codes + “DEF” for default which are currently displayed for editing. | <n[0-x]> |
“Value” Elements:
Element | Format | Description |
|---|---|---|
<vDEF> <v[ISO language code]> | string | Content of the field in default or localized versions |
<currentSheetId> | string | Points to the currently shown sheet in the DS. |
For syntax highlighted example, see below.
The extension “mininews” displays a FlexForm in the Plugin type content element. The form displays a template selector box:
The DS used to render this field is found in the file “flexform_ds.xml” inside of the “mininews” extension. Notice the <TCEforms> tags:
<T3DataStructure>
<meta>
<langDisable>1</langDisable>
</meta>
<ROOT>
<type>array</type>
<el>
<field_templateObject>
<TCEforms>
<label>LLL:EXT:mininews/locallang_db.php:tt_content.pi_flexform.select_template</label>
<config>
<type>select</type>
<items>
<numIndex index=”0”>
<numIndex index=”0”></numIndex>
<numIndex index=”1”>0</numIndex>
</numIndex>
</items>
<foreign_table>tx_templavoila_tmplobj</foreign_table>
<foreign_table_where>
AND tx_templavoila_tmplobj.pid=###STORAGE_PID###
AND tx_templavoila_tmplobj.datastructure="EXT:mininews/template_datastructure.xml"
AND tx_templavoila_tmplobj.parent=0
ORDER BY tx_templavoila_tmplobj.title
</foreign_table_where>
<size>1</size>
<minitems>0</minitems>
<maxitems>1</maxitems>
</config>
</TCEforms>
</field_templateObject>
</el>
</ROOT>
</T3DataStructure>
It's clear that the contents of <TCEforms> is a direct reflection of the field configurations we normally set up in the $TCA array.
To configure the FlexForm field to use this Data Structure, the “mininews” extension simply includes this in the ext_tables.php file:
1: $TCA['tt_content']['types']['list']['subtypes_addlist'][$_EXTKEY.'_pi1']='pi_flexform';
2: t3lib_extMgm::addPiFlexFormValue($_EXTKEY.'_pi1', 'FILE:EXT:mininews/flexform_ds.xml');
In line 1 the tt_content field “pi_flexform” is added to the display of fields when the Plugin type is selected and set on “mininews_pi1”
In line 2 the DS xml file is configured to be the source of the FlexForm DS used.
If we browse the definition for the “pi_flexform” field in “tt_content” we will see this configuration:
As you can see two extension plugins, “newloginbox_pi1” and “mininews_pi1” has added pointers to their Data Structures.
In this example we create a flexform field with two “sheets”. Each sheet can contain a separate FlexForm structure.
....['config'] = array(
'type' => 'flex',
'ds' => array(
'default' => '
<T3DataStructure>
<sheets>
<sDEF>
<ROOT>
<TCEforms>
<sheetTitle>Default sheet</sheetTitle>
</TCEforms>
<type>array</type>
<el>
<header>
<TCEforms>
<label>Header</label>
<config>
<type>input</type>
<size>30</size>
</config>
</TCEforms>
</header>
<message>
<TCEforms>
<label>Message:</label>
<config>
<type>text</type>
<cols>30</cols>
<rows>5</rows>
</config>
</TCEforms>
</message>
</el>
</ROOT>
</sDEF>
<s_welcome>
<ROOT>
<TCEforms>
<sheetTitle>Second sheet</sheetTitle>
</TCEforms>
<type>array</type>
<el>
<show_forgot_password>
<TCEforms>
<label>Yes, I do:</label>
<config>
<type>check</type>
</config>
</TCEforms>
</show_forgot_password>
</el>
</ROOT>
</s_welcome>
</sheets>
</T3DataStructure>
'
)
);
The result from configuration is a form which looks like this:
Clicking “Second sheet” will now show the other Data Structure:
If you look at the XML stored in the database field this is how it looks:
<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<T3FlexForms>
<meta>
<currentSheetId>s_welcome</currentSheetId>
</meta>
<data>
<sDEF>
<lDEF>
<header>
<vDEF>This is a header</vDEF>
</header>
<message>
<vDEF>Here goes the message
This is another line in the message!</vDEF>
</message>
</lDEF>
</sDEF>
<s_welcome>
<lDEF>
<show_forgot_password>
<vDEF>1</vDEF>
</show_forgot_password>
</lDEF>
</s_welcome>
</data>
</T3FlexForms>
Notice how the data of the two sheets are separated.
Creating a RTE in FlexForms is done by adding “defaultExtras” content to the <TCEforms> tag:
<TCEforms>
<config>
<type>text</type>
<cols>48</cols>
<rows>5</rows>
</config>
<label>Subtitle</label>
<defaultExtras>richtext[*]:rte_transform[mode=ts_css]</defaultExtras>
</TCEforms>
FlexForms allows you to handle translations of content in two ways. But before you can enable those features you have to install the extension “static_info_tables” which contains country names and ISO-language codes which are the ones by which FlexForms stores localized content:
Secondly, you have to configure languages in the Database:
And finally, you have to make sure that each of these languages points to the right ISO code:
Localization method #1:
Immediately you will see that the form has got a language selector and if you select both languages and save the form you will see an additional set of fields for Danish:
Notice: If the “<meta><langDisable>” value is true then you will not see any languages of course.
The data XML in the data base will look like this:
<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<T3FlexForms>
<meta>
<currentSheetId>sDEF</currentSheetId>
<currentLangId>
<numIndex index=”0”>DEF</numIndex>
<numIndex index=”1”>DA</numIndex>
</currentLangId>
</meta>
<data>
<sDEF>
<lDEF>
<header>
<vDEF>This is a header</vDEF>
</header>
<message>
<vDEF>Here goes the message
This is another line in the message!</vDEF>
</message>
</lDEF>
<lDA>
<header>
<vDEF>Dette er en overskrift</vDEF>
</header>
<message>
<vDEF>Her skal beskeden indsættes
Dette er en anden linie i beskeden.</vDEF>
</message>
</lDA>
</sDEF>
<s_welcome>
<lDEF>
<show_forgot_password>
<vDEF>1</vDEF>
</show_forgot_password>
</lDEF>
</s_welcome>
</data>
</T3FlexForms>
Notice the tag <lDA> which contains the Danish translation!
Localization method #2:
In the first method of localization each language can potentially contain a differently structured data set. This is possible because as soon as a DS defines sections with array objects inside the number of objects can be individual!
The second method of localization handles each language on the value level instead, thus requiring a translation for each and every field in the default language! You enable this by setting “<meta><langChildren>” to “1”.
The editing form will now look like this:
You can see that the Danish translation for the header is grouped with the default header and likewise for the “Message” field.
The difference is also seen in the <T3FlexForms> content:
<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<T3FlexForms>
<meta>
<currentSheetId>sDEF</currentSheetId>
<currentLangId>
<numIndex index=”0”>DEF</numIndex>
<numIndex index=”1”>DA</numIndex>
</currentLangId>
</meta>
<data>
<sDEF>
<lDEF>
<header>
<vDEF>This is a header</vDEF>
<vDA>Dette er en overskrift</vDA>
</header>
<message>
<vDEF>Here goes the message
This is another line in the message!</vDEF>
<vDA>Here goes the message
This is another line in the message!</vDA>
</message>
</lDEF>
</sDEF>
<s_welcome>
<lDEF>
<show_forgot_password>
<vDEF>1</vDEF>
</show_forgot_password>
</lDEF>
</s_welcome>
</data>
</T3FlexForms>
You can see the Danish counterparts to the default values are stored in tags named “<vDA>” on the same level as “<vDEF>” is located.
NOTICE: The two localization methods are NOT compatible! You cannot suddenly change from the one method to the other without having to do some conversion of the data format. That is obvious when you look at how the two methods also require different data structures underneath!
Inline-Relational-Record-Editing (IRRE) offers a way of directly editing parent-child-relations in one backend view. New child records are created using AJAX calls to prevent a reload of the complete backend view. This type was first integrated in TYPO3 4.1.
Key | Datatype | Description | Scope |
|---|---|---|---|
type | string | [Must be set to "inline"] | Display / Proc. |
foreign_table | string (tablename) | [Must be set, there is no type “inline” without a foreign table]The table name of the child records is defined here. The table must be configured in $TCA. See the other related options below. | Display / Proc. |
appearance | array | Has information about the appearance of child-records, namely:
| Display |
foreign_field | string | The foreign_field is the field of the child record pointing to the parent record. This defines where to store the uid of the parent record. | Display / Proc. |
foreign_label | string | If set, it overrides the label set in $TCA[<foreign_table>]['ctrl']['label'] for the inline-view. | Display / Proc. |
foreign_selector | string | A selector is used to show all possible child records that could be used to create a relation with the parent record. It will be rendered as a multi-select-box. On clicking on an item inside the selector a new relation is created.The foreign_selector points to a field of the foreign_table that is responsible for providing a selector-box – this field on the foreign_table usually has the type “select” and also has a “foreign_table” defined. | Display / Proc. |
foreign_sortby | string | Define a field on the child record (or on the intermediate table) that stores the manual sorting information. It is possible to have different sortings, depending from which side of the relation we look at parent or child. | Display / Proc. |
foreign_default_sortby | string | If a fieldname for foreign_sortby is defined, then this is ignored. Otherwise this is used as the “ORDER BY” statement to sort the records in the table when listed. | Display |
foreign_table_field | string | The foreign_table_field is the field of the child record pointing to the parent record. This defines where to store the tablename of the parent record. On setting this configuration key together with foreign_field, the child record knows what its parent record is – so the child record could also be used on other parent tables.This issue is also known as “weak entity”.Do not cnfound with foreign_table or foreign_field. It has its own behaviour. | Display / Proc. |
foreign_unique | string | Field which must be unique for all children of a parent record. Example: Say you have two tables, products, your parent table, and prices, your child table (products) can have multiple prices. The prices table has a field called customer_group, which is a selector box. Now you want to be able to specify prices for each customer group when you edit a product, but of course you don't want to specify contradicting prices for one product (i.e. two different prices for the same customer_group). That's why you would set foreign_unique to the field name “customer_group”, to prevent that two prices for the same customer group can be created for one product. | Display / Proc. |
MM | string (table name) | Means that the relation to the records of "foreign_table" is done with a M-M relation with a third "join" table. That table typically has three columns:
The field which is configured as “inline” is not used for data-storage any more 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 (so no attributes). | Proc. |
size | integer | Height of the selector box 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 |
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 |
symmetric_field | string | This works like foreign_field, but in case of using bidirectional symmetric relations. symmetric_field defines in which field on the foreign_table the uid of the “other” parent is stored. | Display / Proc. |
symmetric_label | string | If set, it overrides the label set in $TCA[<foreign_table>]['ctrl']['label'] for the inline-view and only if looking to a symmetric relation from the “other” side. | Display / Proc. |
symmetric_sortby | string | This works like foreign_sortby, but in case of using bidirectional symmetric relations. Each side of a symmetric relation could have its own sorting, so symmetric_sortby defines a field on the foreign_table where the sorting of the “other” side is stored. | Display / Proc. |
This combines companies with persons (employees) using a comma separated list, so no “foreign_field” is used here.
$TCA['company'] = Array(
'ctrl' => ...,
'interface' => ...,
'feInterface' => ...,
'columns' => Array(
'hidden' => ...,
'employees' => Array(
'exclude' => 1,
'label' => 'LLL:EXT:myextension/locallang_db.xml:company.employees',
'config' => Array(
'type' => 'inline',
'foreign_table' => 'person',
'maxitems' => 10,
'appearance' => Array(
'collapseAll' => 1,
'expandSingle' => 1,
),
),
),
),
'types' => ...
'palettes' => ...
);
This example combines companies with persons (employees) using an intermediate table. It is also possible to add attributes to every relation – in this example, an attribute “jobtype” on the “person_company” table is defined. It is also possible to look at the relation from both sides (parent and child).
$TCA['person'] = Array( 'columns' => Array( 'employers' => Array( 'label' => 'LLL:EXT:myextension/locallang_db.xml:person.employers', 'config' => Array( 'type' => 'inline', 'foreign_table' => 'person_company', 'foreign_field' => 'person', 'foreign_label' => 'company', ), ), ),);
$TCA['company'] = Array( 'columns' => Array( 'employees' => Array( 'label' => 'LLL:EXT:myextension/locallang_db.xml:company.employees', 'config' => Array( 'type' => 'inline', 'foreign_table' => 'person_company', 'foreign_field' => 'company', 'foreign_label' => 'person', ), ), ),);
$TCA['person_company'] = Array( 'columns' => Array( 'person' => Array( 'label' => 'LLL:EXT:myextension/locallang_db.xml:person_company.person', 'config' => Array( 'type' => 'select', 'foreign_table' => 'person', 'size' => 1, 'minitems' => 0, 'maxitems' => 1, ), ), 'company' => Array( 'label' => 'LLL:EXT:myextension/locallang_db.xml:person_company.company', 'config' => Array( 'type' => 'select', 'foreign_table' => 'company', 'size' => 1, 'minitems' => 0, 'maxitems' => 1, ), ), 'jobtype' => Array( 'label' => 'LLL:EXT:myextension/locallang_db.xml:person_company.jobtype', 'config' => Array( 'type' => 'select', 'items' => Array( Array('Project Manager (PM)', '0'), Array('Chief Executive Officer (CEO)', '1'), Array('Chief Technology Officer (CTO)', '2'), ), 'size' => 1, 'maxitems' => 1, ), ), ),);
This example combines two persons with each other – imagine they are married. One person on the first side is the husband, and one person on the other side is the wife (or generally “spouse” in the example below). Symmetric relations combine object of the same with each other and it does not depend, from which side someone is looking to the relation – so the husband knows it's wife and the wife also know it's husband.
Sorting could be individually defined for each of the both sides (perhaps this should not be applied to a wife-husband-relationship in real life).
$TCA['person'] = Array( 'columns' => Array( 'employers' => Array( 'label' => 'LLL:EXT:myextension/locallang_db.xml:person.employers', 'config' => Array( 'type' => 'inline', 'foreign_table' => 'person_symmetric', 'foreign_field' => 'person', 'foreign_sortby' => 'sorting_person', 'foreign_label' => 'spouse', 'symmetric_field' => 'spouse', 'symmetric_sortby' => 'sorting_spouse', 'symmetric_label' => 'person', ), ), ),);
$TCA['person_symmetric'] = Array( 'columns' => Array( 'person' => Array( 'label' => 'LLL:EXT:myextension/locallang_db.xml:person_symmetric.person', 'config' => Array( 'type' => 'select', 'foreign_table' => 'person', 'size' => 1, 'minitems' => 0, 'maxitems' => 1, ), ), 'spouse' => Array( 'label' => 'LLL:EXT:myextension/locallang_db.xml:person_symmetric.spouse', 'config' => Array( 'type' => 'select', 'foreign_table' => 'person', 'size' => 1, 'minitems' => 0, 'maxitems' => 1, ), ), 'someattribute' => Array( 'label' => 'LLL:EXT:myextension/locallang_db.xml:person_symmetric.someattribute', 'config' => Array( 'type' => 'input', ), ), 'sorting_person' => Array( 'config' => Array( 'type' => 'passthrough', ), ), 'sorting_spouse' => Array( 'config' => Array( 'type' => 'passthrough', ), ), ),);
You have to add at least one entry in the "types"-configuration before any of the configured fields from the ['columns'] section will show up in TCEforms.
For instance, if you would like a form to look like below...:
... you could configure it with :
140: 'types' => Array (
141: '0' => Array('showitem' => 'hidden;;1, type, title, test_template'),
The key "showitem" lists the order in which to define the fields: "hidden, type, title, test_template"
The power of "types"-configuration is clear in the moment when you want the form composition of a record to depend on a value from the record. From the example above, lets say we want the selector box "type" to define the composition of fields in the form. This is configured like this:
2: 'ctrl' => Array (
3: 'title' => 'LLL:EXT:coreunittest/locallang_db.php:tx_coreunittest_1',
4: 'label' => 'title',
5: 'type' => 'type',
6: 'crdate' => 'crdate',
...
87: 'type' => Array (
88: 'exclude' => 0,
89: 'label' => 'LLL:EXT:coreunittest/locallang_db.php:tx_coreunittest_1.type',
90: 'config' => Array (
91: 'type' => 'select',
92: 'items' => Array (
93: Array('LLL:EXT:coreunittest/locallang_db.php:tx_coreunittest_1.type.I.0', '0'),
94: Array('LLL:EXT:coreunittest/locallang_db.php:tx_coreunittest_1.type.I.1', '1'),
95: Array('LLL:EXT:coreunittest/locallang_db.php:tx_coreunittest_1.type.I.2', '2'),
96: Array('LLL:EXT:coreunittest/locallang_db.php:tx_coreunittest_1.type.I.3', '3'),
97: ),
98: 'size' => 1,
99: 'maxitems' => 1,
100: )
101: ),
Line 5 defines that the field name "type" is to be used as pointer to a key in the types-configuration.
Line 87-101 shows the configuration of this selector box which turns out to be rather normal, having four static values.
In the end of the TCA configuration the "types" section contain four listings, one for each value of the selector box:
140: 'types' => Array (
141: '0' => Array('showitem' => 'hidden;;1, type, title, test_template'),
142: '1' => Array('showitem' => 'title, test_template, hidden, type'),
143: '2' => Array('showitem' => 'type, title'),
144: '3' => Array('showitem' => 'type;;2'),
145: ),
If the "type" selector box has the value "0" (zero, "Mode 1") you will see the same as in the example above. If it is changed to "1" (label "Mode 2"), then the form changes as well:
The order of fields in this case is clearly the one defined in line 142.
Changing the "type" value to "Mode 3" means we will see this form:
And "Mode 4":
If no "type" field is defined the type value will default to "0" (zero). If the type value (coming from a field or being zero by default) does not point to a defined index in the "types"-configuration, the configuration for key "1" will be used by default.
Notice: You must not show the same field more than once in the editing form. If you do, the field will not detect the value properly.
Key | Datatype | Description |
|---|---|---|
showitem | string (list of field configuration sets) | Required. Configuration of the displayed order of fields in TCEforms. The whole strings is divided by tokens according to a - unfortunately - complex ruleset.
Notice: Instead of a real fieldname you can theoretically insert "--div--" and you will have a divider line shown. However this is not rendered by default so it has no significance. Another special fieldname, '--palette--', will insert a link to a palette (of course you need to specify a palette and title then...) |
subtype_value_field | string (fieldname) | Fieldname, which holds a value being a key in the 'subtypes_excludelist' array. This is used to specify a secondary level of 'types' - basically hiding certain fields of those found in the types-configuration, based on the value of another field in the row. Example (from sysext/cms/tbl_tt_content.php): 'subtype_value_field' => 'list_type', 'subtypes_excludelist' => Array( '3' => 'layout', '1' => 'layout', '8' => 'layout', 'indexed_search' => 'layout,bodytext', ) |
subtypes_excludelist | array | See "subtype_value_field". Syntax: “[field value]” => “[commalist of fields (from the main types-config) which are excluded]” |
subtypes_addlist | array | A list of fields to add when the "subtype_value_field" matches a key in this array. See "subtype_value_field". Syntax: “[value]” => “[commalist of fields which are added] Notice: that any transformation configuration used by TCE will NOT work because that configuration is visible for the TCEforms class only during the drawing of fields. In other words any configuration in this list of fields will work for display only.” |
bitmask_value_field | string (fieldname) | Fieldname, which holds a value being the integer (bit-mask) for the 'bitmask_excludelist_bits' array. It works much like 'subtype_value_field' but excludes fields based on whether a bit from the value field is set or not. See 'bitmask_excludelist_bits'; [+/-] indicates whether the bit [bit-number] is set or not. Example: 'bitmask_value_field' => 'active', 'bitmask_excludelist_bits' => Array ( '-0' => 'tmpl_a_subpart_marker,tmpl_a_description', '-1' => 'tmpl_b_subpart_marker,tmpl_b_description', '-2' => 'tmpl_c_subpart_marker,tmpl_c_description' ) |
bitmask_excludelist_bits | array | See "bitmask_value_field" “[+/-][bit-number]” => “[commalist of fields (from the main types-config) excluded]” |
Now follows a codelisting as example:
This is a quite normal and simple configuration. In the "types" section the list of fields does not contain much additional stuff except the first entry which configures "Part 5" - the colorscheme for the whole form.
Basically the "showitem" list is just listing the fieldnames which will be displayed.
script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'types' => Array ( '0' => Array('showitem' => 'name;;;;1-1-1, age, language, allergies, allergies_list, institution, babysitting, other')),
The result of this configuration looks like this:
This is a semi-complex example taken from the "mininews" extension. It does include configuration of the rich text editor which is the main reason for the lengthyness. Notice the "palettes" definition which the example includes. The palette has number "1" and will be triggered when the user puts the focus on the field "hidden" (according to the configuration in the "types" list).
script_ended = 0;
function jumpToUrl(URL) {
document.location = URL;
}
'types' => Array ( '0' => Array('showitem' => 'hidden;;1;;1-1-1, datetime, title;;;;2-2-2, teaser;;;;3-3-3, full_text;;;richtext[cut|copy|paste|formatblock|textcolor|bold|italic|underline|left|center|right|orderedlist|unorderedlist|outdent|indent|link|table|image|line|chMode]:rte_transform[mode=ts_css|imgpath=uploads/tx_mininews/rte/], front_page')),
'palettes' => Array (
'1' => Array('showitem' => 'starttime, endtime, fe_group'))
This is a part of the "types" definition for the "tt_content" table. This is one of the more advanced configurations, including basically all the levels of options you can use:
'types' => Array (
'1' => Array('showitem' => 'CType'),
'header' => Array('showitem' => 'CType;;4;button;1-1-1, header;;3;;2-2-2, subheader;;8'),
'text' => Array('showitem' => 'CType;;4;button;1-1-1, header;;3;;2-2-2, bodytext;;9;richtext[paste|bold|italic|underline|formatblock|class|left|center|right|orderedlist|unorderedlist|outdent|indent|link|image]:rte_transform[flag=rte_enabled|mode=ts];3-3-3, rte_enabled, text_properties'),
'textpic' => Array('showitem' => 'CType;;4;button;1-1-1, header;;3;;2-2-2, bodytext;;9;richtext[paste|bold|italic|underline|formatblock|class|left|center|right|orderedlist|unorderedlist|outdent|indent|link|image]:rte_transform[flag=rte_enabled|mode=ts];3-3-3, rte_enabled, text_properties, --div--, image;;;;4-4-4, imageorient;;2, imagewidth;;13,
--palette--;LLL:EXT:cms/locallang_ttc.php:ALT.imgLinks;7,
--palette--;LLL:EXT:cms/locallang_ttc.php:ALT.imgOptions;11,
imagecaption;;5'),
'rte' => Array('showitem' => 'CType;;4;button;1-1-1, header;;3;;2-2-2, bodytext;;;nowrap:richtext[*]:rte_transform[mode=ts_images-ts_reglinks];3-3-3'),
'image' => Array('showitem' => 'CType;;4;button;1-1-1, header;;3;;2-2-2, image;;;;4-4-4, imageorient;;2, imagewidth;;13,
--palette--;LLL:EXT:cms/locallang_ttc.php:ALT.imgLinks;7,
--palette--;LLL:EXT:cms/locallang_ttc.php:ALT.imgOptions;11,
imagecaption;;5'),
'bullets' => Array('showitem' => 'CType;;4;button;1-1-1, header;;3;;2-2-2, layout;;;;3-3-3, bodytext;;9;nowrap, text_properties'),
'table' => Array('showitem' => 'CType;;4;button;1-1-1, header;;3;;2-2-2, layout;;10;button;3-3-3, cols, bodytext;;9;nowrap:wizards[table], text_properties'),
'splash' => Array('showitem' => 'CType;;4;button;1-1-1, header;LLL:EXT:lang/locallang_general.php:LGL.name;;;2-2-2, splash_layout, bodytext;;;;3-3-3, image;;6'),
'uploads' => Array('showitem' => 'CType;;4;button;1-1-1, header;;3;;2-2-2, media;;;;5-5-5,
select_key;LLL:EXT:cms/locallang_ttc.php:select_key.ALT.uploads,
layout;;10;button, filelink_size,
imagecaption;LLL:EXT:cms/locallang_ttc.php:imagecaption.ALT.uploads;;nowrap'),
"Palettes" represents a way to move less frequently used form fields out of sight. Palettes are groups of field which are associated with a field in the main form. When this field is activated the palette fields are displayed. They are also known as "secondary options" which is a more telling name I believe.
This configuration shows us that two palettes are defined (line 8 and 9) with key 1 and 2.
1: 'types' => Array (
2: '0' => Array('showitem' => 'hidden;;1, type;;1, title, test_template'),
3: '1' => Array('showitem' => 'title, test_template;;1, hidden, type'),
4: '2' => Array('showitem' => 'type, title'),
5: '3' => Array('showitem' => 'type;;2'),
6: ),
7: 'palettes' => Array (
8: '1' => Array('showitem' => 'starttime, endtime, fe_group'),
9: '2' => Array('showitem' => 'title'),
10: )
11: );
Palette 1 is referred to from "types"-configuration "0" by the field name "hidden" and "type" and "types" configuration "1" by the field "test_template".
Palette 2 is referred to from "types"-configuration "3" by the field name "type".
The configuration means that next to the checkbox for the field "hidden" there is an icon which will activate the palette when clicked:
The palette fields appear in the top frame until another field in the main form is activated.
The other option is to enable "Show secondary options" (found in bottom of the form) which in some cases is more convenient way to access palette fields:
This results in the palette fields being included into the form, but arranged horizontally instead of vertically:
Notice: You should not show the same field on more than one palette! If you do, the images (required and changed) will not work in MSIE.
Key | Datatype | Description |
|---|---|---|
showitem | string (list of fieldnames) | Required. Configuration of the displayed order of fields in the palette. Remember that a fieldname must not appear in more than one palette and not more than one time!. Eg. 'hidden,starttime,endtime' |
canNotCollapse | boolean | If set, then this palette is not allowed to 'collapse' in the TCEforms-display. This basically means that if "Show secondary options" is not on, this palette is still displayed in the main form and not linked with an icon. |
