Attention

TYPO3 v8 has reached its end-of-life March 31st, 2020 and is not maintained by the community anymore. Looking for a stable version? Use the version switch on the top left.

There is no further ELTS support. It is recommended that you upgrade your project and use a supported version of TYPO3.

type = 'group'¶

Introduction¶

The group element in TYPO3 makes it possible to create references to records from multiple tables in the system. This is especially useful (compared to the "select" type) when records are scattered over the page tree and require the Element Browser to be selected.

Next to database relations, the group type is also able to handle files. Using type='group' for file handling however is considered outdated and should be based on the FAL API instead, and it can be assumed that internal_type='file' and internal_type='file_reference' will be removed sooner or later.

For database relations however, the type='group' field is the right and a powerful choice especially if dealing with lots of re-usable child records, and if type='inline' is not suitable.

This type is very flexible in its display options with all its different fieldControl and fieldWizard options. A lot of them are available by default but disabled.

Examples¶

Group relation to a single page (group_db_single)¶

Group relation to be_groups and be_users with some selected records (group_db_1)¶

Group file relation with some selected files (group_file_1)¶

'group_db_single' => [
   'label' => 'group_db_1 allowed=pages size=1',
   'config' => [
      'type' => 'group',
      'internal_type' => 'db',
      'allowed' => 'pages',
      'maxitems' => 1,
      'minitems' => 0,
      'size' => 1,
      'default' => 0,
      'suggestOptions' => [
         'default' => [
            'additionalSearchFields' => 'nav_title, alias, url',
            'addWhere' => 'AND pages.doktype = 1'
         ]
      ]
   ]
]

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

'group_file_1' => [
    'exclude' => 1,
    'label' => 'group_file_1',
    'config' => [
        'type' => 'group',
        'internal_type' => 'file',
        'allowed' => 'jpg, jpeg, png, gif',
        'disallowed' => 'ai',
        'size' => 3,
        'uploadfolder' => 'uploads/tx_styleguide/',
        'max_size' => 2000,
    ],
],

Properties renderType default¶

allowed¶

Datatype

string (list)

Scope

Proc. / Display

Description

For the "file" internal type (Optional):: A lowercase comma list of file extensions that are permitted, eg. 'jpg,gif,txt'. Also see disallowed.
For the "db" internal type (Required!):: 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.

appearance¶

Datatype

array

Scope

Display

Description

Options for refining the appearance of group-type fields.

elementBrowserType (string): Allows set an alternative element browser type ("db" or "file") than would otherwise be rendered based on the "internal_type" setting. This is used internally for FAL file fields, where internal_type is "db" but the element browser should be the file element browser anyway.
elementBrowserAllowed (string): Makes it possible to set an alternative element browser allowed string than would otherwise be taken from the "allowed" setting of this field. This is used internally for FAL file fields, where this is used to supply the comma list of allowed file types.

autoSizeMax¶

Datatype: integer
Scope: Display
Description: If set, then the height of element listing selector box will automatically be adjusted to the number of selected elements, however never less than "size" and never larger than the integer value of "autoSizeMax" itself (takes precedence over "size"). So "autoSizeMax" is the maximum height the selector can ever reach.

behaviour¶

Datatype: array
Scope: Proc.
Description: The behaviour array contains various sub properties to specify processing options like localization overlay behaviour and children behaviour for relation types. Available properties vary by type and renderType combination.

allowLanguageSynchronization

| Scope: Proc. | Type: boolean | Default: false |

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.

default¶

Datatype: integer / string
Scope: Display / Proc.
Description: Default value set if a new record is created.

disallowed¶

Datatype

string (list of)

Scope

Proc. / Display

Description

Only with internal_type='file'

Default value is '*' which means that anything file-extension which is not allowed is denied.

If you set this value (to for example "php,inc") AND the "allowed" key is an empty string all extensions are permitted except ".php" and ".inc" files (works like the [BE][fileExtensions] configuration option).

