Child records configuration

The "children" property is used to create nested structures, generally MM tables where additional information needs to be stored. This will correspond to inline-type ("IRRE") fields with MM tables having a primary key field ("uid").

See the Mapping data chapter for an overview of import scenarios which may help understand this feature.

Example:

$GLOBALS['TCA']['tx_externalimporttest_product']['columns']['pictures']['external'] = [
   'base' => [
        'field' => 'Pictures', // remote db field
        'transformations' => [
            10 => [
                'userFunction' => [
                    'class' => \Cobweb\ExternalImport\Transformation\ImageTransformation::class,
                    'method' => 'saveImageFromUri',
                    'parameters' => [
                        'storage' => '1:importedpictures', // local folder for files
                    ]
                ]
            ]
        ],
        'children' => [
            'table' => 'sys_file_reference',
            'columns' => [
                'uid_local' => [
                    'field' => 'pictures'
                ],
                'uid_foreign' => [
                    'field' => '__parent.id__'
                ],
                'title' => [
                    'field' => 'picture_title'
                ],
                'tablenames' => [
                    'value' => 'tx_externalimporttest_product'
                ],
                'fieldname' => [
                    'value' => 'pictures'
                ],
                'table_local' => [
                    'value' => 'sys_file'
                ]
            ],
            'sorting' => [
                'source' => 'picture_order',
                'target' => 'sorting_foreign'
            ],
            'controlColumnsForUpdate' => 'uid_local, uid_foreign, tablenames, fieldname, table_local',
            'controlColumnsForDelete' => 'uid_foreign, tablenames, fieldname, table_local'
        ]
       ...
   ]
]
Copied!

Properties

Property Data type Step/Scope
columns array Store data
controlColumnsForUpdate string Store data
controlColumnsForDelete string Store data
disabledOperations string Store data
sorting array Store data
table string Store data

table

Type
string
Description
Name of the nested table. This information is mandatory.
Scope
Store data

columns

Type
array
Description

List of columns (database fields) needed for the nested table. This is an associative array, using the column name as the key. Then each column must have one of two properties:

value
This is a simple value that will be used for each entry into the nested table. Use it for invariants like the "tablenames" field of a MM table.
field

This is the name of a field that is available in the imported data. The value is copied from the current record. Note that such fields can be any of the mapped columns, any of the additionalFields or any of the substructureFields.

The special value __parent.id__ refers to the primary key of the current record and will typically be used for "uid_local" or "uid_foreign" fields in MM tables, depending on how the relation is built.

Scope
Store data

controlColumnsForUpdate

Type
string
Description

Comma-separated list of columns that need to be used for checking if a child record already exists. All these columns must exist in the list of columns defined above. Defining this property ensures that existing relations are updated instead of being created anew.

This list should contain all columns that are significant for identifying a child record without ambiguity. In the example above, we have:

'controlColumnsForUpdate' => 'uid_local, uid_foreign, tablenames, fieldname, table_local',
Copied!

These are all the columns that need to be queried in the "sys_file_reference" table to be sure that we are targeting the right record in the database. Any missing information might mean retrieving another record (for a different table or field, or whatever).

Scope
Store data

controlColumnsForDelete

Type
string
Description

This is similar to controlColumnsForUpdate but for finding out which existing relations are no longer relevant and need to be deleted. It is not the same list of fields as you need to leave out the field which references the relation on the "other side". In the case of "sys_file_reference", you would leave out "uid_local", which is the reference to the "sys_file" table.

Scope
Store data

sorting

Type
array
Description

External Import stores child records in the order in which they appear, which is generally the order in which they are in the external data source. It may be needed to sort the child records differently, according to some other data available in the in the external source.

This property allows this. It is defined by two elements:

source

The name of the column containing the sorting value in the external data source. This column should ideally contain numerical values. If that is not the case, the values are cast to integer when they are used, so you need to make sure that the values contained in this column can be cast safely.

If the sorting value is missing for some records, a value of 0 will be used instead, putting those child records at the top of the list.

target
The name of the sorting field in the child record table.

Both elements are mandatory. Configuration validation will fail otherwise.

'sorting' => [
    'source' => 'picture_order',
    'target' => 'sorting_foreign'
],
Copied!
Scope
Store data

disabledOperations

Type
string
Description

Comma-separated list of operations which should not take place. This can be "insert" (no new child records), "update" (no update to existing child records) and/or "delete" (no removal of existing child records).

Scope
Store data