4.3 Callbacks für die Auflistung

Die Callbacks für die Auflistung werden beim Aufruf der Liste im Backend ausgeführt und dienen der Bearbeitung der Ausgabe der Liste und des Kopfbereichs.

Alle hier aufgeführten Callbacks kann es nur einmal geben, sie werden also nicht der Reihe nach ausgeführt. Wird ein neuer Callback definiert, überschreibt er den alten.

In diesen Beispielen werden die Callbacks immer in der Datei /src/Ctocb/Example/Resources/config/services.yml registriert und die Klasse für die Verarbeitung ist hier immer /src/Ctocb/Example/Classes/Contao/Callbacks/TlTest.php. Wer nicht weiß was hier gemeint ist, sollte sich den Text " "Grundlagen der Callbacks"" noch einmal ansehen.

Bitte auch in diesem Artikel wieder den Vendor-Namespace (und/oder entsprechenden Ordner) durch Euren eignen ersetzen und nicht Ctocb verwenden! Danke!

Callback: `list.sorting.paste_button`

Mit dem list.sorting.paste_button- Callback kann man wohl die Einfügen-Buttons verändern. Leider habe ich diesen Callback trotz intensiver Versuche nicht zum Laufen bekommen. Er wird augenscheinlich nur im List-Mode 5 (s. "Der Abschnitt: List") getriggert. Wer Details wissen möchte, kann sich gerne die Datei DC_Table ab Zeile 3914 ansehen.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: list.sorting.paste_button, table: tl_test, method: myCallback }

Als Rückgabewert muss der Calback laut Handbuch, das HTML der (zusätzlichen) Buttons zurückgeben.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(
        DataContainer $dc, 
        array $record, 
        string $table, 
        bool $circular, 
        array $clipboard, 
        ?array $children, 
        ?string $previousLabel, 
        ?string $nextLabel
    ): string {
        // do something ...
        $buttonHtml = '<img src="...">';

        return $buttonHtml;
    }
}

$dc ist wieder das Data Container Objekt, $record enthält die Daten des Datensatzes, der gerade verarbeitet wird. $table ist der Name der Tabelle und $circular ist ein boolscher Wert, der angibt, ob es sich um einen Ringbezug in der Baumansicht handelt. $clipboard enthält die Daten der Zwischenablage und $children enthält augenscheinlich die Kinddatensätze. $previousLabel das Label für "Letzte" und $nextLabel das für "Nächster".

Callback: `list.sorting.child_record`

Der list.sorting.child_record-Callback dient der Formatierung von Kinddatensätzen in der Liste im "parent view" (sorting mode 4). Wir werden das Thema Kindtabellen in einem späteren Kapitel ausführlicher behandeln, weshalb ich mich hier auf die Vorstellung des Callbacks beschränke. Dieser Callback muss für eine Kindtabelle (tl_test_child) benutzt werden.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: list.sorting.child_record, table: tl_test_child, method: myCallback }

Der Callback bekommt das Array mit den Daten des Kinddatensatzes übergeben und muss das Label des Kinddatensatzes als String zurückgeben.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(array $record): string
    {
        // do something ...

        return $record['label'] . ' [' . $record['id'] . ']'; // oder sinnvoll formatierte Daten
    }
}

Callback: `list.sorting.header`

Mit dem list.sorting.header-Callback kann der Kopfbereich der Liste im "parent view" (sorting mode 4) bearbeitet werden. Dieser Callback muss für eine Kindtabelle (tl_test_child) benutzt werden, da einzelne Tabellen oder Elterntabellen keinen Headbrereich haben, der die Daten der Elterntabelle anzeigt.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: list.sorting.header, table: tl_test_child, method: myCallback }

Der erste Parameter enthält die Beschriftung der Felder im Kopfbereich. Es kann verändert werden und wird dann als Rückgabewert erwartet.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(array $headerLabels, DataContainer $dc): array
    {
        $headerLabels['Id'] = $dc->id; // or do something useful ...

        return $headerLabels;
    }
}

In diesem Beispiel fügen wird die Id als Feld für die Anzeige hinzu.

Callback: `list.sorting.panel_callback.subpanel`

