List

The listing array defines how records are listed. The Contao core engine supports three different “list view”, “parent view” and “tree view”. You can configure various sorting options like filters or the default sorting order and you can add custom labels.

Sorting

// contao/dca/tl_example.php
$GLOBALS['TL_DCA']['tl_example']['list']['sorting'] = [
    // …
];

Key	Value	Description
mode	Sorting mode (`integer`)	0 Records are not sorted 1 Records are sorted by a fixed field 2 Records are sorted by a switchable field 3 Records are sorted by the parent table 4 Displays the child records of a parent record (see content elements) 5 Records are displayed as tree (see site structure) 6 Displays the child records within a tree structure (see articles module) Tip Use the constants in `\Contao\DataContainer` class for sorting modes. Info Before Contao 4.13 you will need to implement a child_record_callback in mode 4, otherwise no records will be shown in backend.
flag	Sorting flag (`integer`)	1 Sort by initial letter ascending 2 Sort by initial letter descending 3 Sort by initial two letters ascending 4 Sort by initial two letters descending 5 Sort by day ascending 6 Sort by day descending 7 Sort by month ascending 8 Sort by month descending 9 Sort by year ascending 10 Sort by year descending 11 Sort ascending 12 Sort descending since 5.1 13 Sort by initial letter ascending and descending 14 Sort by initial two letters ascending and descending 15 Sort by day ascending and descending 16 Sort by month ascending and descending 17 Sort by year ascending and descending 18 Sort ascending and descending Tip Use the constants in `\Contao\DataContainer` class for sorting flags.
panelLayout	Panel layout (`string`)	search show the search records menu sort show the sort records menu filter show the filter records menu limit show the limit records menu. Separate options with comma (= space) and semicolon (= new line) like `sort,filter;search,limit`.
fields	Default sorting values (`array`)	One or more fields that are used to sort the table.
headerFields	Header fields (`array`)	One or more fields that will be shown in the header element (sorting mode 4 only).
icon	Tree icon (`string`)	Path to an icon that will be shown on top of the tree (sorting mode 5 and 6 only).
root	Root nodes (`array`)	IDs of the root records (pagemounts). This value usually takes care of itself.
rootPaste	true/false (`bool`)	Enable paste buttons at root level. (default: false)
filter	Query filter (`array`)	Allows you to add custom filters as arrays, e.g. `[['status=?', 'active'], ['usages>?', 0]]`.
disableGrouping	true/false (`bool`)	Allows you to disable the group headers in list view and parent view.
defaultSearchField	Field name (`string`)	since 5.1 Set a default search field for the search records menu instead of selecting the alphabetically first field.
paste_button_callback	Callback function (`array`)	These functions will be called instead of displaying the default paste buttons. Please specify as `['Class', 'Method']` or use an anonymous function.
child_record_callback	Callback function (`array`)	These functions must be specified to render the child elements (sorting mode 4 only). Please specify as `['Class', 'Method']` or use an anonymous function.
header_callback	Callback function (`array`)	These functions will be called when the header fields (sorting mode 4 only) are created. Please specify as `['Class', 'Method']` or use an anonymous function.
panel_callback	Callback function (`array`)	This callback allows you to inject HTML for custom panels. Please specify as `['Class', 'Method']` or use an anonymous function.
child_record_class	CSS class (`string`)	Allows you to add a CSS class to the parent view elements.

Tip

since 4.13 The Contao\DataContainer class provides constants for the various sorting modes and flags, e.g.

// Displays the child records of a parent record (see content elements)
'mode' => Contao\DataContainer::MODE_PARENT, // 4

// Records are displayed as tree (see site structure)
'mode' => Contao\DataContainer::MODE_TREE, // 5

//Sort by initial letter ascending
'flag' => Contao\DataContainer::SORT_INITIAL_LETTER_ASC, // 1

// Sort by initial letter descending
'flag' => Contao\DataContainer::SORT_INITIAL_LETTER_DESC, // 2

Labels

// contao/dca/tl_example.php
$GLOBALS['TL_DCA']['tl_example']['list']['label'] = [
    // …
];

Key	Value	Description
fields	Fields (`array`)	One or more fields that will be shown in the list (e.g. `['title', 'user_id:tl_user.name']`).
showColumns	true/false (`bool`)	If true Contao will generate a table header with column names (e.g. back end member list)
showFirstOrderBy	true/false (`bool`)	since 4.13.36 If false Contao will not force the first sorting field to show up in the list. (default: `true`)
format	Format string (`string`)	HTML string used to format the fields that will be shown (e.g. `'%s (%s)'`).
maxCharacters	Number of characters (`integer`)	Maximum number of characters of the label.
group_callback	Callback functions (`array`)	Call a custom function instead of using the default group header function.
label_callback	Callback functions (`array`)	Call a custom function instead of using the default label function.

Operations

The operations are divided into two sections: global operations that relate to all records at once (e.g. editing multiple records) and regular operations that relate to a particular record only (e.g. editing or deleting a record).

Global operations

// contao/dca/tl_example.php
$GLOBALS['TL_DCA']['tl_example']['list']['global_operations'] = [
    // …
];

