This chapter of the document aims to describe the global array, $TCA, in TYPO3. The array describes the database tables that TYPO3 can operate on. Since the database is a central element in TYPO3 this array is a backbone in the system.
The following pages will describe all the features of the $TCA array in details.
This global array in TYPO3 defines the editable database tables and the relationship between them and how the fields in tables are rendered in backend forms and processed in the TCE and so on.
The array is highly extendable through extensions and in fact only four tables are configured by default in TYPO3. These four tables - those which are required for any TYPO3 installation - is configured in the file "t3lib/stddb/tables.php". The tables are:
the "pages" table containing the page tree of TYPO3
the "be_users" table containing backend users
the "be_groups" table containing backend user groups
the "sys_filemounts" table containing file mounts for backend users.
All other tables are configured in extensions.
The file "t3lib/stddb/tables.php" contains not only the $TCA definition. You can also find other global core variables defined there. For instance $PAGES_TYPES, $ICON_TYPES and $LANG_GENERAL_LABELS which are also used in relation to $TCA but much less important and probably not relavant for you to use. There are more details on these arrays further ahead in this document.
This is done by extensions and typically the information added to the table is stored in extension files named "ext_tables.php". Please see the Extension API description for details about this.
An example could look like this (from the extension "mininews", file "ext_tables.php"):
1: // Defining a new column for the mininews extension (goes into the tt_content table)
2: $tempColumns = Array (
3: "tx_mininews_frontpage_list" => Array (
4: "exclude" => 1,
5: "label" => "LLL:EXT:mininews/locallang_db.php:tt_content.tx_mininews_frontpage_list",
6: "config" => Array (
7: "type" => "select",
8: "items" => Array (
9: Array("LLL:EXT:mininews/locallang_db.php:tt_content.tx_mininews_frontpage_list.I.0", "0"),
10: Array("LLL:EXT:mininews/locallang_db.php:tt_content.tx_mininews_frontpage_list.I.1", "1"),
11: ),
12: )
13: ),
14: );
15:
16: // Make sure to load all of "tt_content":
17: t3lib_div::loadTCA("tt_content");
18:
19: // ... then add the column for mininews which was defined above:
20: t3lib_extMgm::addTCAcolumns("tt_content",$tempColumns,1);
21:
22: // ... and finally add the new column definition to the list of fields shown for the mininews plugin:
23: // (This also removes the presence of the normally shown fields, "layout" and "select_key")
24: $TCA["tt_content"]["types"]["list"]["subtypes_excludelist"][$_EXTKEY."_pi1"]="layout,select_key";
25: $TCA["tt_content"]["types"]["list"]["subtypes_addlist"][$_EXTKEY."_pi1"]="tx_mininews_frontpage_list;;;;1-1-1";
26:
27: // Now, define a new table for the extension. Name: "tx_mininews_news"
28: // Only the "ctrl" section is defined since the rest of the config is in the "tca.php" file, loaded dynamically when needed.
29: $TCA["tx_mininews_news"] = Array (
30: "ctrl" => Array (
31: "title" => "LLL:EXT:mininews/locallang_db.php:tx_mininews_news",
32: "label" => "title",
33: "tstamp" => "tstamp",
34: "crdate" => "crdate",
35: "cruser_id" => "cruser_id",
36: "default_sortby" => "ORDER BY datetime DESC",
37: "delete" => "deleted",
38: "enablecolumns" => Array (
39: "disabled" => "hidden",
40: "starttime" => "starttime",
41: "endtime" => "endtime",
42: "fe_group" => "fe_group",
43: ),
44: "dynamicConfigFile" => t3lib_extMgm::extPath($_EXTKEY)."tca.php",
45: "iconfile" => t3lib_extMgm::extRelPath($_EXTKEY)."icon_tx_mininews_news.gif",
46: ),
47: "feInterface" => Array (
48: "fe_admin_fieldList" => "hidden, starttime, endtime, fe_group, datetime, title, teaser, full_text, front_page",
49: )
50: );
51:
52: // Then, make sure records from this table is allowed on regular pages:
53: t3lib_extMgm::allowTableOnStandardPages("tx_mininews_news");
54: // ... and allowed to be added in the "Insert Record" content element type:
55: t3lib_extMgm::addToInsertRecords("tx_mininews_news");
Here line 1-25 is about adding a column to the table "tt_content" which was in fact added by the extension "cms"
Then line 27-55 shows how a totally new table is added for the extension "mininews".
On the "first level" of the $TCA array you will find key values which matches with database table names:
$TCA['pages'] = Array (
...
);
$TCA['tt_content'] = Array (
...
);
$TCA['tx_myext'] = Array (
...
);
Here three tables, "pages", "tt_content" and "tt_myext" is shown as examples.
Each table is defined by an array which configures how the system handles the table, both for display and processing in the backend (the frontend is mostly independant of the TCA except from some features in the [ctrl] section).
On this "second level" (configuring a single table) the structure is as follows:
$TCA['tablename'] = Array (
'ctrl' => Array(
....
),
'interface' => Array(
....
),
'feInterface' => Array(
....
),
'columns' => Array(
'fieldname_1' => Array(
....
),
'fieldname_2' => Array(
....
),
....
),
'types' => Array(
....
),
'palettes' => Array(
....
),
);
(The bold/italic strings in blacks indicate that here actual table/fieldnames are used as keys)
This table describes each of the sections. Over the next pages you will see each section described in detail with all features.
Section | Description |
|---|---|
ctrl | The table The "ctrl" section contains properties for the table in general. These are basically devided in two main categories;
|
interface | The backend interface handling The "interface" section contains properties related to the tables display in the backend, mostly the Web>List module. |
feInterface | Frontend Editing 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. |
columns | The individual fields 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, input 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 for each type. |
types | The form layout for editing The "types" section defines how the fields in the table (configured in the "columns" section) should be arranged inside the editing form; in which order, with which "palettes" (see below) and with which possible additional features applied. |
palettes | The palette fields order A palette is just a list of fields which will be arranged horizontally side-by-side. But the main idea is that these fields can be displayed in the top-frame of the backend interface on request so they don't display inside the main form. In this way they are kind of hidden fields which are brought forth either by clicking an icon in the main form or (more usually) when you place the cursor in a form field of the main form). |
Before you read on, lets just refresh the meaning of a few concepts mentioned on the next pages:
TCE: Short for "TYPO3 Core Engine". Also referred to as "TCEmain". This class (class.t3lib_tcemain) should ideally handle all updates to records made in the backend of TYPO3. The class will handle all the rules which may be applied to each table correctly. It will also handle logging, versioning, history/undo features, copying/moving/deleting etc.
"list of": Typically used like "list of fieldnames". Whenever "list of" is used it means a list of strings separated by comma and with NO space between the values.
field name: The name of a field from a database table. Another word for the same is "column" but it is used more rarely, however meaning the exact same thing when used.
record type: A record can have different types, expressed by the value of a certain field in the record. This field is defined by the [ctrl][type] value and it affects also which fields ("types"-configuration) is used to display possible form fields.
(LS): "LanguageSplitted" - meaning that
the value can be a plain string which will be splitted by the "|" token where each part corresponds to a language as found in the constant "TYPO3_languages" (obsolete concept! Depricated!)
or the string can fetch a value from a locallang file by prefixing the string with "LLL:" (please see the description of [ctrl][title] for details).
In almost the whole system the [ctrl] section of the $TCA entry for a table plays a crucial role. For all tables configured in $TCA this section must exist in $TCA. The other sections (except [feInterface]) can optionally be stored in another file.
This feature allows scalability since hundreds of tables can be configured with their complete [ctrl]-sections while leaving a relatively small memory footprint since they don't define all the other sections by default (eg. the "columns" section can group quite large!). Please see the [ctrl]-property "dynamicConfigFile" and the section "Loading the full $TCA dynamically" for details.
However this means that:
You can always depend on accessing information in the [ctrl] section, eg. $TCA['your_table_name']['ctrl']
But before you can depend on information in any other section (except [feInterface]) you should:
1) Call t3lib_loadTCA('your_table_name'); (This will dynamically load the full content of the TCA section for the table)
2) Then access the information, eg. $TCA['your_table_name']['columns']['your_field_name']
See more information in the section about handling after the $TCA array reference section.