Mit dem list.sorting.panel_callback.subpanel -Callback kann man eigene Panels einfügen. Leider steht nirgendwo, wie dies geht, oder wann der Callback getriggert wird.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: list.sorting.panel_callback.subpanel, table: tl_test, method: myCallback }

Laut Handbuch muss subpaneldurch den Namen des eigenen Panels ersetzt werden. Es wird das Data Container Objekt übergeben und das HTML des Panels als Rückgabewert erwartet.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(DataContainer $dc): string
    {
        // do something ...
        return '<div class="panel">Etwas sinnvolles ... </div>';
    }
}

Callback: `list.label.group`

Der list.label.group-Callback erlaubt es, die Beschriftung einer Gruppe von Kinddatensätzen (im sorting mode 3) zu verändern. Auch dieser Callback funktioniert nur bei Kindtabellen (tl_test_child).

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: list.label.group, table: tl_test_child, method: myCallback }

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(
        string $group,
        ?string $mode,
        string $field,
        array $record,
        DataContainer $dc
    ): string {
        // do something ...
        return $group . '_TEST'; // or something useful ...
    }
}

Der erste Parameter enthält den Namen der Gruppe, dieser kann hier verändert werden. Der zweite Parameter enthält den Mode, kann aber auch null sein. Der dritte Parameter enthält das Feld mit Bezug zur Elterntabelle (bei mir pid). Leider fehlt auch hier eine genauere Beschreibung, sodass ich mir nicht sicher bin. Der vierte Parameter ($record) enthält die Daten des ersten Kinddatensatzes und DataContainer sollte klar sein.

Man kann nun die Beschriftung der Gruppe anpassen und dann zurückgeben. Wir fügen im Beispiel _TEST an den Namen der Gruppe an.

Callback: `list.label.label`

Einer der gebräuchlichsten Callbacks ist der list.label.label. Mit ihm kann man das Label eines Datensatzes in der Liste anpassen. Der Callback wird für jeden Datensatz einzeln mit den jeweiligen Daten aufgerufen.

Auch hier gibt es wieder verschiedene Versionen mit unterschiedlichen Parametern für die Listenansicht ("List view"), Baumansicht ("Tree View") und Kinddatensätze ("Parent view").

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: list.label.label, table: tl_test, method: myCallback }

Listenansicht:

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(array $record, string $label, DataContainer $dc, array $columns): array 
    {
        return $label . ' [' . $record['id'] . ']'; // or something useful ...
    }
}

In diesem Beispiel für die Listenansicht fügen wir dem Label die Id des Datensatzes hinzu. Der Parameter $record enthält die Daten des Datensatzes, der Parameter $label das im DCA definierte Label, $dc ist wie immer der Data Container Objekt und $columns enthält das Array mit den Werten der Felder, die im DCA für das Label definiert wurden (unter $GLOBALS['TL_DCA']['tl_test]['list']['label']['fields']).

Wenn im DCA showColumns auf true gesetzt ist, muss ein Array zurückgegeben werden, sonst ein String!

Baumansicht:

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(
        array $record, 
        string $label, 
        DataContainer $dc, 
        string $alwaysEmpty, 
        bool $alwaysFalse, 
        bool $protected
    ): string {
        return $label . ' [' . $record['id'] . ']'; // or something useful ...
    }
}

Die ersten drei Parameter sind gleich der Listenansicht. Den Parameter $columns gibt es hier nicht. Der vierte Parameter ist laut Handbuch immer eine leerer String, der fünfte ist immer false und der sechste gibt an, ob der Datensatz geschützt ist.

Im Gegensatz zur Listenansicht soll hier immer ein String zurückgegeben werden.

Parent View:

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(
        array $record, 
        string $label, 
        DataContainer $dc, 
        string $alwaysEmpty, 
        bool $alwaysFalse, 
        bool $protected
    ): string {
        return $label . ' [' . $record['id'] . ']'; // or something useful ...
    }
}

Die ersten drei Parameter sind gleich der Listenansicht. Die anderen Parameter gibt es hier nicht. Im Gegensatz zur Listenansicht soll auch hier immer ein String zurückgegeben werden.

Die ist sicher einer der am häufigst verwendeten Callback, auch wenn es sehr unschön ist, dass er unterschiedliche Parameter übergbit und im Fall der Listenansicht sogar unterschiedliche Rückgebewerte erwartet.

Zurück Inhalt Weiter