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

Insert records content element

The "Insert records" content element with 3 elements referenced

Properties

Property Data Type
allowed string
appearance array
autoSizeMax integer
disable_controls string
disallowed string
dontRemapTablesOnCopy string
filter array
foreign_table string
internal_type string
max_size integer
maxitems integer
minitems integer
MM string
MM_hasUidField boolean
MM_insert_fields array
MM_match_fields array
MM_opposite_field string
MM_oppositeUsage array
MM_table_where string
multiple boolean
prepend_tname boolean
selectedListStyle string
show_thumbs boolean
size integer
type string
uploadfolder string
wizards array

Property details

type

Key

type

Datatype

string

Description

[Must be set to "group"]

Scope

Display / Proc.

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.

See MM property of select-type fields.

Scope

Proc.

MM_opposite_field

Key

MM_opposite_field

Datatype

string

(field name)

Scope

Proc.

MM_match_fields

Key

MM_match_fields

Datatype

array

Scope

Proc.

MM_oppositeUsage

Key

MM_oppositeUsage

Datatype

array

Scope

Proc.

MM_insert_fields

Key

MM_insert_fields

Datatype

array

Scope

Proc.

MM_table_where

Key

MM_table_where

Datatype

string (SQL WHERE)

Scope

Proc.

MM_hasUidField

Key

MM_hasUidField

Datatype

boolean

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?

hideMoveIcons

Key

hideMoveIcons

Datatype

boolean

Description

Removes the move icons next to the selector box.

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 controls

Disabling the various controls

Scope

Display / Proc.

wizards

Key

wizards

Datatype

array

Description

See the wizards section for more information.

Scope

Display

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

Insert records content element

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

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

It is possible to use FAL references in a group-type field, although using them with inline-type fields allows for richer references (as there can be additional fields in the relation in that case).

Here is an example taken from the "examples" extension:

'image_fal_group' => array(
        'label' => 'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tx_examples_haiku.image_fal_group',
        'config' => array(
                'type' => 'group',
                'internal_type' => 'db',
                'allowed' => 'sys_file',
                'MM' => 'sys_file_reference',
                'MM_match_fields' => array(
                        'fieldname' => 'image_fal_group'
                ),
                'prepend_tname' => TRUE,
                'appearance' => array(
                        'elementBrowserAllowed' => $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext'],
                        'elementBrowserType' => 'file'
                ),
                'max_size' => $GLOBALS['TYPO3_CONF_VARS']['BE']['maxFileSize'],
                'show_thumbs' => '1',
                'size' => '3',
                'maxitems' => '200',
                'minitems' => '0',
                'autoSizeMax' => 40,
        ),
),

Note

It is also possible to create relations directly to the "sys_file" table by not using MM information.

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.

Todo

Undefined:

t3cmsapi:typo3\cms\backend\form\datapreprocessor

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.