Attention

TYPO3 v9 has reached its end-of-life September 30th, 2021 and is not maintained by the community anymore. Looking for a stable version? Use the version switch on the top left.

You can order Extended Long Term Support (ELTS) here: TYPO3 ELTS.

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.

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.

It is required to set internal_type. Most common usage is to model database relations (n:1 or n:m) with internal_type='db'. In this case property allowed is required.

The group field uses either CSV format to store uids of related records or intermediate mm table (in this case MM property is required).

You can read more on how data is structured in Stored data values chapter.

Note

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 internal_type='file' and internal_type='file_reference' will be removed in TYPO3 version 10. To see an example on how to migrate these fields to FAL see the core change on Gerrit

Examples

Group relation to a single page

Group relation to a single page (group_db_single)

'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 relation to be_groups and be_users

Group relation to be_groups and be_users with some selected records (group_db_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 relation

Group file relation with some selected files (group_file_1)

Properties

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.

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

Deprecated since version 9.5: The internal types file and file_reference have been deprecated with TYPO3 9 and will be removed with TYPO3 10. Extensions that used group fields with these internal types should switch to use FAL references based on type=inline instead.

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.

behaviour => allowLanguageSynchronization

Datatype

boolean

Scope

Proc.

Description

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.

Example:

'aField' => [
   'config' => [
      'type' = 'sometype',
      'behaviour' => [
         'allowLanguageSynchronization' => true
      ]
   ]
]

Default

false

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

Deprecated since version 9.5: The internal types file and file_reference have been deprecated with TYPO3 9 and will be removed with TYPO3 10. Extensions that used group fields with these internal types should switch to use FAL references based on type=inline instead.

dontRemapTablesOnCopy

Datatype

string (list of tables)

Scope

Proc.

Description

If used with type='group', this is only considered 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.

The following fieldControls are available for this type:

fieldControl => 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 multiple 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###

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

fieldControl => 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!',
                ],
            ],
        ],
    ],
],

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

fieldControl => 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

fieldControl => 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###

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.

The following wizards are available for this type:

fieldWizard => 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

fieldWizard => 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.

fieldWizard => 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'.

Warning

The configuration of internal_type='file' is deprecated since TYPO3 v9 and should not be used.

fieldWizard => fileUpload

Datatype

array

Scope

fieldWizard

Description

Only with internal_type='file'

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

fieldWizard => 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 an type=input field

fieldWizard => 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.

fieldWizard => 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.

fieldWizard => 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 ['ctrl'] 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' => \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!

Deprecated since version 9.5: The internal types file and file_reference have been deprecated with TYPO3 9 and will be removed with TYPO3 10. Extensions that used group fields with these internal types should switch to use FAL references based on type=inline instead.

localizeReferencesAtParentLocalization

Datatype

boolean

Scope

Proc.

Description

Defines whether referenced records should be localized when the current record gets localized. This only applies if references are not stored using MM tables. In addition, when using the type group, foreign_table has to reference the same table in allowed.

max_size

Datatype

integer

Scope

Proc.

Description

Only with internal_type='file'

Maximum file size allowed in KB.

Deprecated since version 9.5: The internal types file and file_reference have been deprecated with TYPO3 9 and will be removed with TYPO3 10. Extensions that used group fields with these internal types should switch to use FAL references based on type=inline instead.

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 (or table specified in allowed property in case of the group field) is done with a M-M relation with a third "join" table.

The intermediate 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_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_insert_fields

Datatype

array

Scope

Proc.

Description

Array of field=>value pairs to insert when writing new MM relations.

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.

Example:

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

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

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

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

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

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

uploadfolder

Datatype

string

Scope

Proc.

Description

Only with internal_type='file'

Path to folder under \TYPO3\CMS\Core\Core\Environment::getPublicPath() 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").

Deprecated since version 9.5: The internal types file and file_reference have been deprecated with TYPO3 9 and will be removed with TYPO3 10. Extensions that used group fields with these internal types should switch to use FAL references based on type=inline instead.

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.