Core API

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:

1. One field, "displaytype", is a selectorbox with two values: "1" with the label "Regular display" and "2" with the label "Regular display + link"

2. Then three other fields, "title", "description" and "title_link"

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:

          '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:

1. If there is a slash ( / ) in the value: It must be a relative filepath pointing to the icon file relative to the typo3/ (admin) folder. You may start that path with '../' if you like to get your icon from a folder in the PATH_site path.

   For extensions, see example below.

2. If there is just a filename: It must exist in the "typo3/gfx/i/" folder.

3. If empty/not given: The default icon for a table is defined as "gfx/i/[table_name].gif". (This is an obsolete approach to use since the content of the "gfx/i/" folder should not be changed.)

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:

          '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:

1. 0 (false): Can only exist in the page tree.
   Records from this table must belong to a page (have a positive "pid" field value). Thus records cannot be created in the root of the page tree (where "admin" users are the only ones allowed to create records anyways).

2. 1 (true): Can only exist in the root.
   Records must have a "pid"-field value equal to zero. The consequence is that only admin can edit this record.

3. -1: Can exist in both page tree and root.
   Records can belong either to a page (positive "pid" field value) or exist in the root of the page tree (where the "pid" field value will be 0 (zero))
   Notice: that the -1 value will still select foreign_table records for selectox boxes only from root (pid=0)

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:

          '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:

1. "t3ver_oid" - Pointing back to online version

2. "t3ver_id" - Incremental integer (version number)

3. "t3ver_label" - Version label, eg. "1.1.1" or "Christmas edition"

4. "t3ver_wsid" - Workspace ID. For all workspace Ids apart from 0 (zero) there can be only one version of an element per ID.

5. "t3ver_state" - Contains special states of a version used when new and deleted content requires versioning.

   1. For an online version with this value set to "1" it means that it is a temporary placeholder for a new element.

   2. For an offline (unpublished) version with this value set to "2" it means that when swapped, the page must be deleted also.

   3. For an offline (unpublished) version with this value set to "-1" it is just an indication that the online version has the flag set to "1" (is a placeholder for new records.). This only affects display, not processing anywhere.

6. "t3ver_stage" - For custom workspaces elements go through a cycle where 0 (zero) represents the editing cycle, 1 represents review cycle and 10 represents ready for publishing.

1. "t3ver_count" - 0/offline=draft/never published, 0/online=current, 1/offline=archive, 1+=multiple online/offline occurences (incrementation happens when versions are swapped offline.)

2. "t3ver_tstamp" - Timestamp of last swap/publish action.

1. The fields pid and uid should have "signed" attributes in MySQL (so their content can be negative!)

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:

1. If an absolute path: Well, its an absolute path... (this is used for extensions, see example below).

2. If  prefixed with "T3LIB:" This indicates that it's position is in t3lib/install/

3. By default: The value is a filename relative to "typo3conf/"

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.