In other words:

If you want to permit only certain file-extensions, use 'allowed' and not disallowed.
If you want to permit all file-extensions except a few, set 'allowed' to blank ("") and enter the list of denied extensions in 'disallowed'.
If you wish to allow all extensions with no exceptions, set 'allowed' to '*' and disallowed to ''

dontRemapTablesOnCopy¶

Datatype

string (list of tables)

Scope

Proc.

Description

Only with internal_type='db'

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.

fieldControl¶

Datatype: array
Scope: Display
Description: Show action buttons next to the element. This is used in various type's to add control buttons right next to the main element. They can open popus, switch the entire view and other things. All must provide a "button" icon to click on, see FormEngine docs for more details. See type=group for examples.

addRecord¶

Datatype

array

Scope

fieldControl

Description

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 muliple tables are allowed, the first table from the allowed list is selected, if not 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.

Options:

pid (string)

pid of the new record. Can be an hard pid setting, or one of these markers, see select foreign_table_where. Falls back to "current pid" if not set, forces pid=0 if records of this table are only allowed on root level.

###CURRENT_PID###

###THIS_UID###

###SITEROOT###

###PAGE_TSCONFIG_ID###

###PAGE_TSCONFIG_IDLIST###

###PAGE_TSCONFIG_STR###

table (string): Add a record to this table, falls back to first table from allowed list if not set for type='group' fields and to foreign_table for type='select' fields.
title (string or LLL reference): Allows to set a different 'title' attribute to the popup icon, defaults to LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.createNew
setValue (string, keyword): Can be one of 'set', 'prepend' or 'append'. With 'set' the given selection is substituted with the new record, 'prepend' adds the new record on top of the list, 'append' adds it at the bottom. Default: 'append'.

Add a new record icon¶

Add a new record view¶

editPopup¶

Datatype

array

Scope

fieldControl

Description

The edit popup field control gives a shortcut to edit referenced elements directly a popup. When a record is selected and the edit button is clicked, that record opens in a new window for modification.

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.

Options:

title (string or LLL reference): Allows to set a different 'title' attribute to the popup icon, defaults to LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.edit
windowOpenParameters (string): Allows to set a different size of the popup, defaults to height=800,width=600,status=0,menubar=0,scrollbars=1.

Edit a related record directly thanks to the Edit wizard¶

Example

'myField' => [
    'type' => 'group',
    // ...
    'config' => [
        'fieldControl' => [
            'editPopup' => [
                'disabled' => false,
                'options' => [
                    'title' => 'Edit a selected record!',
                ],
            ],
        ],
    ],
],

elementBrowser¶

Datatype

array

Scope

fieldControl

Description

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

Open element browser popup (group_folder_1)¶

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

'myField' => [
    'config' => [
        'fieldControl' => [
            'elementBrowser' => [
                'disabled' => true,
            ],
        ],
    ],
],

insertClipboard¶

Datatype: array
Scope: fieldControl
Description: 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.

The clipboard control below the insert record control¶

listModule¶

Datatype

array

Scope

fieldControl

Description

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

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.

Options:

pid (string)

pid of the new record. Can be an hard pid setting, or one of these markers, see select foreign_table_where. Falls back to "current pid" if not set, forces pid=0 if records of this table are only allowed on root level.

###CURRENT_PID###
###THIS_UID###
###SITEROOT###
###PAGE_TSCONFIG_ID###
###PAGE_TSCONFIG_IDLIST###
###PAGE_TSCONFIG_STR###

table (string)

List records of this table only, falls back to first table from allowed list if not set for type='group' fields and to foreign_table for type='select' fields.

title (string or LLL reference)

Allows to set a different 'title' attribute to the popup icon, defaults to LLL:EXT:lang/Resources/Private/Language/locallang_core.xlf:labels.list

fieldInformation¶

