[4707 Aufrufe]

3.3 Der Abschnitt: List

Im Abschnitt list legen wir fest, wie unsere Daten im Backend angezeigt werden sollen. Dies klingt erst einmal simpel, aufgrund der vielen Möglichkeiten kann dies aber sehr komplex werden. Wie immer gehen wir die wichtigesten Dinge Schritt für Schritt durch. Es ist nicht schlimm, wenn Ihr nicht alles sofort versteht. Gerade den Tabellenbeziehungen werde ich später noch einen eigenen Text widmen. Ich werde die Einstellungen dieser Darstellungsformen aber auch hier vorstellen. Eine Beschreibung aller Einstellungen ist im Handbuch zu finden.

Beispielkonfiguration

Hier eine Minimalkonfiguration des Abschnitts list, die ich sehr häufig verwende:

<?php declare(strict_types=1);

$GLOBALS['TL_DCA']['tl_testtable'] = [
    // Config ...
    'list' => [
         'sorting' => [
            'mode'              => \Contao\DataContainer::MODE_SORTED,
            'flag'              => \Contao\DataContainer::SORT_INITIAL_LETTER_ASC,
            'fields'            => ['title'],
            'panelLayout'       => 'sort,filter;search,limit'
        ],
        'label' => [
            'fields'            => ['title'],
            'format'            => '%s'
        ],
        'global_operations' => [
            'all' => [
                'label'             => &$GLOBALS['TL_LANG']['MSC']['all'],
                'href'              => 'act=select',
                'class'             => 'header_edit_all',
                'attributes'        => 'onclick="Backend.getScrollOffset();" accesskey="e"'
            ]
        ],
        'operations' => [
            'edit' => [
                'label'             => &$GLOBALS['TL_LANG'][$table]['edit'],
                'href'              => 'act=edit',
                'icon'              => 'edit.svg'
            ],
            'copy' => [
                'label'             => &$GLOBALS['TL_LANG'][$table]['copy'],
                'href'              => 'act=copy',
                'icon'              => 'copy.svg'
            ],
            'delete' => [
                'label'             => &$GLOBALS['TL_LANG'][$table]['delete'],
                'href'              => 'act=delete',
                'icon'              => 'delete.svg',
                'attributes'        => 'onclick="if(!confirm(\'' . ($GLOBALS['TL_LANG']['MSC']['deleteConfirm'] ?? '') . '\'))return false;Backend.getScrollOffset()"'
            ],
            'show' => [
                'label'             => &$GLOBALS['TL_LANG'][$table]['show'],
                'href'              => 'act=show',
                'icon'              => 'show.svg'
            ]
        ]
    ],
    // ...
];

Wie man sieht, ist dieser Abschnitt etwas umfangreicher. Er umfasst die Bereiche sorting, label, global_operations und operations.

Der Abschnitt: sorting

Option: mode

Variablentyp:	integer
Beispiel:	\Contao\DataContainer::MODE_SORTED

Das Feld mode legt die Art fest, wie die Datensätze im Backend sortiert werden sollen. Es gibt folgende Werte:

Wert	Konstante	Bedeutung
0	\Contao\DataContainer::MODE_UNSORTED	Datensätze werden nicht sortiert.
1	\Contao\DataContainer::MODE_SORTED	Datensätze werden nach festen Felder sortiert. (Diese werden in der Option fields angegeben.)
2	\Contao\DataContainer::MODE_SORTABLE	Datensätze werden nach dynamischen Felder sortiert. (Nutzer kann im Backend die Sortierung ändern).
3	\Contao\DataContainer::MODE_SORTED_PARENT	Datensätze werden anhand der Eltertabelle sortiert.
4	\Contao\DataContainer::MODE_PARENT	Datensätze werden nach Elterdatensätzen sortiert (wie bei den Inhaltselementen).
5	\Contao\DataContainer::MODE_TREE	Datensätze werden als Baum angezeigt (wie bei der Seitenstruktur).
6	\Contao\DataContainer::MODE_TREE_EXTENDED	Datensätze werden in einer erweiterten Baumstruktur angezeigt (wie bei den Artikeln).

Es kann etwas verwirrend sein, das sorting > mode eigentlich die Art der Anzeigt und sorting > flag die Art der Sortierung festlegt (s. nächste Option).

Option: flag

Variablentyp:	integer
Beispiel:	\Contao\DataContainer::SORT_INITIAL_LETTER_ASC

