FlexForm syntax

Note

This section is still messy, should be merged with the section from Core API and FlexForms and should be much easier to understand.

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 \TYPO3\CMS\Core\Utility\GeneralUtility::xml2array().

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.

  • You cannot add, change or remove fields in FlexForms without copying the data structure and changing the configuration accordingly.

  • Charset follows that of the current backend UTF-8. When storing FlexForm information in external files, make sure that they are using UTF-8 too.

  • type='inline' and other types that point to different tables are not allowed in FlexForm section containers.

Changed in version 13.0: Since TYPO3 13.0, also type='select' (when using foreign_table) is not allowed and will raise an exception when used. Note this only applies to FlexForm sections, not general FlexForm usage.

Changed in version 12.0: The superfluous array key TCEforms was removed and is not evaluated anymore. Its sole purpose was to wrap real TCA definitions.

The tag TCEforms should be removed upon dropping TYPO3 v11 support.

The tables below documents the extension elements:

Array Elements

<meta>

Element

<meta> Can contain application specific meta settings. For FlexForms this means a definition of how languages are handled in the form.

<[application tag]>

Element

A direct reflection of a ['columns']['field name']['config'] PHP array configuring a field in TCA. As XML, this is expressed by array2xml()'s output.

<ROOT>

Element

<ROOT> For <ROOT> elements in the DS you can add application specific information about the sheet that the <ROOT> element represents.

Child elements

<sheetTitle>

<sheetDescription>

<sheetShortDescr>

Value Elements

<sheetTitle>

Element

<sheetTitle>

Format

string or LLL reference Specifies the title of the sheet.

<sheetDescription>

Element

<sheetDescription>

Format

string or LLL reference Specifies a description for the sheet shown in the flexform.

<sheetShortDescr>

Element

<sheetShortDescr>

Format

string or LLL reference Specifies a short description of the sheet used in the tab-menu.

Sheets and FlexForms

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

FlexForm data format, <T3FlexForms>

When saving FlexForm elements the content is stored as XML using \TYPO3\CMS\Core\Utility\GeneralUtility::array2xml() to convert the internal PHP array to XML format. The structure is as follows:

<T3FlexForms>

Element

<T3FlexForms> Document tag

Child elements

<meta>

<data>

<meta>

Element

<meta> Meta data for the content. For instance information about which sheet is active etc.

<data>

Element

<data> Contains the data: sheets, language sections, field and values

Child elements

<sheet>

<sheets>

Element

<sheets> Contains the data for each sheet in the form. If there are no sheets, the default sheet "<sDEF>" is always used.

Child elements

<sDEF>

<s_[sheet keys]>

<sDEF>

Element

<sDEF> For each sheet it contains elements for each language. only the <lDEF> tag is used.

Child elements

<lDEF>

<lDEF>

Element

<lDEF> For each language the fields in the form will be available on this level.

Child elements

<[field name]>

<[field name]>

Element

<[field name]> For each field name there is at least one element with the value, <vDEF>.

Child elements

<vDEF>

<vDEF>

Element

<vDEF>

Format

string Content of the field in default or localized versions.