Eigene insert tags erstellen

Unvollständiger Artikel: dieser Artikel ist noch nicht sauber bearbeitet. Bitte erweitere ihn und entferne erst anschliessend diesen Hinweis.

Unter Insert-Tags versteht man in Contao spezielle Platzhalter, die beim Laden der Webseite durch bestimmte Inhalte ersetzt werden. Dies können zum Beispiel der aktuelle Benutzername, ein Datum oder ein Link sein. Der Contao-Core bietet eine ganze Reihe verschiedener Insert-Tags, welche auf der Projekthomepage dokumentiert sind (siehe Contao Insert-Tags).

Aufbau eines Insert-Tags

Insert-Tags werden generell in zwei geschwungenen Klammern verpackt. {{var::value}} Des weiteren sind Insert-Tags meistens zweigeteilt. Die Wertepaare sind durch zwei Doppelpunkte getrennt. Der erste Teil ist entweder die Kategoriezugehörigkeit des Insert-Tags oder der Name des Tags. Der zweite Teil ist meistens ein Parameter, um die gewünschte Rückgabe noch zu verfeinern. Ein Beispiel verdeutlicht dies: {{link::*}} Dieser Insert Tag würde einen Link zur Seite * (muss durch die ID der Seite ersetzt werden) im richtigen URL Format generieren.

Eigene Insert-Tags erstellen

Seit TYPOlight Version 2.6 kann man Contao durch eigene Insert-Tags erweitern. Dazu wurde der Hook replaceInsertTags zur Verfügung gestellt. Der Ablauf ist nun folgender.

1. Contao parsed einen Seitenaufruf und stößt dabei auf ein Insert-Tag
2. Contao probiert dieses Insert-Tag mit den Core-Möglichkeiten zu ersetzen
3. Wenn Contao das Insert-Tag nicht kennt, wird es an den Hook replaceInsertTags weitergereicht. Dieser Hook erhält das unbekannte Insert-Tag als Parameter. Nun kann der Entwickler prüfen ob er das unbekannte Insert-Tag ersetzen möchte und wenn ja, gibt er einen beliebigen Content zurück.
4. Wenn der Entwickler nichts mit dem unbekannten Insert-Tag anfangen kann, so muss false zurück gegeben werden.

Codebeispiel Contao 3

In diesem Code-Beispiel soll der Insert-Tag {{foo::bar}} ersetzt werden. Als erstes muss der Hook registriert werden.

 <?php 
 // Datei /system/modules/myinserttag/config/config.php
 
 // Registrieren des Hooks replaceInsertTags
 $GLOBALS['TL_HOOKS']['replaceInsertTags'][] = array('MyClass', 'myReplaceInsertTags');
 ?>

Nach der Registrierung des Hooks muss eine Klasse erstellt werden, welche eine Methode zur Ersetzung beinhaltet.
Dabei muss der Name der Klasse und der Methode identisch sein wie bei der Hook Registration.(logisch,oder?)
Außerdem muss der Name der Datei (ohne Endung) identisch sein wie der Name der Klasse.

 <?php 
 // Datei /system/modules/myinserttag/MyClass.php
 
 class MyClass extends Frontend
 {
    public function myReplaceInsertTags($strTag)
    {
        $arrSplit = explode('::', $strTag);
 
        if ($arrSplit[0] == 'foo')
        {
            if (isset($arrSplit[1]) && $arrSplit[1] == 'bar')
            {
                return 'Parameter bar';
            } else {
                return 'Fehler! foo ohne Parameter!';
            }
        }
        // nicht unser Insert-Tag
        return false;
      }
 }
 ?>

In der Methode myReplaceInsertTags muss man zuerst prüfen, ob man für den unbekannten Insert-Tag zuständig ist. Wenn man einen zweigeteilten Insert-Tag verwendet, splittet man den Tag anhand des :: (explode). Die geschweiften Klammern werden bereits von Contao entfernt und müssen daher nicht mehr entfernt werden.
Im Beispiel wurde zusätzlich noch eine Ausgabe ermöglicht, wenn der Parameter "bar" nicht angegeben wurde.

Hinweis: Damit Contao 3 nun die Klasse findet, muss nun im Backend der Autoload Generator für dieses Modul aufgerufen werde um die autoload.php zu generieren im config Verzeichnis.

Codebeispiel Contao 2

In diesem Code-Beispiel soll der Insert-Tag {{foo::bar}} ersetzt werden. Als erstes muss der Hook registriert werden.

 <?php if (!defined('TL_ROOT')) die('You can not access this file directly!');
 // Datei /system/modules/myinserttag/config/config.php
 
 // Registrieren des Hooks replaceInsertTags
 $GLOBALS['TL_HOOKS']['replaceInsertTags'][] = array('MyClass', 'myReplaceInsertTags');
 ?>

Nach der Registrierung des Hooks muss eine Klasse erstellt werden, welche eine Methode zur Ersetzung beinhaltet.
Dabei muss der Name der Klasse und der Methode identisch sein wie bei der Hook Registration.(logisch,oder?)
Außerdem muss der Name der Datei (ohne Endung) identisch sein wie der Name der Klasse.

 <?php if (!defined('TL_ROOT')) die('You can not access this file directly!');
 // Datei /system/modules/myinserttag/MyClass.php
 
 class MyClass extends Frontend
 {
    public function myReplaceInsertTags($strTag)
    {
        $arrSplit = explode('::', $strTag);
 
        if ($arrSplit[0] == 'foo')
        {
            if (isset($arrSplit[1]) && $arrSplit[1] == 'bar')
            {
                return 'Parameter bar';
            } else {
                return 'Fehler! foo ohne Parameter!';
            }
        }
        // nicht unser Insert-Tag
        return false;
      }
 }
 ?>

In der Methode myReplaceInsertTags muss man zuerst prüfen, ob man für den unbekannten Insert-Tag zuständig ist. Wenn man einen zweigeteilten Insert-Tag verwendet, splittet man den Tag anhand des :: (explode). Die geschweiften Klammern werden bereits von Contao entfernt und müssen daher nicht mehr entfernt werden.
Im Beispiel wurde zusätzlich noch eine Ausgabe ermöglicht, wenn der Parameter "bar" nicht angegeben wurde.

Insert-Tags und Seiten-Cache

Ist der Seiten Cache eingeschaltet, werden eigene Insert-Tags ersetzt vor der Abspeicherung der Seite im Cache.
Es ist jedoch seit TYPOlight Version 2.8 möglich, daß der Insert-Tag Platzhalter selbst im Cache gespeichert wird und dieser dann erst direkt vor Auslieferung an den Browser ersetzt wird.

Dazu muss der Insert-Tag mit einem Präfix "cache_" gebildet werden: {{cache_foo::bar}}
Im Quellcode der Klasse ist ebenfalls eine Anpassung an einer der Zeilen nötig, es werden nun beide Varianten geprüft:

 
 if ($arrSplit[0] == 'foo' || $arrSplit[0] == 'cache_foo')