Callbacks

Callbacks are entry-points for custom code in the DCA. Using callbacks you can modify the static Data Container Array during runtime.

Callback functions are based on the event dispatcher pattern. They are similar to Hooks, but always bound to a specific DCA table. You can register one or more callbacks for a certain event and when the event is triggered, the callback functions are being executed. See the framework article on how to register callbacks.

You can also use anonymous functions for DCA callbacks.

The following is a reference of all available callbacks, using their service tag callback property name.

Global callbacks

config.onload

Executed when the DataContainer object is initialized. Allows you to e.g. check permissions or to modify the Data Container Array dynamically at runtime.

Parameters

config.oncreate

Executed when a new record is created.

Parameters

config.onsubmit

Executed when a back end form is submitted. Allows you to e.g. modify the form data before it is written to the database (used to calculate intervals in the calendar extension).

Parameters

config.ondelete

Executed before a record is removed from the database.

Parameters

config.oncut

Is executed after a record has been moved to a new position.

Parameters

config.oncopy

Executed after a record has been duplicated.

Parameters

config.oncreate_version

Executed after the old version of the record has been added to tl_version.

Parameters

config.onrestore_version

Executed after a record has been restored from an old version.

Parameters

config.onundo

Executed after a deleted record has been restored from the “undo” table.

Parameters

config.oninvalidate_cache_tags

This feature is only available in Contao 4.7 and later.

This callback is executed whenever a record is changed in any way via the Contao back end. It allows you to add additional cache tags that should be invalidated.

Parameters

config.onshow

This feature is only available in Contao 4.7 and later.

Allows you to customize the info modal window of a database record.

Parameters

Listing callbacks

All listing callbacks are singular callbacks - meaning there can only be one callback, not multiple ones.

list.sorting.paste_button

Allows for individual paste buttons and is e.g. used in the site structure to disable buttons depending on the user’s permissions (requires an additional command check via load_callback).

Parameters

list.sorting.child_record

Defines how child elements are rendered in “parent view”.

Parameters

list.sorting.header

Allows for individual labels in header of “parent view”.

Parameters

list.sorting.panel_callback.subpanel

This callback allows you to inject HTML for custom panels. Replace subpanel wit your custom panel’s name.

Parameters

list.label.group

Allows for individual group headers in the listing.

Parameters

list.label.label

Allows for individual labels in the listing and is e.g. used in the user module to add status icons.

Parameters

Operations callbacks

All operations callbacks are singular callbacks - meaning there can only be one callback, not multiple ones.

The following is a list of button callbacks for operations. Replace operation in each case with the actual operation you want to use the callback for.

These callbacks allow for individual navigation icons and is e.g. used in the site structure to disable buttons depending on the user’s permissions (requires an additional command check via load_callback).

list.global_operations.operation.button

Parameters

list.operations.operation.button

Parameters

Field callbacks

The following is a list of callbacks for DCA fields. Replace field with a field name of your choice.

fields.field.options

The fields.field.options callback is a singular callback - meaning there can only be one callback, not multiple ones.

Allows you to define an individual function to load data into a drop-down menu or checkbox list. Useful e.g. for conditional foreinKey-relations.

Parameters

fields.field.input_field

The fields.field.input_field callback is a singular callback - meaning there can only be one callback, not multiple ones.

Allows for the creation of individual form fields and is e.g. used in the back end module “personal data” to generate the “purge data” widget. Attention: the field is not saved automatically!

Parameters

fields.field.load

Executed when a form field is initialized and can e.g. be used to load a default value.

Parameters

fields.field.save

Executed when a field is submitted and can e.g. be used to add an individual validation routine. If the new value does not validate, you can throw an \Exception with an appropriate error message. The record will not be saved then and the error message will be shown in the form.

Parameters

fields.field.wizard

Allows you to add additional HTML after the field input, typically used to show a button that starts a “wizard”.

Parameters

fields.field.xlabel

Allows you to add additional HTML after the field label, typically used to show a button for an import “wizard”.

Parameters