Attention
TYPO3 v6 has reached its end-of-life April 18th, 2017 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 strongly recommended updating your project.
TYPE: "group"¶
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. In this example, Content Element records are attached (taken from the "Insert records" content element):

The "Insert records" content element with 3 elements referenced¶
Properties¶
Property |
Data Type |
---|---|
string |
|
array |
|
integer |
|
string |
|
string |
|
string |
|
array |
|
string |
|
string |
|
integer |
|
integer |
|
integer |
|
string |
|
boolean |
|
array |
|
array |
|
string |
|
array |
|
string |
|
boolean |
|
boolean |
|
string |
|
boolean |
|
integer |
|
string |
|
string |
|
array |
Property details¶
internal_type¶
Key
internal_type
Datatype
string
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 since TYPO3 CMS 6.0. You should use FAL references instead (see example).
Scope
Display / Proc.
allowed¶
Key
allowed
Datatype
string
(list of)
Description
For the "file" internal type (Optional):
A lowercase comma list of file extensions that are permitted. E.g. 'jpg,gif,txt'. Also see 'disallowed'.
For the "db" internal type (Required!):
A comma list of tables from $TCA.
For example the value could be "pages,be_users".
Value from these tables are always the 'uid' field.
First table in list is understood as the default table , if a table-name is not prepended to the value.
If the value is '*' then all tables are allowed (in this case you should set "prepend_tname" so all tables are prepended with their table name for sure).
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.
Scope
Proc. / Display
disallowed¶
Key
disallowed
Datatype
string
(list of)
Description
[internal_type = "file" ONLY]
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 ''
Scope
Proc. / Display
filter¶
Key
filter
Datatype
array
Description
(Available since TYPO3 CMS 6.0)
[internal_type = "db" ONLY]
Define filters for item values.
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 TCEMain. 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' => array (
array(
'userFunc' => 'EXT:myext/class.tx_myext_filter.php:tx_myext_filter->doFilter',
'parameters' => array(
// optional parameters for the filter go here
),
),
array(
'userFunc' => 'EXT:foo/class.tx_foo_filter.php:tx_foo_filter->myFilter',
'parameters' => array(
// 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' => array (
'label' => 'Mother',
'config' => array (
'type' => 'group',
'internal_type' => 'db',
'allowed' => 'tx_myext_person',
'size' => 1,
'filter' => array (
array(
'userFunc' => 'EXT:myext/class.tx_myext_filter.php:tx_myext_filter->doFilter',
'parameters' => array(
'evaluateGender' => 'female', ),
),
),
)
),
The corresponding filter class would look like:
class tx_myext_filter {
public function doFilter(array $parameters, $parentObject) {
$fieldValues = $parameters['values'];
// do the filtering here
...
return $fieldValues;
}
}
Scope
Proc. / Display
foreign_table¶
Key
foreign_table
Datatype
string
(table name)
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.
Scope
Proc. / Display
MM¶
Key
MM
Datatype
string
(table name)
Description
Defines MM relation table to use.
Means that the relation to the files/db is done with a M-M relation through a third "join" table.
A MM-table must have these four columns:
uid_local - for the local uid.
uid_foreign - for the foreign uid. If the "internal_type" is "file" then the "uid_foreign" should be a varchar or 60 or so (for the filename) instead of an unsigned integer as you would use for the uid.
tablenames - is required if you use multi-table relations and this field must be a varchar of approx. 30In case of files, the tablenames field is never used.
sorting - is a required field used for ordering the items.
Scope
Proc.
MM_opposite_field¶
Key
MM_opposite_field
Datatype
string
(field name)
Description
Scope
Proc.
MM_match_fields¶
Key
MM_match_fields
Datatype
array
Description
Scope
Proc.
MM_oppositeUsage¶
Key
MM_oppositeUsage
Datatype
array
Description
Scope
Proc.
MM_insert_fields¶
Key
MM_insert_fields
Datatype
array
Description
Scope
Proc.
MM_table_where¶
Key
MM_table_where
Datatype
string (SQL WHERE)
Description
Scope
Proc.
MM_hasUidField¶
Key
MM_hasUidField
Datatype
boolean
Description
Scope
Proc.
max_size¶
Key
max_size
Datatype
integer
Description
[internal_type = **file* ONLY]*
Files: Maximum file size allowed in KB
Scope
Proc.
uploadfolder¶
Key
uploadfolder
Datatype
string
Description
[internal_type = **file* ONLY]*
Path to folder under PATH_site in which the files are stored.
Example: 'uploads' or 'uploads/pictures'
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").
Scope
Proc.
prepend_tname¶
Key
prepend_tname
Datatype
boolean
Description
[internal_type = **db* ONLY]*
Will prepend the table name to the stored relations (so instead of storing "23" you will store e.g. "tt_content_23").
Scope
Proc.
dontRemapTablesOnCopy¶
Key
dontRemapTablesOnCopy
Datatype
string
(list of tables)
Description
[internal_type = **db* ONLY]*
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.
Scope
Proc.
show_thumbs¶
Key
show_thumbs
Datatype
boolean
Description
Show thumbnails for the field in the TCEform.
Scope
Display
size¶
Key
size
Datatype
integer
Description
Height of the selector box in TCEforms.
Since TYPO3 CMS 6.1, the default size is 5.
Scope
Display
autoSizeMax¶
Key
autoSizeMax
Datatype
integer
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.
Scope
Display
selectedListStyle¶
Key
selectedListStyle
Datatype
string
Description
If set, this will override the default style of element selector box (which is "width:200px").
Scope
Display
multiple¶
Key
multiple
Datatype
boolean
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".
Scope
Display / Proc.
maxitems¶
Key
maxitems
Datatype
integer > 0
Description
Maximum number of items in the selector box. (Default = 1)
Scope
Display / Proc?
minitems¶
Key
minitems
Datatype
integer > 0
Description
Minimum number of items in the selector box. (Default = 0)
Scope
Display / Proc?
disable_controls¶
Key
disable_controls
Datatype
string
Description
Disables sub-controls inside "group" control. Comma-separated list of values. Possible values are: browser (disables browse button for list control), list (disables list and browse button, but not delete button), upload (disables upload control) and delete (disables the delete button). See example image below.
Note
If you use the delete button when the list is disabled, all entries in the list will be deleted.

Disabling the various controls¶
Scope
Display / Proc.
appearance¶
Key
appearance
Datatype
array
Description
Options for refining the appearance of group-type fields.
elementBrowserType (string) (since TYPO3 CMS 6.0) Makes it possible to 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) (since TYPO3 CMS 6.0) 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.
Scope
Display
Examples¶
References to database records¶
The "Insert records" content element can be used to reference records from the "tt_content" table (and possibly others, like "tt_news" in the screenshot below):