Datatype: array
Scope: Display
Description: Show information between an element label and the main element input area. Configuration works identical to the "fieldWizard" property, no default configuration in the core exists (yet). In contrast to "fieldWizard", HTML returned by fieldInformation is limited, see FormEngine docs for more details.

fieldWizard¶

Datatype

array

Scope

Display

Description

Specifies wizards rendered below the main input area of an element. Single type / renderType elements can register default wizards which are merged with this property.

As example, type='check' comes with this default wizards configuration:

protected $defaultFieldWizard = [
    'localizationStateSelector' => [
        'renderType' => 'localizationStateSelector',
    ],
    'otherLanguageContent' => [
        'renderType' => 'otherLanguageContent',
        'after' => [
            'localizationStateSelector'
        ],
    ],
    'defaultLanguageDifferences' => [
        'renderType' => 'defaultLanguageDifferences',
        'after' => [
            'otherLanguageContent',
        ],
    ],
];

This is be merged with the configuration from TCA, if there is any. Below example disables the default localizationStateSelector wizard.

'aField' => [
    'config' => [
        'fieldWizard' => [
            'localizationStateSelector' => [
                'disabled' => true,
            ],
        ],
    ],
],

It is possible to add own wizards by adding them to the TCA of the according field and pointing to a registered renderType, to resort wizards by overriding the before and after keys, to hand over additional options in the optional options array to specific wizards, and to disable single wizards using the disabled key. Developers should have a look at the FormEngine docs for details.

defaultLanguageDifferences¶

Datatype

array

Scope

fieldWizard

Description

Show a "diff-view" if the content of the default language record has been changed after the translation overlay has been created. The ['ctrl'] section property transOrigDiffSourceField has to be specified to enable this wizard in a translated record.

This wizard is important for editors who maintain translated records: They can see what has been changed in their localization parent between the last save operation of the overlay.

A field has been changed in default language record¶

fileThumbnails¶

Datatype

array

Scope

fieldWizard

Description

Only with internal_type='file' and internal_type='file_reference'

This field wizard renders the selected files as thumb nails below the main input field.

fileTypeList¶

Datatype

array

Scope

fieldWizard

Description

Only with internal_type='file'

Render a list of allowed file extensions. Enabled by default with type='group' and internal_type='file'.

fileUpload¶

Datatype

array

Scope

fieldWizard

Description

Only with internal_type='file'

Renders a direct file upload button if property uploadfolder is set.

localizationStateSelector¶

Datatype

array

Scope

fieldWizard

Description

The localization state selector wizard displays two or three radio buttons in localized records saying: "This field has an own value distinct from my default language or source record", "This field has the same value as the default language record" or "This field has the same value as my source record". This wizard is especially useful for the tt_content table. It will only render, if:

The record is a localized record (not default language)
The record is in "translated" (connected), but not in "copy" (free) mode
The table is localization aware using the ['ctrl'] properties languageField, transOrigPointerField. If the optional property translationSource is also set, and if the record is a translation from another localized record, the third radio appears.
The property ['config']['behaviour']['allowLanguageSynchronization'] is set to true

Example localization state selector on a type=input field

Example localization state selector on an type=input field¶

recordsOverview¶

Datatype

array

Scope

fieldWizard

Description

Only with internal_type='db'

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¶

Datatype

array

Scope

fieldWizard

Description

Only with internal_type='db'

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.

otherLanguageContent¶

Datatype

array

Scope

fieldWizard

Description

Show values from the default language record and other localized records if the edited row is a localized record. Often used in tt_content fields. By default, only the value of the default language record is shown, values from further translations can be shown by setting the userTsConfig property additionalPreviewLanguages.

The wizard shows content only for "simple" fields. For instance, it does not work for database relation fields, and if the field is set to readOnly. Additionally, the table has to be language aware by setting up the according fields in ['ctr'] section.

Header field showing values from two other languages¶

filter¶

Datatype

array

Scope

Proc. / Display

Description