Mit der Option flag legt man die Sortierreihenfolge fest. Die Angaben bezeiehn sich auf die in der Option fields angegebenen Felder. Es gibt folgende Werte:

Wert	Konstante	Bedeutung
1	\Contao\DataContainer::SORT_INITIAL_LETTER_ASC	Datensätze werden nach dem ersten Buchstaben aufsteigend sortiert.
2	\Contao\DataContainer::SORT_INITIAL_LETTER_DESC	Datensätze werden nach dem ersten Buchstaben absteigend sortiert.
3	\Contao\DataContainer::SORT_INITIAL_LETTERS_ASC	Datensätze werden nach den ersten zwei Buchstaben aufsteigend sortiert.
4	\Contao\DataContainer::SORT_INITIAL_LETTERS_DESC	Datensätze werden nach den ersten zwei Buchstaben absteigend sortiert.
5	\Contao\DataContainer::SORT_DAY_ASC	Datensätze werden nach Tag aufsteigend sortiert. (Feld muss ein Datum enthalten.)
6	\Contao\DataContainer::SORT_DAY_DESC	Datensätze werden nach Tag absteigend sortiert. (Feld muss ein Datum enthalten.)
7	\Contao\DataContainer::SORT_MONTH_ASC	Datensätze werden nach Monat aufsteigend sortiert. (Feld muss ein Datum enthalten.)
8	\Contao\DataContainer::SORT_MONTH_DESC	Datensätze werden nach Monat absteigend sortiert. (Feld muss ein Datum enthalten.)
9	\Contao\DataContainer::SORT_YEAR_ASC	Datensätze werden nach Jahr aufsteigend sortiert. (Feld muss ein Datum enthalten.)
10	\Contao\DataContainer::SORT_YEAR_DESC	Datensätze werden nach Jahr absteigend sortiert. (Feld muss ein Datum enthalten.)
11	\Contao\DataContainer::SORT_ASC	Datensätze werden aufsteigend.
12	\Contao\DataContainer::SORT_DESC	Datensätze werden absteigend.

Will man die Daten nach Datum sortieren und dies auch anzeigen, muss beim entsprecheden Feld ebenfalls ein das Flag gesetzt werden, da sonst der Timestamp statt des formatierten Datums angezeigt wird.

Option: fields

Variablentyp:	array
Beispiel:	['title', 'description']

Hier werden die Felder angegeben, nach denen sortiert werden soll.

Option: panelLayout

Variablentyp:	string
Beispiel:	filter;sort,search,limit

Mit der Option panelLayout kann der Aufbau des Panels im Kopf der Liste beeinflusst werden. Die Werte können wie im Beispiel kombiniret werden. Werden die Felder durch ein Komma getrennt, werden sie in einer Zeile dargestell, ein Semikolon steht für einen Zeilenumbruch.

Es gibt die Werte search für das Suchfeld, sort für die Auswahl der Sortierung, filter für die Filterfelder und limit für die Limitierung der Anzahl der angezeigten Datensätze.

Im Beispiel (filter;sort,search,limit) werden die Felder für die Filter in einer Zeile und das Feld für die Sortierung, die Suche und die Limitierung der angezeigten Datensätze in einer zweiten Zeile dargestellt.

Option: filter

Variablentyp:	array
Beispiel:	[['title=?', 'Test', ['description=?', 'Auch Test']]

Mit der Option filter können die Datensätze gefiltert werden, sodass nur bestimmte Datensätze angezeigt werden.

Option: headerFields

Variablentyp:	array
Beispiel:	['title', 'description']

Mit der Option werden die Felder festgelegt, die im Panel angezeigt werden sollen. Dies greift nur im Mode 4 (\Contao\DataContainer::MODE_PARENT), also wenn Kinddatensätze zu einem Elterndatensatz angezeigt werden. Die Felder beziehen sich auf die Elterntabelle und zeigen die entsprechenden Daten des Elterndatensatzes an.

Option: icon

Variablentyp:	string
Beispiel:	/path/to/my/icon.png

Im Mode 5 (\Contao\DataContainer::MODE_TREE) und 6 (\Contao\DataContainer::MODE_TREE_EXTENDED) kann ein Icon für den obersten Knoten angegeben werdne.

Option: root

Variablentyp:	array
Beispiel:	[1, 2]

Ids der Wurzelseiten. Hab ich ehrlich gesagt noch nie benötigt. Im Handbuch steht; "... This value usually takes care of itself." Ich führes es der Vollständigkeithalber trotzdem hier auf.

Option: rootPaste

Variablentyp:	bool
Beispiel:	true

Wird rootPaste auf true gesetzt, wird der Einfügen-Button für die Rootebene eingeschaltet.

Option: disableGrouping

Variablentyp:	bool
Beispiel:	true

Normalerweise werden die Datensätze anhand ihrer Sortierung gruppiert. Wird z. B. nach den ersten beiden Buchstaben des Titels sortiert, werden jeweils alle Titel mit Aa, Ab, ... zusammengefasst und es wird eine Gruppenüberschrift erstellt.

Wird disableGrouping auf true gesetzt, wird dies unterbunden.

Option: child_record_class

Variablentyp:	string
Beispiel:	myChildCssClass

Mit der Option child_record_class kann den Kinddatensätzen eine CSS-Klasse zugeordnet werden.

Option: paste_button_callback

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'myMethod']

