Group fields¶

Properties of the TCA column type group¶

allowed ¶

Type

string (list)

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Proc. / Display

A comma list of tables from $GLOBALS['TCA'], for example "pages,be_users".

Note

If the field is the foreign side of a bidirectional MM relation, only the first table is used and that must be the table of the records on the native side of the relation.

Note

When using Extbase, you also need to fill foreign_table property with the same table name as used in allowed property (but with just one table name).

[
    'columns' => [
        'group_db_1' => [
            'label' => 'group_db_1 allowed=be_users,be_groups description',
            'description' => 'field description',
            'config' => [
                'type' => 'group',
                'allowed' => 'be_users,be_groups',
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

behaviour ¶

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

$groupField = [
    'config' => [
        'type' => 'group',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];

Copied!

autoSizeMax ¶

Type

integer

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Display

The maximum size (height) of the select field.

The size of the select field will be automatically adjusted based on the number of selected items. The select field will never be smaller than the specified size and never larger than the value of autoSizeMax.

Note

Only has an effect if maxitems is greater than 1.

dontRemapTablesOnCopy ¶

Type

string (list of tables)

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Proc.

Types

Description

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.

elementBrowserEntryPoints ¶

Type

array

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Display

By default, the last selected page is used when opening the element browser. Setting this configuration value changes this behaviour.

This configuration value is a PHP array, containing table => id pairs. When opening the element browser for a specific table (buttons below the group field), the defined page is then always selected by default. There is also the special _default key, used for the general element browser button (on the right side of the group field), which is not dedicated to a specific table.

This configuration value also supports the known markers ###SITEROOT###, ###CURRENT_PID### and ###PAGE_TSCONFIG_<key>###.

Each table => id pair can also be overridden via page TSconfig.

'simple_group' => [
    'label' => 'Simple group field',
    'config' => [
        'type' => 'group',
        'allowed' => 'tt_content',
        'elementBrowserEntryPoints' => [
            'tt_content' => 123,
        ]
    ]
],

This could then be overridden via page TSconfig:

TCEFORM.my_table.simple_group.config.elementBrowserEntryPoints.tt_content = 321

Since only one table is allowed, the defined entry point is also automatically used for the general element browser button.

In case the group field allows more than one table, the _default key has to be set:

'extended_group' => [
    'label' => 'Extended group field',
    'config' => [
        'type' => 'group',
        'allowed' => 'tt_content,tx_news_domain_model_news',
        'elementBrowserEntryPoints' => [
            '_default' => '###CURRENT_PID###' // E.g. use a special marker
            'tt_content' => 123,
            'tx_news_domain_model_news' => 124,
        ]
    ]
],

Of course, the _default key can also be overridden via page TSconfig:

TCEFORM.my_table.extended_group.config.elementBrowserEntryPoints._default = 122

fieldControl ¶

The field of type group can enable all common field control options. Furthermore the following are available:

addRecord ¶

Type

array

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']

Scope

fieldControl

Types

group

Control button to directly add a related record. Leaves the current view and opens a new form to add a new record. On 'Save and close', the record is directly selected as referenced element in the type='group' field. If multiple tables are allowed, the first table from the allowed list is selected, if no specific table option is given.

Note

The add record control is disabled by default, enable it if needed. It is shown below the edit popup control if not changed by below or after settings.

Example: Group field with add popup enabled

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_group.php

[
    'columns' => [
        'group_db_1' => [
            'label' => 'group_db_1 allowed=be_users,be_groups description',
            'description' => 'field description',
            'config' => [
                'type' => 'group',
                'allowed' => 'be_users,be_groups',
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

editPopup ¶

Type

array

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']

Scope

fieldControl

Types

group

The edit popup field control shows a pencil icon to edit an element directly in a popup window. When a record is selected and the edit button is clicked, that record opens in a new window for modification.

For details see editPopup.

Note

The edit popup control is pre-configured, but disabled by default. Enable it if you need it, the button is by default shown below element browser and insert clipboard.

Example: Group field with edit popup enabled

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_group.php

[
    'columns' => [
        'group_db_1' => [
            'label' => 'group_db_1 allowed=be_users,be_groups description',
            'description' => 'field description',
            'config' => [
                'type' => 'group',
                'allowed' => 'be_users,be_groups',
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

listModule ¶

Type

array

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']

Scope

fieldControl

Types

group

The list module control button opens the Web > List module for only one table and allows the user to manipulate stuff there.

For details see listModule.

Note

The list module control is disabled by default, enable it if needed. It is shown below the add record control if not changed by below or after settings.

Example: Group field with add list module enabled

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_group.php

[
    'columns' => [
        'group_db_1' => [
            'label' => 'group_db_1 allowed=be_users,be_groups description',
            'description' => 'field description',
            'config' => [
                'type' => 'group',
                'allowed' => 'be_users,be_groups',
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

elementBrowser ¶

Type

array

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']

Scope

fieldControl

Types

group

The element browser field control used in type='group' renders a button to open an element browser. It is enabled by default if rendering a group element.

insertClipboard ¶

Type

array

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldControl']

Scope

fieldControl

Types

group

The clipboard control adds a control button for type='group' to paste records from a users clipboard into the selection. It is enabled by default for type='group' and shown below the element browser if the order has not been changed using the before and after keywords. It can be turned off by setting disabled to true, just like any other fieldControl.

Example: Group field with element browser enabled

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_group.php

[
    'columns' => [
        'group_db_1' => [
            'label' => 'group_db_1 allowed=be_users,be_groups description',
            'description' => 'field description',
            'config' => [
                'type' => 'group',
                'allowed' => 'be_users,be_groups',
                'fieldControl' => [
                    'editPopup' => [
                        'disabled' => false,
                    ],
                    'addRecord' => [
                        'disabled' => false,
                    ],
                    'listModule' => [
                        'disabled' => false,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

Example: Group field with element browser disabled

The element browser control can be disabled by setting disabled = true:

EXT:styleguide/Configuration/TCA/tx_styleguide_elements_group.php

[
    'columns' => [
        'group_db_3' => [
            'label' => 'group_db_3 allowed=tx_styleguide_staticdata, disabled elementBrowser',
            'config' => [
                'type' => 'group',
                'allowed' => 'tx_styleguide_staticdata',
                'fieldControl' => [
                    'elementBrowser' => [
                        'disabled' => true,
                    ],
                ],
            ],
        ],
    ],
]

Copied!

fieldInformation ¶

For details see fieldInformation.

fieldWizard ¶

For general fieldWizard documentation see here.

recordsOverview ¶

Type

array

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']

Scope

fieldWizard

Render an overview of the selected records with correct icon and click menu and title. Allows to perform actions on the selected records directly. Links the record title to a direct editing form.

tableList ¶

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']

type

array

Scope

fieldWizard

Render a list of allowed tables and link to element browser. This field wizard is enabled by default. This wizard allows to easily select records from a popup.

filter ¶

Type

array

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Proc. / Display

Define filters for item values. Doesn't work in combination with a wizard.

This is useful when only foreign records matching certain criteria should be allowed to be used as values in the group field. The values are filtered in the Element Browser as well as during processing in DataHandler. Filter userFuncs should have two input arguments ($parameters and $parentObject). The first argument ($parameters) is an array with the parameters of the filter as configured in the TCA, but with the additional parameter "values", which contains the array of values which should be filtered by the userFunc. The function must return the filtered array of values.

Note

Do not confuse the filter values with the page tree selector on the left side. To change the entry page in the navigation use elementBrowserEntryPoints instead.

Multiple filters can be defined, and an array of configuration data for each of the filters can be supplied:

'filter' => [
    [
        'userFunc' => \Vendor\Extension\MyClass::class . '->doFilter',
        'parameters' => [
            // optional parameters for the filter go here
        ],
    ],
    [
        'userFunc' => \Vendor\Extension\OtherClass::class . '->myFilter',
        'parameters' => [
            // optional parameters for the filter go here
        ],
    ],
],

Copied!

Say you have a "person" table with fields "gender" (radio buttons) as well as "mother" and "father", both group fields with relations to the same table.

Now, in the field "mother" it should certainly only be possible to create relations to female persons. In that case, you could use the filter functionality to make sure only females can be selected in that field.

The field configuration for the "mother" field could look like:

'mother' => [
    'label' => 'Mother',
    'config' => [
        'type' => 'group',
        'allowed' => 'tx_myext_person',
        'size' => 1,
        'filter' => [
            [
                'userFunc' => \Vendor\Extension\MyClass::class . '->doFilter',
                'parameters' => [
                    'evaluateGender' => 'female',
                ],
            ],
        ],
    ]
],

The corresponding filter class would look like:

class MyClass
{
    public function doFilter(array $parameters, $parentObject)
    {
        $fieldValues = $parameters['values'];
        // do the filtering here
        return $fieldValues;
    }
}

foreign_table ¶

Type

string (table name)

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Proc. / Display

This property does not really exist for group-type fields. It is needed as a workaround for an Extbase limitation. It is used to resolve dependencies during Extbase persistence. It should hold the same values as property allowed. Notice that only one table name is allowed here in contrast to the property allowed itself.

hideMoveIcons ¶

Type

boolean

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Display

Removes the move icons next to the selector box.

hideSuggest ¶

Type

boolean

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Display

The "suggest wizard" is added by default to all database relation group fields. After a couple of characters have been typed into this field, an ajax based search starts and shows a list of records matching the search word.

The syntax for the search is: "multiple words" something, so you can enclose words you want to find next to each other in double quotes.

A set of options is available to configure search details.

Setting this property to true disables the suggest wizard.

[
    'columns' => [
        'group_db_11' => [
            'label' => 'group_db_11 hideSuggest=true allowed=tx_styleguide_staticdata, multiple, autoSizeMax=10',
            'config' => [
                'type' => 'group',
                'hideSuggest' => true,
                'allowed' => 'tx_styleguide_staticdata',
                'multiple' => true,
                'autoSizeMax' => 10,
            ],
        ],
    ],
]

[
    'columns' => [
        'group_db_8' => [
            'label' => 'group_db_8 allowed=tx_styleguide_staticdata, multiple',
            'config' => [
                'type' => 'group',
                'hideSuggest' => false,
                'allowed' => 'tx_styleguide_staticdata',
                'multiple' => true,
            ],
        ],
    ],
]

maxitems ¶

Type

integer > 0

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Display / Proc.

Maximum number of child items. Defaults to a high value. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

minitems ¶

Type

integer > 0

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Display

Minimum number of child items. Defaults to 0. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

MM ¶

Type

string (table name)

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Proc.

This value contains the name of the table in which to store a MM relation. It is used together with allowed (group). If you use Extbase, foreign_table has to contain the same table name additionally.

The database field with a MM property only stores the number of records in the relation.

Please have a look into the additional information in the MM common property description.

The table name used in the field MM should be unique. It must be a valid SQL table name. It is best practise to use the name of both referenced tables and of the field in which the reference is saved on local side. See also naming conventions for mm tables. This way uniqueness can be ensured and it is possible to find the field where the table is used quickly.

Example:

// table tx_myextension_domain_model_mymodel1
$fields = [
    'relation_table1_table2' => [
        'label' => 'Some relation from table 1 to table 2',
        'config' => [
            'type' => 'group',
            'allowed' => 'tx_myextension_domain_model_mymodel2',
            'foreign_table' => 'tx_myextension_domain_model_mymodel2', // needed by Extbase
            'MM' => 'tx_myextension_domain_model_mymodel1_mymodel2_mm',
        ],
    ],
];

Copied!

MM_match_fields ¶

Type

array

Scope

Display / Proc.

Array of field => value pairs to both insert and match against when writing/reading MM relations.

MM_opposite_field ¶

Type

string (field name)

Scope

Proc.

If you want to make a MM relation editable from the foreign side (bidirectional) of the relation as well, you need to set MM_opposite_field on the foreign side to the field name on the local side.

For example, 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".

Note

Bidirectional references only get registered once on the native side in sys_refindex.

MM_oppositeUsage ¶

Type

array

Scope

Proc.

In a MM bidirectional relation using group match fields the opposite side needs to know about the match fields for certain operations (for example, when a copy is created in a workspace) so that relations are carried over with the correct information.

MM_oppositeUsage is an array which references which fields contain the references to the opposite side, so that they can be queried for match field configuration.

MM_table_where ¶

Type

string (SQL WHERE)

Scope

Proc.

Additional where clause used when reading MM relations.

Example:

{#uid_local} = ###THIS_UID###

Copied!

The above example uses the special field quoting syntax {#...} around identifiers to be as DBAL-compatible as possible.

MM_hasUidField ¶

Changed in version 13.0

This setting is obsolete. Remove all occurrences of MM_hasUidField from TCA. The uid column is added as primary key automatically, if multiple = true is set, otherwise a combined primary key of fields uid_local, uid_foreign plus eventually tablenames and fieldname is used.

prepend_tname ¶

Type

boolean

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Proc.

Will prepend the table name to the stored relations (so instead of storing "23" you will store e.g. "tt_content_23"). This is automatically turned on if multiple different tables are allowed for one relation.

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.

Warning

This property affects only the display. It is still possible to write to those fields when using the DataHandler.

size ¶

Type

integer

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Display

The minimum size (height) of the select field.

The size of the select field will be automatically adjusted based on the number of selected items. The select field will never be smaller than the specified size and never larger than the value of autoSizeMax.

suggestOptions ¶

Type

array

Path

$GLOBALS['TCA'][$table]['columns'][$field]['config']

Scope

Display

Optional, additional suggest options used if the suggest wizard is not hidden. The suggest wizard options can also be overriden on a page TSconfig level.

Suggestions can be configured differently for each table. Settings in "default" are applied to all tables. In the example below, there is a special setting for the "pages" table to search only standard pages.

'related_records' => [
    'label' => 'Related records',
    'config' => [
        'type' => 'group',
        'allowed' => 'pages, tt_content',
        'suggestOptions' => [
            'default' => [
                'searchWholePhrase' => 1
            ],
            'pages' => [
                'searchCondition' => 'doktype = 1'
            ]
        ]
    ]
],

Copied!

additionalSearchFields (string)

Comma-separated list of fields the suggest wizard should also search in. By default the wizard looks only in the fields listed in the label and label_alt of TCA ctrl properties.

addWhere (string)

Allows to define an additional where clause for the searchquery. It supplies a marker for ###THIS_UID### which is useful to exclude the current record.

Note

Basically identical to 'searchCondition' - one will vanish sooner or later.

cssClass (string)

Add a CSS class to every list item of the result list.

maxItemsInResultList (integer)

Maximum number of results to display, default is 10.

maxPathTitleLength (integer)

Maximum number of characters to display when a path element is too long.

minimumCharacters (integer)

Minimum number of characters needed to start the search. Works only in "default" configuration array.

orderBy (string)

Allows to add an ORDER BY part to the search query.

pidList (list of values)

Limit the search to certain pages (and their sub pages). When pidList is empty all pages will be included in the search (as long as the be_user is allowed to see them).

Example

'storage_pid' => [
   'config' => [
      'suggestOptions' => [
         'default' => [
            'pidList' => '1,2,3,45',
         ],
      ],
   ],
],

Copied!

pidDepth (integer)

Expand pidList by this number of levels. Has an effect only if pidList has a value.

Example

'storage_pid' => [
   'config' => [
      'suggestOptions' => [
         'default' => [
            'pidList' => '6,7',
            'pidDepth' => 4
         ],
      ],
   ],
],

Copied!

receiverClass (string)

PHP class alternative receiver class, default is TYPO3\\CMS\\Backend\\Form\\Wizard\\SuggestWizardDefaultReceiver. Can be used to implement an own search strategy.

renderFunc (string)

User function to manipulate the displayed records in the results.

searchCondition (string)

Additional WHERE clause (not prepended with AND).

Note

Basically identical to 'addWhere' - one will vanish sooner or later.

Example

'storage_pid' => [
   'config' => [
      'suggestOptions' => [
         // configures the suggest wizard for the field "storage_pid"
         // in table "pages" to search only for pages with doktype=1
         'pages' => [
            'searchCondition' => 'doktype=1',
         ],
      ],
   ],
],

Copied!

searchWholePhrase (boolean)

Whether to do a LIKE=%mystring% (searchWholePhrase = 1) or a LIKE=mystring% (to do a real find as you type), default is 0.

Example

'storage_pid' => [
   'config' => [
      'suggestOptions' => [
         'default' => [
            'searchWholePhrase' => 1,
         ],
      ],
   ],
],

Copied!

[
    'columns' => [
        'group_db_10' => [
            'label' => 'group_db_10 allowed=pages size=1',
            'config' => [
                'type' => 'group',
                'allowed' => 'pages',
                'maxitems' => 1,
                'minitems' => 0,
                'size' => 1,
                'suggestOptions' => [
                    'default' => [
                        'additionalSearchFields' => 'nav_title, url',
                        'addWhere' => 'AND pages.doktype = 1',
                    ],
                ],
            ],
        ],
    ],
]