Only with internal_type='db'

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.

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' => 'userFunc' => Vendor\\Extension\\OtherClass::class . '->myFilter',
        'parameters' => [
            // optional parameters for the filter go here
        ],
    ],
],

Example

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',
        'internal_type' => 'db',
        '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¶

Datatype: string (table name)
Scope: Proc. / Display
Description: 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¶

Datatype: boolean
Scope: Display
Description: Removes the move icons next to the selector box.

hideSuggest¶

Datatype

boolean

Scope

Display

Description

Only with internal_type='db'

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.

A set of options is available to configure search details.

Setting this property to true disables the suggest wizard.

Suggest wizard showing some suggestions¶

internal_type¶

Datatype

string

Scope

Display / Proc.

Description

Required!

Configures the internal type of the "group" type of element. There are four possible options to choose from:

file: This will create a field where files can be attached to the record.
file_reference: This will create a field where files can be referenced. In contrast to "file", referenced files (usually from fileadmin/) will not be copied to the upload folder. Warning: use this carefully. Your references will be broken if you delete referenced files in the filesystem!
folder: This will create a field where folders can be attached to the record.
db: This will create a field where database records can be attached as references.

The default value is none of them - you must specify one of the values correctly!

Important

Types "file" and "file_reference" should not be used anymore. Use FAL references instead.

localizeReferencesAtParentLocalization¶

Datatype: boolean
Scope: Proc.
Description: Defines whether referenced records should be localized when the current record gets localized. This does only apply if references are stored using MM tables.

max_size¶

Datatype

integer

Scope

Proc.

Description

Only with internal_type='file'

Maximum file size allowed in KB.

maxitems¶

Datatype: integer > 0
Scope: 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.

Note

Property maxitems is ignored with type='select' and renderType='selectSingle'.
Description: Display / Proc.

minitems¶

Datatype: integer > 0
Scope: Display
Description: Minimum number of child items. Defaults to 0. JavaScript record validation prevents the record from being saved if the limit is not satisfied.

MM¶

Datatype

string (table name)

Scope

Proc.

Description

Means that the relation to the records of foreign_table is done with a M-M relation with a third "join" table.

That table has three columns as a minimum:

uid_local, uid_foreign (Required)

Storing uids of both sides. If done right, this is reflected in the table name - tx_foo_local_foreign_mm

sorting (Required)

Is a required field used for ordering the items.

sorting_foreign

Is required if the relation is bidirectional (see description and example below table)

tablenames

Is used if multiple tables are allowed in the relation.

uid (auto-incremented and PRIMARY KEY)

May be used if you need the "multiple" feature (which allows the same record to be references multiple times in the box. See MM_hasUidField for type='select' and MM_hasUidField for type='group' fields.

further fields

May exist, in particular if MM_match_fields / MM_match_fields is involved in the set up.

Example SQL #1

Most simple MM table

CREATE TABLE tx_testmmrelations_one_rel_mm (
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign)
);

Example SQL #2

Advanced with uid field, "ident" used with MM_match_fields and "sorting_foreign" for bidirectional MM relations:

CREATE TABLE tx_testmmrelations_two_rel_mm (
    uid int(11) NOT NULL auto_increment,
    uid_local int(11) DEFAULT '0' NOT NULL,
    uid_foreign int(11) DEFAULT '0' NOT NULL,
    tablenames varchar(30) DEFAULT '' NOT NULL,
    sorting int(11) DEFAULT '0' NOT NULL,
    sorting_foreign int(11) DEFAULT '0' NOT NULL,
    ident varchar(30) DEFAULT '' NOT NULL,

    KEY uid_local (uid_local),
    KEY uid_foreign (uid_foreign),
    PRIMARY KEY (uid)
);

Value of field

The field name of the config is not used for data-storage anymore but rather it's set to the number of records in the relation on each update, so the field should be an integer.

MM relations and flexforms

MM relations has been tested to work with flexforms if not in a repeated element in a section.

Note

Using MM relations you can ONLY store real relations for foreign tables in the list - no additional string values or non-record values.