Mit paste_button_callback kann der entsprechende Callback definiert werden. Mit ihm kann ein individueller Einfügen-Button erzeugt werden. Auf die Details der einzelnen Callbacks gehen wir im nächsten Kapitel ein.

Option: child_record_callback

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'myMethod']

Mit child_record_callback kann der entsprechende Callback definiert werden. Mit ihm kann ein individuelles Label für die einzelnen Kinddatensätze erzeugt werden. Auf die Details der einzelnen Callbacks gehen wir im nächsten Kapitel ein.

Option: header_callback

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'myMethod']

Mit header_callback kann der entsprechende Callback definiert werden. Mit ihm können die Felder im Kopfbereich beim Sorting-Mode 4 individualisiert werden. Auf die Details der einzelnen Callbacks gehen wir im nächsten Kapitel ein.

Der Abschnitt: label

In diesem Abschnitt wird die Beschriftung der Datensätze festgelegt.

Option: fields

Variablentyp:	array
Beispiel:	['title', 'description']

Hier werden in einem Array die Namen der Felder angegeben, die als Beschriftung verwendet werden sollen.

(Dies kann vom label_callback überschrieben oder geändert werden!)

Option: format

Variablentyp:	string
Beispiel:	%s <span style="color: #999;">%s</span>

Hier wird das Format für die Ausgabe der Beschrifung festgelegt. Das Format wird mit der PHP-Funktion sprintf verarbeitet. In der Regel wird für jedes Feld in der Option fields ein %s angegeben und zusätzlich Trennzeichen, falls erforderlich. Es kann auch HTML verwendet werden.

Option: showColumns

Variablentyp:	bool
Beispiel:	true

Mit showColumns wird aus der Liste eine Tabelle. Dies wird z. B. für die Benutzer des Backends verwendet.

Option: maxCharacters

Variablentyp:	integer
Beispiel:	255

Mit maxCharacters kann die maximale Länge der Beschrieftung angegeben werden.

Option: group_callback

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'generateGroup']

In manchen Anzeigeformen werden die Datensätze gruppiert. Mit dem group_callback kann die Beschriftung der Gruppen individualisiert werden.

Option: label_callback

Variablentyp:	array
Möglicher Werte:	[class, method]

Mit dem label_callback kann die Beschriftung der einzelnen Datensätze überarbeitet werden. Wir haben dies im Beitrag "Ein eigenes Icon für eine Backendliste erstellen" benutzt, um der Beschriftung ein Icon hinzuzufügen.

Der Abschnitt: global_operations

Hier werden die globalen Optionen erstellt, die oben rechts über der Liste der Datensätze angezeigt werden. Für jede globale Option gibt es folgende Einstellungen.

Option: label

Variablentyp:	array
Beispiel:	$GLOBALS['TL_LANG']['tl_testtable']['edit']

Hier wird die Übersetzung der Operation angegeben. Es ist fast immer ein Verweis auf ein Spracharray.

Option: href

Variablentyp:	string
Beispiel:	act=edit, key=hideall

Mit href wird der Link gesetzt, den Contao nutzen soll. Diesem muss dann in der Datei config.php eine Klasse für die Bearbeitung der Anfrage zugewiesen werden (s. Beitrag "Einen Button für eine eigene Liste").

Option: icon

Variablentyp:	string
Beispiel:	edit.svg, bundles/Ctocbexample/img/edit.png

