Core API

< 4.2.9. ['columns'][

Table Of Content

4.2.11. ['columns'][ >

4.2.10. ['columns'][fieldname]['config'] / 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 requires the Element Browser to be selected. In this example, Content Element records are attached:

The "group" element It is also the element you can use to bind files to records in TYPO3. In this case image files:

One thing to notice about attaching files is that the files are actually moved into an internal file folder for TYPO3! It doesn't merely create a reference to the files original position!

Key	Datatype	Description	Scope
type	string	[Must be set to "group"]	Display / Proc.
internal_type	string	Required! Configures the internal type of the "group" type of element. There are two options for a value: "file" - this will create a field where files 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!	Display / Proc.
allowed	string (list of)	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 $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).	Proc. / Display
disallowed	string (list of)	[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,php3") AND the "allowed" key is an empty string all extensions are permitted except* ".php" and ".php3" files (works like the [BE][fileExtensions] config option). In other words: If you want to permit only certain file-extentions, 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 ''	Proc. / Display
MM	string (table name)	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 multitable-relations and this field must be a varchar of approx. 30 In case of files, the tablenames field is never used. sorting - is a required field used for ordering the items. The fieldname of the config is not used for data-storage any more but rather it's set to the number of records in the relation on each update, so the field should be an integer. Sample SQL table definitions for MM relations look like: # # Example MM table for database relations # CREATE TABLE example_db_mm ( 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, KEY uid_local (uid_local), KEY uid_foreign (uid_foreign) ) TYPE=MyISAM; # # Example MM table for file attachments # CREATE TABLE example_files_mm ( uid_local int(11) DEFAULT '0' NOT NULL, uid_foreign varchar(60) DEFAULT '' NOT NULL, sorting int(11) DEFAULT '0' NOT NULL, KEY uid_local (uid_local), KEY uid_foreign (uid_foreign) ) TYPE=MyISAM;	Proc.
MM_opposite_field	string (field name)	see ['columns'][fieldname]['config'] / TYPE: "select" => MM_opposite_field	Proc.
MM_match_fields	array	see ['columns'][fieldname]['config'] / TYPE: "select" => MM_match_fields
MM_insert_fields	array	see ['columns'][fieldname]['config'] / TYPE: "select" => MM_insert_fields
MM_table_where	string (SQL WHERE)	see ['columns'][fieldname]['config'] / TYPE: "select" => MM_table_where
max_size	integer	[internal_type = file* ONLY]* Files: Maximum filesize allowed in KB	Proc.
uploadfolder	string	[internal_type = file* ONLY]* Filefolder under PATH_site in which the files are stored. Example: 'uploads' or 'uploads/pictures' Notice: 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.	Proc.
prepend_tname	boolean	[internal_type = db ONLY] Will prepend the table name to the stored relations (so instead of storing "23" you will store eg. "tt_content_23").	Proc.
dontRemapTablesOnCopy	string (list of tables)	[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.	Proc.
show_thumbs	boolean	Show thumbnails for the field in the TCEform	Display
size	integer	Height of the selectorbox in TCEforms.	Display
autoSizeMax	integer	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.	Display
selectedListStyle	string	If set, this will override the default style of element selector box (which is "width:200px").	Display
multiple	boolean	Allows the same item more than once in a list.	Display / Proc.
maxitems	integer > 0	Maximum number of items in the selector box. (Default = 1)	Display / Proc?
minitems	integer > 0	Minimum number of items in the selector box. (Default = 0)	Display / Proc?
wizards	array	[See section later for options]	Display

Here follow some code listings as examples:

Example - References to database records

In this example up to 200 references to Content Elements can be made:

     1: 'records' => Array (

     2:     'label' => 'LLL:EXT:cms/locallang_ttc.php:records',

     3:     'config' => Array (

     4:         'type' => 'group',

     5:         'internal_type' => 'db',

     6:         'allowed' => 'tt_content',

     7:         'size' => '5',

     8:         'maxitems' => '200',

     9:         'minitems' => '0',

    10:         'show_thumbs' => '1'

    11:     )

    12: ),

In line 5 it is configured that the internal type of the group field is "db" and then it follows that the allowed tables you can select from is "tt_content" (Content Elements table). This could be a list of tables which means you can mix references as you like!

Line 8 defines that there can be only 200 references and line 10 shows that they should be listed with their icons to the right of the selector box list.

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.

Example - 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 configuration looks like:

     1: 'storage_pid' => Array (

     2:     'exclude' => 1,

     3:     'label' => 'LLL:EXT:lang/locallang_tca.php:storage_pid',

     4:     'config' => Array (

     5:         'type' => 'group',

     6:         'internal_type' => 'db',

     7:         'allowed' => 'pages',

     8:         'size' => '1',

     9:         'maxitems' => '1',

    10:         'minitems' => '0',

    11:         'show_thumbs' => '1'

    12:     )

    13: ),

Notice how "maxitems" in line 9 is used to enforce that only one relation is created despite the ability of the "group" type field to create multiple references.

Example - Attaching images

When you want to attach files to a database record it is done by the group field like this:

Notice how the same image has apparently been added twice - or at least the filename was the same ("DSC_7102_background.jpg"). In the second case the name has been made unique by appending "_01" before the extension. This happens because all files attached to records through the group type are copied to a location defined by the "uploadfolder" setting in the configuration (see line 8 below). Therefore, having two files with identical names means one of them must be renamed automatically.

     1: 'image' => Array (

     2:     'label' => 'LLL:EXT:lang/locallang_general.php:LGL.images',

     3:     'config' => Array (

     4:         'type' => 'group',

     5:         'internal_type' => 'file',

     6:         'allowed' => $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext'],

     7:         'max_size' => '1000',

     8:         'uploadfolder' => 'uploads/pics',

     9:         'show_thumbs' => '1',

    10:         'size' => '3',

    11:         'maxitems' => '200',

    12:         'minitems' => '0',

    13:         'autoSizeMax' => 40,

    14:     )

    15: ),

Notice how line 5 defines the "group" type to contain files.

In line 6 the list of allowed file extensions are defined (here, taking the default list of image types for TYPO3).

Line 7 defines the maximum kb size of files allowed.

Line 8 defines the storage folder in the filesystem where the files are copied to when attached to the record. The path is relative to the PATH_site of TYPO3, one directory below PATH_typo3

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

In t3lib/ the class "t3lib_loaddbgroup" 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.

The t3lib/ class "t3lib_transferdata" 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.jpg,DSC_7102_background_01.jpg	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.

Alternatively 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/fileadmin/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.

To top