MM_insert_fields¶

Datatype: array
Scope: Proc.
Description: Array of field=>value pairs to insert when writing new MM relations.

MM_hasUidField¶

Datatype: boolean
Scope: Proc.
Description: If the "multiple" feature is used with MM relations you MUST set this value to true and include a UID field! Otherwise sorting and removing relations will be buggy.

MM_match_fields¶

Datatype: array
Scope: Display / Proc.
Description: Array of field=>value pairs to both insert and match against when writing/reading MM relations.

MM_opposite_field¶

Datatype

string (field name)

Scope

Proc.

Description

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.

E.g. 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¶

Datatype

array

Scope

Proc.

Description

In a MM bidirectional relation using select match fields / 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 whichfields contain the references to the opposite side, so that they can be queried for match field configuration.

This is used by the Core for system categories. Whenever a table is registered as being categorizable, an entry in MM_oppositeUsage is created for the "sys_category" table.

Example

With "pages", "tt_content" and "sys_file_metadata" all registered as categorizable (using the default name of "categories" for the relations field) plus extension "examples" installed, the TCA for "sys_category" contains the following definition once fully assembled:

$GLOBALS['TCA']['sys_category']['columns']['items']['config']['MM_oppositeUsage'] = [
    'pages' => ['tx_examples_cats', 'categories'],
    'sys_file_metadata' => ['categories'],
    'tt_content' => ['categories'],
];

MM_table_where¶

Datatype: string (SQL WHERE)
Scope: Proc.
Description: Additional where clause used when reading MM relations.

multiple¶

Datatype

boolean

Scope

Display / Proc.

Description

Allows the same item more than once in a list.

If used with bidirectional MM relations it must be set for both the native and foreign field configuration. Also, with MM relations in general you must use a UID field in the join table, see description for "MM".

prepend_tname¶

Datatype

boolean

Scope

Proc.

Description

Only with internal_type='db'

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¶

Datatype: boolean
Scope: Display
Description: Renders the field in a way that the user can see the values but cannot edit them. The rendering is as similar as possible to the normal rendering but may differ in layout and size.

Warning

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

size¶

Datatype

integer

Scope

Display

Description

Height of the box in FormEngine.

With type='select' and renderType='selectSingle', the default is 1, but if set to a number greater than 1, the select drop down will be displayed as box where only one item can be selected.

With type='select' and renderType='selectSingleBox', this value should not be set to a number smaller than 2.

With type='group', the "box" collapses to a single element input and should then be combined with a maxitems=1, the default is 5.

suggestOptions¶

Datatype

array

Scope

Display

Description

Only with internal_type='db'

Optional, additional suggest options used if the suggest wizard is not hidden.

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',
        'internal_type' => 'db',
        'allowed' => 'pages, tt_content',
        'suggestOptions' => [
            'default' => [
                'searchWholePhrase' => 1
            ],
            'pages' => [
                'searchCondition' => 'doktype = 1'
            ]
        ]
    ]
],

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',
            ],
        ],
    ],
],

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
            ],
        ],
    ],
],

minimumCharacters (integer)

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

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.

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,
            ],
        ],
    ],
],

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',
            ],
        ],
    ],
],

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

orderBy (string)

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

cssClass (string)

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

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.

uploadfolder¶

Datatype

string

Scope

Proc.

Description

Only with internal_type='db'

Path to folder under PATH_site in which the files are stored, 'uploads/tx_myextension'.

Note

TYPO3 does NOT create a reference to the file in its original position! It makes a copy of the file into this folder and from that moment that file is not supposed to be manipulated from outside. Being in the upload folder means that files are understood as a part of the database content and should be managed by TYPO3 only.

Warning

Do NOT add a trailing slash (/) to the upload folder otherwise the full path stored in the references will contain a double slash (e.g. "uploads/pictures//stuff.png").

Stored data values¶

Note