Mit icon wird der Aktion ein Icon zugweisen. Dies kann ein internes Icon von Contao sein (edit.svg), oder ein eigenes
(bundles/Ctocbexample/img/edit.png). In letzteren Fall wird das Icon unter src/Ctocb/Example/Resources/public/img/edit.png im Verzeichnis der Erweiterung gespeichert und von Contao nach /web/bundles/Ctocbexample/img/edit.png verlinkt.

(Bitte den Vendor-Namespace (oder entsprechenden Ordner) wieder durch Euren eignen ersetzen und nicht Ctocb verwenden!)

Option: attributes

Variablentyp:	string
Beispiel:	onclick="if(!confirm(\'' . ($GLOBALS['TL_LANG']['MSC']['deleteConfirm'] ?? '') . '\'))return false;Backend.getScrollOffset()"

Mit attributes können zusätzliche Attribute an das Linktag angehängt werden. Dies wird z. B. beim Löschen einzelner Datensätze verwendet, um eine Bestätigung einzufordern.

Option: class

Variablentyp:	string
Beispiel:	mycssclass

Mit class kann dem Link eine CSS-Klasse mitgegeben werden.

Option: button_callback

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'toggleIcon']

Einen button_callback haben wir im Beitrag "Eine Togglefunktion für eine eigene Liste" bereits verwendet, um den Status des Datensatzes in der Liste anzuzeigen. Auch wenn es sich dabei um eine Operation für einen Datensatz gehandelt hat, ist die Funktionsweise ähnlich, nur die Parameter sind etwas anders. Wir werden uns dies im Kapitel über die Callbacks noch genauer ansehen.

Option: route

Variablentyp:	string
Beispiel:	(Leider habe ich bisher kein Beispiel gefunden.)

Seit Contao 4.7 kann man eine Route setzen, sodass man nicht über die Datei config.php eine Klasse für die Verarbeitung zuweisen muss. Der Weg über die Datei config.php funktionert aber weiterhin. Ich mag es, alle Einstellungen des Moduls dort abzulegen. Es ist aber jedem selbst überlassen, welche Methode man bevorzugt.

Der Abschnitt: operations

Hier finden wir die Operationen für die einzelnen Datensätze. In der Regel hat man die Operationen edit, copy, delete und show. Diese sind aus Contao bekannt und finden sich fast überall im Backend. Des Weitern gibt es noch die eigenen Aktionen, wie wir sie im Beitrag "Einen Button für eine eigene Liste" erstellt haben.

Option: label

Variablentyp:	array
Beispiel:	$GLOBALS['TL_LANG']['tl_testtable']['edit']

Hier wird die Übersetzung der Operation angegeben. Es ist fast immer ein Verweis auf ein Spracharray.

Option: href

Variablentyp:	string
Beispiel:	act=edit, key=hideall

Mit href wird der Link gesetzt, den Contao nutzen soll. Diesem muss dann in der Datei config.php eine Klasse für die Bearbeitung der Anfrage zugewiesen werden (s. Beitrag "Einen Button für eine eigene Liste").

Option: icon

Variablentyp:	string
Beispiel:	edit.svg, bundles/Ctocbexample/img/edit.png

Mit icon wird der Aktion ein Icon zugweisen. Dies kann ein internes Icon von Contao sein (edit.svg), oder ein eigenes
(bundles/Ctocbexample/img/edit.png). In letzteren Fall wird das Icon unter src/Ctocb/Example/Resources/public/img/edit.png im Verzeichnis der Erweiterung gespeichert und von Contao nach /web/bundles/Ctocbexample/img/edit.png verlinkt.

(Bitte den Vendor-Namespace (oder entsprechenden Ordner) wieder durch Euren eignen ersetzen und nicht Ctocb verwenden!)

Option: attributes

Variablentyp:	string
Beispiel:	onclick="if(!confirm(\'' . ($GLOBALS['TL_LANG']['MSC']['deleteConfirm'] ?? '') . '\'))return false;Backend.getScrollOffset()"

Mit attributes können zusätzliche Attribute an das Linktag angehängt werden. Dies wird z. B. beim Löschen verwendet, um eine Bestätigung einzufordern.

Option: button_callback

Variablentyp:	array
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'toggleIcon']

Den button_callback haben wir im Beitrag "Eine Togglefunktion für eine eigene Liste" bereits verwendet, um den Status des Datensatzes in der Liste anzuzeigen.

Fazit

Dies war ein recht umfangreicher Artikel. Wie wir gesehen haben, bietet das DCA viele verschiedene Möglichkeiten, unsere Daten darzustellen.