The "Insert records" content element with 3 elements referenced¶
The corresponding TCA code:
'records' => array(
'label' => 'LLL:EXT:cms/locallang_ttc.xml:records',
'config' => array(
'type' => 'group',
'internal_type' => 'db',
'allowed' => 'tt_content',
'size' => '5',
'maxitems' => '200',
'minitems' => '0',
'show_thumbs' => '1',
'wizards' => array(
'suggest' => array(
'type' => 'suggest',
),
),
),
),
Note in particular how the "internal_type" of the group field is set to "db". Then the allowed tables is defined as "tt_content" (Content Elements table). This could very well be a list of tables which means you can mix references as you like!
The limit is set to a maximum of 200 references and thumbnails should be displayed, if possible. Finally a suggest wizard is added.
In this case it wouldn't have made sense to use a "select" type field since the situation implies that records might be found all over the system in a table which could potentially carry thousands of entries. In such a case the right thing to do is to use the "group" field so you have the Element Browser available for selector of the records.
Reference to another page¶
You will often see "group" type fields used when a reference to another page is required. This makes sense since pages can hardly be presented effectively in a big selector box and thus the Element Browser that follows the "group" type fields is useful. An example is the "General Record Storage page" reference:

The general storage page selector, with link browser icon and select wizard¶
The configuration looks like:
'storage_pid' => array(
'exclude' => 1,
'label' => 'LLL:EXT:lang/locallang_tca.xlf:storage_pid',
'config' => array(
'type' => 'group',
'internal_type' => 'db',
'allowed' => 'pages',
'size' => '1',
'maxitems' => '1',
'minitems' => '0',
'show_thumbs' => '1',
'wizards' => array(
'suggest' => array(
'type' => 'suggest'
)
)
)
),
Notice how "maxitems" is used to ensure that only one relation is created despite the ability of the "group" type field to create multiple references.
File Abstraction Layer¶
Be aware that you should never use FAL references in a group-type field / as an MM relation. While sys_file_reference looks similar as an MM table it is not - and you will experience unexpected behavior when using it. You should instead use FAL relations with inline-type fields.
Data format of "group" elements¶
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.
Passing the list of references to TCEforms¶
Regardless of storage method, the reference list has to be "enriched" with proper title values when given to TCEforms for rendering. In particular this is important for database records. Passing the list "26,45,49,1" will not give TCEforms a chance to render the titles of the records.
Class TYPO3\CMS\Backend\Form\DataPreprocessor is doing such transformations (among other things) and this is how the transformation happens:
Int. type |
In Database: |
When given to TCEforms: |
---|---|---|
"db" |
26,45,49,1 |
tt_content_26|%20adfs%20asdf%20asdf%20,tt_content_45|This%20is %20a%20test%20%28copy%203%29,tt_content_49|%5B... %5D,tt_content_1|%5B...%5D |
"file" |
DSC_7102_background.jpg,DSC_7181 |
DSC_7102_background.jpg|DSC_7102_background.jpg,DSC_7181.jpg| DSC_7181.jpg,DSC_7102_background_01.jpg| DSC_7102_background_01.jpg |
The syntax is:
[ref. value]|[ref. label rawurlencoded],[ref. value]|[ref. label rawurlencoded],....
Values are transferred back to the database as a comma separated list of values without the labels but if labels are in the value they are automatically removed.
Alternately you can also submit each value as an item in an array; TCEmain will detect an array of values and implode it internally to a comma list. (This is used for the "select" type, in renderMode "singlebox" and "checkbox").
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 |
Submitted data from TCEforms |
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. |