FlexForm field

New in version 13.0

Renders a FlexForm element. Essentially, this consists in a hierarchically organized set of fields which will have their values saved into a single field in the database, stored as XML.

The according database field is generated automatically.

The general idea is: There is a data structure that defines which and how single fields should be displayed, re-using all the TCA column type possibilities. The actual values of single fields are then stored in an XML representation within this "flex" field.

Table of contents

Properties of the TCA column type flex

Changed in version 13.0

The configuration options ds_tableField, ds_pointerField_searchParent_subField and ds_pointerField_searchParent are not handled anymore. Use the Events to replace their logic if needed.

Name Type Scope
behaviour
allowLanguageSynchronization
 boolean Proc.
ds
 array Display / Proc.
ds_pointerField
 string Display / Proc.
fieldInformation
fieldWizard
defaultLanguageDifferences
 array
localizationStateSelector
 array
otherLanguageContent
 array
readOnly
 boolean Display

behaviour

behaviour

allowLanguageSynchronization

allowLanguageSynchronization
Type
boolean
Default
false
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['allowLanguageSynchronization']
Scope
Proc.

Allows an editor to select in a localized record whether the value is copied over from default or source language record, or if the field has an own value in the localization. If set to true and if the table supports localization and if a localized record is edited, this setting enables FieldWizard LocalizationStateSelector: Two or three radio buttons shown below the field input. The state of this is stored in a json encoded array in the database table called l10n_state. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.

EXT:my_extension/Configuration/TCA/Overrides/someTable.php 
<?php

$flexField = [
    'config' => [
        'type' => 'flex',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];
Copied!

ds

ds
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.

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.

If you specified more than one ds_pointerField, the keys in this "ds" array should contain comma-separated value pairs where the asterisk * matches all values (see the example below). If you don't need to switch for the second ds_pointerField, it's also possible to use only the first ds_pointerField's value as a key in the "ds" array without necessarily suffixing it with ",*" for a catch-all on the second ds_pointerField.

For each value in the array there are two options:

  • Make a reference to an external XML file
  • Either enter XML directly
Example with XML in external file
EXT:styleguide/Configuration/TCA/tx_styleguide_flex.php 
[
    'columns' => [
        'flex_file_1' => [
            'label' => 'flex_file_1 simple flexform in external file',
            'description' => 'field description',
            'config' => [
                'type' => 'flex',
                'ds' => [
                    'default' => 'FILE:EXT:styleguide/Configuration/FlexForms/Simple.xml',
                ],
            ],
        ],
    ],
]
Copied!

The included file:

<T3DataStructure>
    <sheets>
        <sDEF>
            <ROOT>
                <sheetTitle>Sheet Title</sheetTitle>
                <type>array</type>
                <el>
                    <input_1>
                        <label>input_1</label>
                        <config>
                            <type>input</type>
                        </config>
                    </input_1>
                </el>
            </ROOT>
        </sDEF>
    </sheets>
</T3DataStructure>
Copied!
Example with XML directly entered
EXT:styleguide/Configuration/TCA/tx_styleguide_flex.php 
[
    'columns' => [
        'flex_2' => [
            'label' => 'flex_2 section container',
            'config' => [
                'type' => 'flex',
                'ds' => [
                    'default' => '
                        <T3DataStructure>
                            <sheets>
                                <sSection>
                                    <ROOT>
                                        <sheetTitle>section</sheetTitle>
                                        <type>array</type>
                                        <el>
                                            <section_1>
                                                <title>section_1</title>
                                                <type>array</type>
                                                <section>1</section>
                                                <el>
                                                    <container_1>
                                                        <type>array</type>
                                                        <title>container_1</title>
                                                        <el>
                                                            <input_1>
                                                                <label>input_1 description</label>
                                                                <description>field description</description>
                                                                <config>
                                                                    <type>input</type>
                                                                </config>
                                                            </input_1>
                                                            <color_1>
                                                                <label>color_1</label>
                                                                <config>
                                                                    <type>color</type>
                                                                    <size>10</size>
                                                                </config>
                                                            </color_1>
                                                        </el>
                                                    </container_1>
                                                    <container_2>
                                                        <type>array</type>
                                                        <title>container_2</title>
                                                        <el>
                                                            <text_1>
                                                                <label>text_1 default "foo"</label>
                                                                <config>
                                                                    <type>text</type>
                                                                    <default>foo</default>
                                                                </config>
                                                            </text_1>
                                                        </el>
                                                    </container_2>
                                                </el>
                                            </section_1>
                                        </el>
                                    </ROOT>
                                </sSection>
                            </sheets>
                        </T3DataStructure>
                    ',
                ],
            ],
        ],
    ],
]
Copied!

ds_pointerField

ds_pointerField
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']
Scope
Display / Proc.

Field name(s) in the record which point to the field where the key for "ds" is found. Up to two field names can be specified comma separated.

fieldInformation

fieldInformation

For details see fieldInformation.

fieldWizard

fieldWizard

defaultLanguageDifferences

defaultLanguageDifferences
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['defaultLanguageDifferences']

For details see defaultLanguageDifferences.

localizationStateSelector

localizationStateSelector
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']

For details see localizationStateSelector.

otherLanguageContent

otherLanguageContent
Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['otherLanguageContent']

For details see otherLanguageContent.

readOnly

readOnly
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['readOnly']
Scope
Display

Renders the field in a way that the user can see the value but cannot edit it.

Defining multiple data structures for different records

There can be multiple data structures defined in TCA and it depends on the configuration and the record which one is chosen. If the ds and ds_pointerField are not sufficient, you can use the Events to manipulate with data structure should be displayed.

Events to manipulate the FlexForm data structure

There are appropriate events that allow the manipulation of the data structure lookup logic: