IRRE / inline
New in version 13.0
When using the inline
type, TYPO3
generates the correct database fields.
Developers do not need to define this field in an extension's
ext_
file.
Inline Relational Record Editing (IRRE) is a way of editing parent-child-relations in the backend view. Instead of child records already having to exist, new child records are created using AJAX calls (to prevent reloading the complete backend view).
The according database field is generated automatically.
Note
Inline fields should not be used anymore to handle files. Use the TCA column type file instead.
The type='inline' is a powerful element that can handle many types of relation,
including simple 1:
and nested 1:
relations, aswell as m:
relations with different view aspects and localization setups. When combined with
'ctrl' and 'types' properties in the TCA a huge amount of different views are possible.
The inline type was mainly designed to handle 1:
relations,
where one parent record has many children and each child has only one
parent. Children can not be transferred from one parent to another.
However, m:
relations can be setup using intermediate tables. An m:
relation is where a child has many parents. In addition to the main parent-child
relation fields in the intermediate table, fields can be added to attach
additional information to the parent-child relation. One example of this is
"FAL" / resource handling in the Core. A parent record
(for instance table "tt_content") is connected via table "sys_file_reference" to
a media resource in "sys_file". A sys_file record has table "sys_file_metadata"
as a child record which holds meta information about the file (for instance a
description). This information can be overwritten for the specific file resource used in
"tt_content" by adding a new description in "sys_file_reference". There are inline
and field properties in the TCA such as "placeholder" to set this up.
Hint
The inline type does not have field
,
field
or field
properties like other types. This is
due to the fact that it is a container and not an element. You can
still add fieldInformation or fieldWizard, but they must be configured
in the ctrl
. Please see the
example.
Properties of the TCA column type inline
appearance
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
Has information about the appearance of child records, namely:
- collapseAll (boolean)
- Show all child records collapsed (if false, all are expanded)
- expandSingle (boolean)
- Show only one child record expanded each time. If a collapsed record is clicked, the currently open one collapses and the clicked one expands.
- showNewRecordLink (boolean)
- Disables the New record link in TCA
inline
elements without simultaneously disabling the + button in the header of each inline record (using['appearance']
).['enabled Controls'] ['new'] - newRecordLinkAddTitle (boolean)
-
Adds the title of the foreign_table to the "New record" link.
- false
- "Create new"
- true
- "Create new <title of foreign_table>", e.g. "Create new address"
- newRecordLinkTitle (string or LLL reference)
-
Overrides the title of the "New record" link with a localized string. This will work only if
new
is not set to true.Record Link Add Title Example:
'newRecordLinkTitle' => 'LLL:EXT:myext/Resources/Private/Language/locallang_db.xlf:my_new_record_label'
Copied! - createNewRelationLinkTitle (string or LLL reference)
- Overrides the link text and title of the "Create new relation" button with a localised string. Only useful, if the element browser is enabled. This is usually used together with FAL relations to change it to "Add file" or similar.
- levelLinksPosition (string)
- Values: 'top' (default), 'bottom', 'both'. Defines where to show the "New record" link in relation
to the child records. Value 'none' is no longer supported, use
show
,All Localization Link show
andSynchronization Link show
with valueNew Record Link false
instead. - useCombination (boolean)
- This is only useful on bidirectional relations using an intermediate table with attributes. In a "combination" it is possible to edit the attributes AND the related child record itself. If using a foreign_selector in such a case, the foreign_unique property must be set to the same field as the foreign_selector.
- suppressCombinationWarning (boolean)
-
Suppresses the warning flash message that will be displayed when using useCombination. You can also override the message with your own message using the example below.
Example:
$GLOBALS['TCA']['tx_demo_domain_model_demoinline']['columns']['irre_records']['config'] = [ 'appearance' => [ 'overwriteCombinationWarningMessage' => 'LLL:EXT:demo/Resources/Private/Language/locallang_db.xlf:tx_demo_domain_model_demoinline.irre_records.useCombinationWarning', 'useCombination' => TRUE ], ],
Copied! - useSortable (boolean)
- Activate drag & drop.
- showPossibleLocalizationRecords (boolean)
- Show unlocalized records which are in the original language, but not yet localized.
- showAllLocalizationLink (boolean)
- Defines whether to show the "localize all records" link to fetch untranslated records from the original language.
- showSynchronizationLink (boolean)
- Defines whether to show a "synchronize" link to update to a 1:1 translation with the original language.
- enabledControls (array)
- Associative array with the keys 'info', 'new', 'dragdrop', 'sort', 'hide', 'delete', 'localize'. If the accordant values are set to a boolean value (true or false), the control is shown or hidden in the header of each record.
- showPossibleRecordsSelector (boolean)
- Can be used to hide the foreign record selector from the interface, even if you have a foreign_selector configured. This can be used to keep the technical functionality of the foreign_selector but is useful if you want to replace it with your own implementation using a custom control, see customControls.
- elementBrowserEnabled (boolean)
- Hides or displays the element browser button in inline records
autoSizeMax
-
- Type
- integer
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
The maximum size (height) of the select field.
The size of the select field will be automatically adjusted based on the number of selected items. The select field will never be smaller than the specified size and never larger than the value of
auto
.Size Max Note
Only has an effect if maxitems is greater than 1.
behaviour
-
allowLanguageSynchronization
-
- Type
- boolean
- Default
- false
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['allowLanguageSynchronization']
- Scope
- Proc.
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_
. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.state
disableMovingChildrenWithParent
-
- Type
- boolean
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']
- Scope
- Proc.
Default false. Disables that child records get moved along with their parent records. Usually if in a parent-child relation a parent record is moved to a different page (eg. via cut+paste from clipboard), the children are relocated along with the parent. This flag disables the child move.
This property can be especially useful if all child records should be gathered in one storage folder and their parents are spread out at different places in the page tree. In combination with the Tsconfig setting
TCAdefaults.<table>.
children can be forced to be created in this folder and stay there.pid = <page id>
enableCascadingDelete
-
- Type
- boolean
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']
- Scope
- Proc.
Default true. Usually in inline relations, if a parent is deleted, all children are deleted along with the parent. This flag can be used to disable that cascading delete. Example usage: A frontend user (parent) has assigned invoices (children). If a frontend user is deleted, it could be useful to keep the invoices.
customControls
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
Numerical array containing definitions of custom header controls for IRRE fields. This makes it possible to create special controls by calling user-defined functions (userFuncs). Each item in the array item must be an array itself, with at least on key "userFunc" pointing to the user function to call.
The userFunc string is defined as usual in TYPO3 as ['class']->['method'], e.g.:
\Vendor\Extension\MyClass::class . '->myUserFuncMethod'
Copied!For more details, see the implementation in
TYPO3\\
and search for "customControls".CMS\\ Backend\\ Form\\ Container\\ Inline Control Container
filter
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
Possibility to define user functions to filter out child items.
This is useful in special scenarios when used in conjunction with a foreign_selector where only certain foreign records are allowed to be related to.
For further documentation on this feature, see the "filter" documentation under TYPE: "group".
foreign_default_sortby
-
- Type
- string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
If a field name for foreign_sortby is defined, then this is ignored. Otherwise, this is used as the "ORDER BY" statement to sort the records in the table when listed.
foreign_field
-
- Type
- string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
The
foreign_
is the field of the child record pointing to the parent record. This defines where to store the uid of the parent record.field
foreign_label
-
- Type
- string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
Insert the fieldname of the inline element, that you want to have as the title of the inline element. E.g. 'header'. If set, it overrides the label set in
$GLOBALS
for the inline-view.['TCA'] [<foreign_ table>] ['ctrl'] ['label']
foreign_match_fields
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Proc.
Array of field-value pairs to both insert and match against when writing/reading IRRE relations. Using the match fields, it is possible to re-use the same child table in more than one field of the parent table by using a match field with different values for each of the use cases.
Imagine you have a parent table called "company" and a child table called "persons". Now, if you want the company table to have two fields of type "inline", one called "employees" and one called "customers", both containing "persons". Then you could use a (hidden) field called "role" on the child (person) table to keep them apart. The match TCA configuration of the parent table would then look like this:
<?php
$GLOBALS['TCA']['ty_myext_company'] = [
'columns' => [
'employees' => [
'config' => [
'type' => 'inline',
'foreign_table' => 'ty_myext_person',
'foreign_field' => 'company',
'foreign_match_fields' => [
'role' => 'employee',
],
],
],
'customers' => [
'config' => [
'type' => 'inline',
'foreign_table' => 'ty_myext_person',
'foreign_field' => 'company',
'foreign_match_fields' => [
'role' => 'customer',
],
],
],
],
];
If the match field is made editable, for instance as a select drop-down of two values, the the relation would switch between the two parent fields after change an save. Imagine a user record having "open" and "closed" issues assigned, both pointing to the same table. The user then switches the status of an issue from "open" to "closed". On save, the issue would "move over" to the "closed" section in his view.
foreign_selector
-
- Type
- string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
A selector is used to show all possible child records that could be used to create a relation with the parent record. It will be rendered as a multi-select-box. On clicking on an item inside the selector a new relation is created. The
foreign_
points to a field of the foreign_table that is responsible for providing a selector-box – this field on theselector foreign_
usually is of type select and also has atable foreign_
defined.table In most cases you must assign the field
uid_
to thelocal foreign_
. This field name is used as a convention for the child record of the intermediate table. The automatic generation of MM tables also uses this field name. It depends whetherselector uid_
of the MM table points to the opposite table (of the perspective of your inline field). In case of the opposite direction the field namelocal uid_
is usually used.foreign
foreign_sortby
-
- Type
- string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
Define a field on the child record that stores the manual sorting information. It is possible to have a different sorting, depending from which side of the relation we look at parent or child.
Attention
Do not confuse this property with foreign_default_sortby. The
foreign_
field contains an integer and is managed by the DataHandler. If by accident a content column like "title" is set assortby foreign_
, the DataHandler will write these integers into that field, which is most likely not what you want. Usesortby foreign_
in this case.default_ sortby This property requires that the foreign_field approach is used.
When using MM relations the field used on the intermediate table is hardcoded to
sorting_
. Setting this property has no effect combined with an MM table.foreign Warning
If you use the table only as an inline element, do not put the sortby field in the ctrl section, otherwise TYPO3 CMS will sort the entire table with every update. For example, if you have 10000 records, each with 4 inline elements, TYPO3 CMS will sort 40000 records even if only 4 must be sorted.
foreign_table
-
- Type
- string (table name)
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Required
- true
- Scope
- Display / Proc.
The table name of the child records is defined here. The table must be configured in
$GLOBALS
.['TCA']
foreign_table_field
-
- Type
- string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
The
foreign_
is the field of the child record pointing to the parent record. This defines where to store the table name of the parent record. On setting this configuration key together with foreign_field, the child record knows what its parent record is – so the child record could also be used on other parent tables. This issue is also known as "weak entity". Do not confuse with foreign_table or foreign_field. It has its own behavior.table_ field
foreign_unique
-
- Type
- string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
Field which must be unique for all children of a parent record.
Say you have two tables, products, your parent table, and prices, your child table (products) can have
multiple prices. The prices table has a field called customer_group, which is a selector box. Now you want to be
able to specify prices for each customer group when you edit a product, but of course you don't want to specify
contradicting prices for one product (i.e. two different prices for the same customer_group). That's why you
would set foreign_
to the field name "customer_group", to prevent that two prices for the
same customer group can be created for one product.
maxitems
-
- Type
- integer > 0
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
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.
minitems
-
- Type
- integer > 0
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
Minimum number of child items. Defaults to 0. JavaScript record validation prevents the record from being saved if the limit is not satisfied.
Note
TCA table column fields that define ['config']
can omit the
specification of the intermediate MM table layout in
ext_tables.sql. The TYPO3 database
analyzer takes care of proper schema definition.
MM
-
- Type
- string (table name)
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Proc.
This value contains the name of the table in which to store an MM relation. It is used together with foreign_table. The database field with a MM property only stores the number of records in the relation.
Please have a look into the additional information in the MM common property description.
Warning
Copying with MM relations will not create a copy of the value. Thus copying the record
Org
withOrg->org
andA Org->org
asB New
results inNew->org
andA New->org
instead ofB New->new
andA New->new
. Deleting the relationB New->org
will result in a broken relationA Org->org
.A
MM_opposite_field
-
- Type
- string (field name)
- Scope
- Proc.
If you want to make a MM relation editable from the foreign side (bidirectional) of the relation as well, you need to set
MM_
on the foreign side to the field name on the local side.opposite_ field For example, if the field
companies.
is your local side and you want to make the same relation editable from the foreign side of the relation in a field calledemployees persons.
, you would need to set theemployers MM_
value of the TCA configuration of theopposite_ field persons.
field to the string "employees".employers Note
Bidirectional references only get registered once on the native side in
sys_
.refindex
MM_hasUidField
-
Changed in version 13.0
This setting is obsolete. Remove all occurrences of
MM_
from TCA. Thehas Uid Field uid
column is added as primary key automatically, ifmultiple = true
is set, otherwise a combined primary key of fieldsuid_
,local uid_
plus eventuallyforeign tablenames
andfieldname
is used.
[
'columns' => [
'inline_1' => [
'label' => 'inline_1',
'config' => [
'type' => 'inline',
'foreign_table' => 'tx_styleguide_inline_mm_child',
'MM' => 'tx_styleguide_inline_mm_child_rel',
'appearance' => [
'showSynchronizationLink' => 1,
'showAllLocalizationLink' => 1,
'showPossibleLocalizationRecords' => 1,
],
],
],
],
]
[
'columns' => [
'parents' => [
'label' => 'parents',
'config' => [
'type' => 'inline',
'foreign_table' => 'tx_styleguide_inline_mm',
'MM' => 'tx_styleguide_inline_mm_child_rel',
'MM_opposite_field' => 'inline_1',
'maxitems' => 10,
'appearance' => [
'showSynchronizationLink' => 1,
'showAllLocalizationLink' => 1,
'showPossibleLocalizationRecords' => 1,
],
],
],
],
]
overrideChildTca
-
- Type
- array
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
This property can be used to override certain aspects of the child's TCA if that child record is opened inline of the given parent. Display related TCA properties of the child table can be overridden in
types
andcolumns
section.See also Examples with overrideChildTca.
size
-
- Type
- integer
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display
Only useful in combination with foreign_selector.
If set to 1 (default), the combination box is a select drop-down, else a select box of given size.
symmetric_field
-
- Type
- string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
This works like foreign_field, but in case of using bidirectional symmetric relations.
symmetric_
defines in which field on the foreign_table the uid of the "other" parent is stored.field
[
'columns' => [
'branches' => [
'label' => 'branches',
'config' => [
'type' => 'inline',
'foreign_table' => 'tx_styleguide_inline_mnsymmetric_mm',
'foreign_field' => 'hotelid',
'foreign_sortby' => 'hotelsort',
'foreign_label' => 'branchid',
'symmetric_field' => 'branchid',
'symmetric_sortby' => 'branchsort',
'symmetric_label' => 'hotelid',
'maxitems' => 10,
'appearance' => [
'showSynchronizationLink' => 1,
'showAllLocalizationLink' => 1,
'showPossibleLocalizationRecords' => 1,
],
],
],
],
]
symmetric_label
-
- Type
- string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
If set, it overrides the label set in
$GLOBALS
for the inline-view and only if looking to a symmetric relation from the "other" side.['TCA'] [<foreign_ table>] ['ctrl'] ['label']
symmetric_sortby
-
- Type
- string
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']
- Scope
- Display / Proc.
This works like foreign_sortby, but in case of using bidirectional symmetric relations. Each side of a symmetric relation could have its own sorting, so
symmetric_
defines a field on the foreign_table where the sorting of the "other" side is stored. This property requires that the foreign_field approach is used.sortby