This structural in-depth study should probably be moved elsewhere and cleaned up since it contains some invalid information.

Since the "group" element allows to store references to multiple elements we might want to look at how these references are stored internally.

Storage methods¶

There are two main methods for this:

Stored in a comma list
Stored with a join table (MM relation)

The default and most wide spread method is the comma list.

Reserved tokens¶

In the comma list the token "," is used to separate the values. In addition the pipe sign "|" is used to separate value from label value when delivered to the interface. Therefore these tokens are not allowed in reference values, not even if the MM method is used.

The "Comma list" method (default)¶

When storing references as a comma list the values are simply stored one after another, separated by a comma in between (with no space around!). The database field type is normally a varchar, text or blob field in order to handle this.

From the examples above the four Content Elements will be stored as "26,45,49,1" which is the UID values of the records. The images will be stored as their filenames in a list like "DSC_7102_background.jpg ,DSC_7181.jpg,DSC_7102_background_01.jpg".

Since "db" references can be stored for multiple tables the rule is that uid numbers without a table name prefixed are implicitly from the first table in the allowed table list! Thus the list "26,45,49,1" is implicitly understood as "tt_content_26,tt_content_45,tt_content_49,tt_content_1". That would be equally good for storage, but by default the "default" table name is not prefixed in the stored string. As an example, lets say you wanted a relation to a Content Element and a Page in the same list. That would look like "tt_content_26,pages_123" or alternatively "26,pages_123" where "26" implicitly points to a "tt_content" record given that the list of allowed tables were "tt_content,pages".

The "MM" method¶

Using the MM method you have to create a new database table which you configure with the key "MM". The table must contain a field, "uid_local" which contains the reference to the uid of the record that contains the list of elements (the one you are editing). The "uid_foreign" field contains the uid of the reference record you are referring to. In addition a "tablename" and "sorting" field exists if there are references to more than one table.

Lets take the examples from before and see how they would be stored in an MM table:

uid_local	uid_foreign	tablename	sorting
[uid of the record you are editing]	26	tt_content	1
[uid of the record you are editing]	45	tt_content	2
[uid of the record you are editing]	49	tt_content	3
[uid of the record you are editing]	1	tt_content	4

Or for "tt_content_26,pages_123":

uid_local	uid_foreign	tablename	sorting
[uid of the record you are editing]	26	tt_content	1
[uid of the record you are editing]	123	pages	2

Or for "DSC_7102_background.jpg,DSC_7181.jpg,DSC_7102_background_01.jpg":

uid_local	uid_foreign	tablename	sorting
[uid of the record you are editing]	DSC_7102_background.jpg	N/A	1
[uid of the record you are editing]	DSC_7181.jpg	N/A	2
[uid of the record you are editing]	DSC_7102_background_01.jpg	N/A	3

API for getting the reference list¶

Class TYPO3\CMS\Core\Database\RelationHandler is designed to transform the stored reference list values into an array where all uids are paired with the right table name. Also, this class will automatically retrieve the list of MM relations. In other words, it provides an API for getting the references from "group" elements into a PHP array regardless of storage method.

Managing file references¶

When a new file is attached to a record the TCE will detect the new file based on whether it has a path prefixed or not. New files are copied into the upload folder that has been configured and the final value list going into the database will contain the new filename of the copy.

If images are removed from the list that is detected by simply comparing the original file list with the one submitted. Any files not listed anymore are deleted.

Examples:

Current DB value	Data from FormEngine	New DB value	Processing done
first.jpg,second.jpg	first.jpg,/www/typo3/fileadm in/newfile.jpg,second.jpg	first.jpg,newfile_01.jpg,second.jpg	/www/typo3/fileadmin/newfile.jpg was copied to "uploads/[some- dir]/newfile_01.jpg". The filename was appended with "_01" because another file with the name "newfile.jpg" already existed in the location.
first.jpg,second.jpg	first.jpg	first.jpg	"uploads/[some-dir]/second.jpg" was deleted from the location.