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.

Generally these callbacks are executed in the back end, e.g. when editing data records. However in some instances they might also be executed by front end modules, most prominently the member modules. In this case the parameters passed to the callback will be different, as there will be no \Contao\DataContainer instance for example, which only exists in the back end. The reference below will list these differences of the respective callbacks. Keep in mind that any extension might also execute any of these callbacks in the front end.


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
Example

config.oncreate

Executed when a new record is created.

Parameters

config.onbeforesubmit

This feature is available in Contao 5.0 and later.

Executed when a back end form is submitted before the record will be updated in the database. Allows you to e.g. modify the values or introduce validation accross multiple fields. You are expected to return the values.

Parameters

config.onsubmit

Executed when a back end form is submitted after the record has been updated in the database. Allows you to e.g. modify the record afterwards (used to calculate intervals in the calendar extension).

Parameters

config.ondelete

Executed before a record is removed from the database.

Parameters
Example

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

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

This callback is deprecated and will be removed in Contao 5.0. Use config.onrestore_version instead.

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 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 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
Example

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
Example for tree view
Example for list view

Operations callbacks

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

The following is a list of 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 a fields.<field>.load callback).

list.global_operations.<OPERATION>.button

This callback allows you to generate a button for a specific global operation yourself, instead of letting Contao generate it for you. The callback passes the originally generated button HTML as a string (if applicable), plus all the metadata defined in the DCA that is included in the generatd button. The callback is expected to return a string containing HTML for the button (or an empty string, if you do not want to show a button).

Parameters

list.operations.<OPERATION>.button

This callback allows you to generate a button for a specific operation yourself, instead of letting Contao generate it for you. The callback passes the database record, the originally generated button HTML as a string (if applicable) and all the metadata defined in the DCA that is included in the generatd button. The callback is expected to return a string containing HTML for the button (or an empty string, if you do not want to show a button).

Parameters
Example

Field Callbacks

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

fields.<FIELD>.attributes

This feature is available in Contao 5.1 and later.

Allows you do dynamically adjust the attributes of a field in a DCA before a widget is generated.

Parameters
Example

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
Example

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

fields.<FIELD>.eval.url

Allows you to add an url to the serp preview field.

Parameters
Example

fields.<FIELD>.eval.title_tag

Allows you to modify the title tag of the serp preview field.

Parameters
Example

Edit Callbacks

The following is a list of callbacks relating to edit actions of a Data Container.

edit.buttons

Allows you to modify the action buttons at the bottom of record editing form. This can be used to add additional buttons or remove any of the existing buttons.

Parameters
Example

Select Callbacks

The following is a list of callbacks relating to select actions of a Data Container.

select.buttons

Allows you to modify the action buttons at the bottom after selecting rows. This can be used to add additional buttons or update and remove any of the existing buttons.

Parameters
Example