Key	Value	Description
label	`&$GLOBALS['TL_LANG']` (`string`)	Button label. Typically a reference to the global language array.
href	URL fragment (`string`)	URL fragment that is added to the URI string when the button is clicked (e.g. `act=editAll`).
icon	Icon (`string`)	Path and filename of the icon.
class	CSS class (`string`)	CSS class attribute of the button.
attributes	Additional attributes (`string`)	Additional attributes like event handler or style definitions.
button_callback	Callback function (`array`)	Call a custom function to generate the button. Please specify as `['Class', 'Method']` or use service tagging.
route	Symfony Route Name (`string`)	since 4.7 The button will redirect to the given Symfony route.

Info

since 5.3 You do not have to define any settings for global operations anymore. Instead, you can give a list of which operations should be available for your data container. You can also adjust the order.

// contao/dca/tl_example.php
$GLOBALS['TL_DCA']['tl_example']['list']['global_operations'] = [
    'all',
    'custom_operation' => [
        'href' => 'do=custom_operation'
    ],
    'toggleNodes',
];

Regular operations

// contao/dca/tl_example.php
$GLOBALS['TL_DCA']['tl_example']['list']['operations'] = [
    // …
];

Key	Value	Description
label	`&$GLOBALS['TL_LANG']` (`string`)	Button label. Typically a reference to the global language array.
href	URL fragment (`string`)	URL fragment that is added to the URI string when the button is clicked (e.g. `act=edit`).
icon	Icon (`string`)	Path and filename of the icon.
attributes	Additional attributes (`string`)	Additional attributes like event handler or style definitions.
button_callback	Callback function (`array`)	Call a custom function to generate the button. Please specify as `['Class', 'Method']` or use service tagging.
showInHeader	true/false (`bool`)	since 4.5 Shows the operation in the header element (sorting mode 4 only).
route	Symfony Route Name (`string`)	since 4.7 The button will redirect to the given Symfony route.
primary	true/false (`bool`)	since 5.5 Shows the operation in the overview, instead of hiding it in the context menu.

Info

since 5.0 You do not have to define any settings for standard operations anymore. Instead, you can give a list of which operations should be available for your data container. Contao will also check the appropriate contao_dc.<data-container> permission for these operations.

// contao/dca/tl_example.php
$GLOBALS['TL_DCA']['tl_example']['list']['operations'] = [
    'edit',
    'children',
    'copy',
    'cut',
    'delete',
    'toggle',
    'show',
];

Info

since 5.5 All operations are now shown within the context-menu. If you want them to appear in the overview, you can enable them by prepending your key with ! as seen in the example (or use 'primary' => true in your custom operation config). Note that the operations edit, children and toggle will always appear in the overview regardless.

$GLOBALS['TL_DCA']['tl_example']['list']['operations'] = [
    '!edit',
    '!children',
    'copy',
    'cut',
    'delete',
    'toggle',
    'show'
];

Toggle Operation

since 4.13 You can implement an automatic toggle operation for data containers that contain a boolean field. This is typically used for fields that control a “published” state of a data record for example, but the use case can be arbitrary.

// contao/dca/tl_foobar.php
$GLOBALS['TL_DCA']['tl_foobar']['list']['operations']['toggle'] = [
    'href' => 'act=toggle&amp;field=published',
    'icon' => 'visible.svg',
];

$GLOBALS['TL_DCA']['tl_foobar']['fields']['published'] = [
    'toggle' => true,
    'inputType' => 'checkbox',
    'sql' => ['type' => 'boolean', 'default' => false],
];

If the state of your field is reversed you can instead define reverseToggle:

$GLOBALS['TL_DCA']['tl_foobar']['fields']['invisible'] = [
    'reverseToggle' => true,
    'inputType' => 'checkbox',
    'sql' => ['type' => 'boolean', 'default' => false],
];

since 5.0 Since contao 5 you can reduce the toggle operation to a single line:

// contao/dca/tl_foobar.php
$GLOBALS['TL_DCA']['tl_foobar']['list']['operations'][] = 'toggle';

Instead of using the default visible.svg icon you can of course also provide your own. However, in the DCA you only define the icon of the active state - and then you additionally provide a second icon file for the inactive state in the same folder, but appended with an underscore in its name. So for example myicon.svg and myicon_.svg.

Note that for custom icons not provided by Contao’s back end theme you will need to provide a path to the icon, relative to the public directory, e.g.

// contao/dca/tl_foobar.php
$GLOBALS['TL_DCA']['tl_foobar']['list']['operations']['toggle'] = [
    'href' => 'act=toggle&amp;field=published',
    'icon' => 'icons/myicon.svg',
];

Or in case of a custom bundle, where the icon resides in the public/ directory of that bundle:

// contao/dca/tl_foobar.php
$GLOBALS['TL_DCA']['tl_foobar']['list']['operations']['toggle'] = [
    'href' => 'act=toggle&amp;field=published',
    'icon' => 'bundles/foobar/myicon.svg',
];

You can also use the assets.packages service:

// contao/dca/tl_foobar.php
$GLOBALS['TL_DCA']['tl_foobar']['list']['operations']['toggle'] = [
    'href' => 'act=toggle&amp;field=published',
    'icon' => Contao\System::getContainer()->get('assets.packages')->getUrl('myicon.svg', 'foobar'),
];