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.