[965 Aufrufe]

4.5 Callbacks für Felder

Mit den Callbacks für die Felder beeinflusst man das Aussehen und die Funktion der einzelnen Felder. Sie werden genutzt, um z. B. Werte beim Laden oder Speichern zu beeinflussen, oder ganze Felder zu erstellen.

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: fields.[FIELD].options

Der fields.[FIELD].options ist vermutlich einer der meist genutzten Callbacks für Felder überhaupt. Mit ihm werden einem Auswahlfeld Optionen hinzugefügt, bzw. diese manipuliert.

Diesen Callback kann es nur einmal geben, er wird also nicht der Reihe nach ausgeführt, wenn mehrere definiert sind. Wird ein neuer Callback definiert, überschreibt er den alten.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: fields.[FIELD].options, table: tl_test, method: myCallback }

Hier muss [FIELD] durch den Namen des Felds ersetzt werden.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(DataContainer $dc): array
    {
        return ['key01' => 'Option 01', 'key02' => 'Option 02'];
    }
}

Der Callback bekommt ein Data Container Objekt und erwartet das Array mit den Optionen als Rückgebewert. Meist werden hier Datenbankabfragen und Fallunterscheidungen genutzt, oder Werte konvertiert. Dieses Beispiel macht wenig Sinn, da man das Array auch einfach im DCA hinterlegen könnte, aber es soll zur Demonstration erst einmal reichen.

Callback: fields.[FIELD].input_field

Der fields.[FIELD].input_field-Callback dient dem Erstellen individueller Felder. Das erstellte Feld ersetzt das normale Feld, welches sonst von Contao generiert wird.

Es ist zu beachten, dass die Werte nicht automatisch gespeichert werden. Man muss also noch einen fields.[FIELD].save-Callback implementieren, damit dies geschieht.

Diesen Callback kann es nur einmal geben, er wird also nicht der Reihe nach ausgeführt, wenn mehrere definiert sind. Wird ein neuer Callback definiert, überschreibt er den alten.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: fields.[FIELD].input_field, table: tl_test, method: myCallback }

Hier muss [FIELD] durch den Namen des Felds ersetzt werden.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(DataContainer $dc, string $label): void
    {
        return '<div class="w50 widget">
          <h3><label for="ctrl_title"><span class="invisible">Pflichtfeld </span>Title<span class="mandatory">*</span></label></h3>
          <input type="text" name="title" id="ctrl_title" class="tl_text" value="test" required="" maxlength="255" onfocus="Backend.getScrollOffset()">
          <p class="tl_help tl_tip" title="">Bitte geben Sie den Titel ein.</p>
        </div>';
    }
}

Hier muss das Markup des Felds zurückgegeben werden. Für dieses Beispiel habe ich einfach das normale Markup eines Textfelds kopiert.

Callback: fields.[FIELD].load

Der fields.[FIELD].load`-Callback wird beim Laden des Felds ausgeführt und kann genutzt werden, um den geladenen Wert aus der Datenbank zu manipulieren, oder einen Vorgabewert zu setzten.

Dieser Callback hat andere Parameter, wenn er im Frontendmodul "Persönliche Daten" verwendet wird. Details sind im Handbuch zu finden.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: fields.[FIELD].load, table: tl_test, method: myCallback, priority: 1024 }

Hier muss [FIELD] durch den Namen des Felds ersetzt werden.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(string $value, DataContainer $dc): string
    {
        return "Title: $value";
    }
}

Der Typ von $value unterscheidet sich je nach Feldtyp, ebenso unterscheidet sich dann auch der Rückgabewert. Es ist also nötig, hier ggf. die TypeHints anzupassen.

Der Callback erhalt als ersten Parameter den Wert und als zweiten ein Data Container Objekt, als Rückgabewert wird der bearbeitete Wert erwartet. In diesem Beispiel stellen wir dem Wert ein "Titel" voran. Dies werden wir im fields.[FIELD].save-Callback vor dem Speichern wieder löschen.

Callback: fields.[FIELD].save

Der fields.[FIELD].save-Callback ist das Gegenstück zum fields.[FIELD].load-Callback und wird vor dem Speichern eines Werts in der Datenbank aufgerufen. Er ermöglicht das Manipulieren des Werts vor dem Speichern. So können z. B. Eingaben geprüft und ggf. konvertiert werden.

Dieser Callback hat andere Parameter, wenn er im Frontendmodul "Persönliche Daten", oder "Registrierung" verwendet wird. Details sind imHandbuch zu finden.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: fields.[FIELD].save, table: tl_test, method: myCallback, priority: 1024 }

Hier muss [FIELD] durch den Namen des Felds ersetzt werden.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(string $value, DataContainer $dc): string
    {
        return \str_replace('Title: ', '', $value);
    }
}

Der Typ von $value unterscheidet sich je nach Feldtyp, ebenso unterscheidet sich dann auch der Rückgabewert. Es ist also nötig, hier ggf. die TypeHints anzupassen.

Der Callback erhalt als ersten Parameter den Wert und als zweiten ein Data Container Objekt, als Rückgabewert wird der bearbeitete Wert erwartet. In diesem Beispiel löschen wird das im fields.[FIELD].load-Callback hinzugefügt "Title" wieder. Es wird also im Backend angezeigt, nicht aber in der Datenbank gespeichert. Dies ist ein schönes Beispiel für das Zusammenspiel von fields.[FIELD].load und fields.[FIELD].save.

Callback: fields.[FIELD].wizard

Mit dem fields.[FIELD].wizard-Callback kann man zusätzliches HTML hinter dem Eingabefeld ausgeben lassen. Dies kann zur Erzeugung eines individuellen Wizards genutzt werden.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: fields.[FIELD].wizard , table: tl_test, method: myCallback, priority: 1024 }

Hier muss [FIELD] durch den Namen des Felds ersetzt werden.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(DataContainer $dc): string
    {
        return '<span>Tolles Feld</span>';
    }
}

Der Callback bekommt als einzigen Parameter ein Data Container Objekt und erwartet das Markup als Rückgabewert.

Callback: fields.[FIELD].xlabel

Mit dem fields.[FIELD].xlabel kann zusätzliches Markup hinter dem Label des Feldes ausgeben werden. Dies wird in Contao z. B. dazu genutzt, um die Buttons des Importwizards anzuzeigen.

services:
  Ctocb\Example\Classes\Contao\Callbacks\TlTest:
    public: true
    tags:
      - { name: contao.callback, target: fields.[FIELD].xlabel, table: tl_test, method: myCallback, priority: 1024 }

Hier muss [FIELD] durch den Namen des Felds ersetzt werden.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback(DataContainer $dc): string
    {
        return '<span>Tolles Label</span>';
    }
}

Der Callback bekommt als einzigen Parameter ein Data Container Objekt und erwartet das Markup als Rückgabewert.

Callback: fields.[FIELD].eval.url

Mit dem fields.[FIELD].eval.url-Callback kann man der "Search Engine Result Page"-Vorschau eine Url hinzugefügt werden.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: fields.[FIELD].eval.url, table: tl_test, method: myCallback, priority: 1024 }

Hier muss [FIELD] durch den Namen des Felds ersetzt werden.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback($model): string
    {
        return 'https://example.org/';
    }
}

Der Callback bekommt ein Model mit dem Datensatz aus der Tabelle und erwartet die Url als Rückgabewert.

Callback: fields.[FIELD].eval.title_tag

Mit dem fields.[FIELD].eval.title_tag-Callback kann man das Title-Tag der "Search Engine Result Page"-Vorschau anpassen.

services:
    Ctocb\Example\Classes\Contao\Callbacks\TlTest:
        public: true
        tags:
            - { name: contao.callback, target: fields.[FIELD].eval.title_tag, table: tl_test, method: myCallback, priority: 1024 }

Hier muss [FIELD] durch den Namen des Felds ersetzt werden.

<?php declare(strict_types=1);

namespace Ctocb\Example\Classes\Contao\Callbacks;

use Contao\DataContainer;

class TlTest
{
    public function myCallback($model): string
    {
        return '<span>Tolles Label</span>';
    }
}

Der Callback bekommt ein Model mit dem Datensatz aus der Tabelle und erwartet den Title-Tag als Rückgabewert.