Version vom 19. September 2014, 10:01 Uhr

Twig ist eine Moderne und beliebte Template Engine. Sie wird unter anderem in Symfony2 und vielen weiteren Systemen eingesetzt. Twig ist recht jung, die bekannteste kompilierende Template Engine für PHP düfte wohl Smarty sein.

Die Contao Erweiterung twig bringt Twig nun auch nach Contao.

Tipps und Tricks

Twig und Insert-Tags

Twig verwendet für Variablen die gleiche Syntax wie Contao für die Insert-Tags: {{...}}. Will man Insert-Tags in einem Twig Template verwenden, muss man ein bisschen kreativ werden und den Insert-Tag als String in einer Twig Variable ausgeben {{ '{{...}}' }}, z.B. {{ '{{link::123}}' }}.

Twig Elemente

Twig stellt ein Inhaltselement und ein Frontend Modul bereit, dieses bietet ähnlich dem HTML Element die Möglichkeit einfach Twig Code im Backend anzugeben, der im Frontend ausgegeben wird.

Achtung: Die Twig Element stehen erst ab Version 1.4 zur Verfügung.

Twig Templates

Twig Templates werden wie Contao Templates in den templates Verzeichnissen abgelegt. Sie erhalten zusätzlich die Endung *.twig, z.B. ce_mycontent.html5.twig oder ce_mycontent.xhtml.twig.

Achtung: Ab Version 1.2 ist Autoescape deaktiviert! (Der Filter raw ist daher nicht mehr notwendig.)

Globale Variablen

Die twig Erweiterung liefert einige globale Variablen mit, auf die man in den Templates Zugriff hat.

• REQUEST_TOKEN Der aktuell gültige request token.
• REFERER_ID Die aktuell gültige referer ID.
• _lang bietet Zugriff auf $GLOBALS['TL_LANG'], z.B. {{ _lang.MSC.confirm.0 }}
• _dca bietet Zugriff auf $GLOBALS['TL_DCA'], z.B. {{ _dca.tl_content.fields.headline.label.0 }}
• _config bietet Zugriff auf $GLOBALS['TL_CONFIG'], z.B. {{ _config.dateFormat }}
• _env bietet Zugriff auf Environment, z.B.{{ _env.request }}
• _db bietet Zugriff auf das Datenbankobjekt, z.B. {{ _db.query('SELECT * FROM tl_user').fetchAllAssoc() }} (siehe auch die speziellen Database-Filter Funktionen)
• _page bietet Zugriff auf die aktuelle Page $GLOBALS['objPage'], z.B.{{ _page.title }}
• _member bietet Zugriff auf das aktuellen Frontend Mitglied, ist false falls kein Mitglied angemeldet ist
• _user bietet Zugriff auf den aktuellen Backend User, ist false falls kein User angemeldet ist
• _session bietet Zugriff auf $_SESSION
• _referer liefert den aktuellen Referer
• _theme liefert das aktuelle Backend Theme system/themes/{{ _theme }}/images/reload.gif

Achtung: _env, _page, _member und _user stehen erst ab Version 1.4.0 zur Verfügung.

Achtung: REFERER_ID stehen erst ab Version 1.4.2 zur Verfügung.

Achtung: _referer und _session stehen erst ab Version 1.6.0 zur Verfügung.

Achtung: _theme stehen erst ab Version 1.11.0 zur Verfügung.

Allgemeine Filter Funktionen

Die twig Erweiterung liefert einige allgemeine Filter Funktionen.

• deserialize, z.B. {{ row.groups|deserialize }} oder {{ row.groups|deserialize(true) }}
• standardize, z.B. {{ row.title|standardize }}
• dateFormat format einen Zeitstempel nach dem globalen Datumsformat, z.B. {{ row.tstamp|dateFormat }}
• datimFormat format einen Zeitstempel nach dem globalen Datum+Zeitformat, z.B. {{ row.tstamp|datimFormat }}
• vformat wie format akzeptiert aber ein Array als Formatargumente (Analogie zu sprintf und vsprintf), z.B. {{ '%s %s'|vformat({'foo', 'bar'}) }}
• url erzeugt eine Frontend URL, z.B. {{ _page|url }}, akzeptiert ein DB Objekt, eine Collection, eine Page ID oder ein Row-Array.

Achtung: vformat steht erst ab Version 1.2.1 zur Verfügung.

Achtung: url steht erst ab Version 1.4 zur Verfügung.

Datenbank Filter Funktionen

Neben dem _db Objekt werden auch Filterfunktionen bereitgestellt, um auf die Datenbank zuzugreifen.

• prepare bereitet ein Statement vors (vgl. Database::prepare), z.B. {% set stmt = 'SELECT * FROM tl_user WHERE admin=?'|prepare %}
• set fügt SET oder UPDATE einem Statement hinzu (vgl. Database_Statement::set), z.B. {% set stmt = stmt|set({ 'foo': 'foo', 'bar': 'bar' }) %}
• execute führt ein Statement aus (vgl. Database::execute und Database_Statement::execute), z.B. {% set result = stmt|execute(1) %} oder {% set result = 'SELECT * FROM tl_user WHERE admin=?'|execute(1) %}
• query führt ein Statement direkt aus (vgl. Database::query), z.B. {% set result = 'SELECT * FROM tl_user'|query %}

Kombinierte Beispiele

{% set result = 'SELECT * FROM tl_user WHERE admin=?'|prepare|execute(1) %}

{% set result = 'UPDATE tl_user %s WHERE id=?'|prepare|set({ 'admin': 1 })|execute(id) %}

{% for row in 'SELECT * FROM tl_user'|query %}
    {# do somethink with row #}
{% endfor %}

Komplexe Funktionen

image Funktion/Filter

(Ab Version 1.2)

Mit der/dem image Funktion/Filter lassen sich Bilder einfach ausgeben und in der Größe ändern. image ist ein Shortcut auf generateImage und ggf. getImage.

Beispiel - Bild ausgeben

{{ image('path/to/image.png') }}

{{ 'path/to/image.png'|image }}

Beispiel - Bild ausgeben mit Größenänderung und Attributen (einfach)

{# {{ image(src, width, height, mode, alt, attributes) }} #}
{{ image('path/to/image.png', '800', '600', 'center_left', 'Ich bin ein Alt Text', 'title="Ich bin der Titel"') }}

Beispiel - Bild ausgeben mit Größenänderung und Attributen (erweitert)

{# {{ image(src, settings) }} #}
{{ image('path/to/image.png', {'alt':'Ich bin ein Alt Text'}) }}

{# {{ image(src, settings) }} #}
{{ image('path/to/image.png', {'alt':'Ich bin ein Alt Text', 'attributes':'title="Ich bin der Titel"'}) }}

{# {{ image(src, settings) }} #}
{{ image('path/to/image.png', {'width':'800', 'height':'600', 'mode':'center_right', 'alt':'Ich bin ein Alt Text', 'attributes':'title="Ich bin der Titel"'}) }}

{# {{ image(src, settings) }} #}
{{ image('path/to/image.png', {'width':'800', 'height':'600'}) }}

messages Funktion

(Ab Version 1.2)

Die messages Funktion ist ein Shortcut für getMessages().

{{ messages() }}

TwigFrontendTemplate und TwigBackendTemplate

Um Twig zu verwenden, werden anstelle der bekannten FrontendTemplate und BackendTemplate Klassen, die Twig Klassen TwigFrontendTemplate und TwigBackendTemplate verwendet. Diese Klassen verhalten sich genau so, wie ihre Contao Pendanten, das gilt auch für die Hooks parseTemplate, parseFrontendTemplate und parseBackendTemplate die ebenfalls verfügbar sind.

$objTemplate = TwigFrontendTemplate('ce_mycontent');
$objTemplate->setData($arrData);
$objTemplate->foo = 'bar';
$strBuffer = $objTemplate->parse();

TwigTemplate

Im Gegensatz zu TwigFrontendTemplate und TwigBackendTemplate ist TwigTemplate nicht für Frontend oder Backend konzipiert und führt entsprechend auch keinerlei Frontend oder Backend spezifischen Manipulationen am Template durch. Außerdem ist eint TwigTemplate stateless, d.h. man kann dem Template keine Variablen zuweisen, sondern übergibt diese der TwigTemplate::parse() Methode.

Man kann TwigTemplate auch als generisches Template bezeichnen, das für jede Art von Templates eingesetzt werden kann.

# use the template my_template.twig
$template = TwigTemplate('my_template');
$buffer = $template->parse();
 
# alternative
$template = TwigTemplate();
$template->setTemplateName('my_template');
$buffer = $template->parse();

# use the template my_template.html5.twig
$template = TwigTemplate('my_template', 'html5');
$buffer = $template->parse();
 
# alternative
$template = TwigTemplate('my_template');
$template->setFormat('html5');
$buffer = $template->parse();

# use the template my_template.html5 (inadvisable)
$template = TwigTemplate('my_template', null, 'html5');
$buffer = $template->parse();
 
# alternative
$template = TwigTemplate('my_template');
$template->setFileExtension('html5');
$buffer = $template->parse();

# pass parameters to my_template.html5.twig
$params = array(
    'foo' => 'bar'
);
$template = TwigTemplate('my_template', 'html5', 'twig');
$buffer = $template->parse($params);

Twig Module und Inhaltselemente

Um Twig in einem Frontend Modul, Backend Modul oder Inhaltselement zu nutzen, gibt es 3 spezielle Klassen.

• TwigModule ist eine spezielle Form von Module die TwigFrontendTemplate anstelle von FrontendTemplate verwendet.
• TwigBackendModule ist eine spezielle Form von BackendModule die TwigBackendTemplate anstelle von BackendTemplate verwendet.
• TwigContentElement ist eine spezielle Form von ContentElement die TwigFrontendTemplate anstelle von FrontendTemplate verwendet.

class MyContent extends TwigContentElement
{
    protected $strTemplate = 'ce_mycontent';
 
    public function compile()
    {
        // ...
    }
}

Basis-Templates

Es werden 8 Basis-Templates zur Verfügung gestellt.

• ce_container.html5.twig
• ce_container.xhtml.twig
• mod_container.html5.twig
• mod_container.xhtml.twig

Diese sind nicht groß, bieten aber die grundlegenden Elemente die jedes Inhaltselement oder Modul mit sich bringt.

<div class="{{ class }} block"{{ cssID }}{% if style %} style="{{ style }}}"{% endif %}{% block attributes %}{% endblock %}>
    {% block headline %}
    {% if headline %}
 
    <{{ hl }}>{{ headline }}</{{ hl }}>
    {% endif %}
    {% endblock %}
 
    {% block content %}{% endblock %}
</div>

Achtung: Die *_noindex.*.twig Templates steht erst ab Version 1.10 zur Verfügung.

Für Module/Inhaltselemente die nicht für die Suche indiziert werden sollen, gibt es zusätzlich noch:

• ce_container_noindex.html5.twig
• ce_container_noindex.xhtml.twig
• mod_container_noindex.html5.twig
• mod_container_noindex.xhtml.twig

Diese sind lediglich noch mit einem und umgeben.

<!-- indexer::stop -->
<div class="{{ class }} block"{{ cssID }}{% if style %} style="{{ style }}}"{% endif %}{% block attributes %}{% endblock %}>
    {% block headline %}
    {% if headline %}
 
    <{{ hl }}>{{ headline }}</{{ hl }}>
    {% endif %}
    {% endblock %}
 
    {% block content %}{% endblock %}
</div>
<!-- indexer::continue -->

Im eigenen Template lässt sich das Basis-Template sehr einfach verwenden:

{% extends 'mod_container.html5.twig' %}
 
{% block content %}
    Put your content here
{% endblock %}

TwigPagination

Die Klasse TwigPagination ist eine "Templatebasierende" Pagination die auf Twig aufsetzt. Sie wird genau so eingesetzt wie die Pagination Klasse, kann aber über das Template pagination.html5.twig und pagination.xhtml.twig angepasst werden.

TwigCustomPagination

Die Klasse TwigCustomPagination ist ebenfalls eine Pagination die auf Twig aufsetzt. Allerdings können bei dieser Pagination die URLs aus der die Pagination erzeugt wird selbst festgelegt werden. Das ist praktisch, wenn man bspw. über mehrere Items eine Pagination erstellen will.

$links = array(
    'news/items/record_1.html',
    'news/items/record_2.html',
    'news/items/record_3.html',
    'news/items/record_4.html',
    'news/items/record_5.html',
    'news/items/record_6.html',
    'news/items/record_7.html',
    'news/items/record_8.html',
    'news/items/record_9.html',
    'news/items/record_10.html',
    'news/items/record_11.html',
    'news/items/record_12.html',
    'news/items/record_13.html',
    'news/items/record_14.html',
    'news/items/record_15.html',
    'news/items/record_16.html',
    'news/items/record_17.html',
    'news/items/record_18.html',
    'news/items/record_19.html',
    'news/items/record_20.html',
);
$pagination = new TwigCustomPagination($links);
echo $pagination->generate();

Man muss darauf achten, dass die URL auch so aufgerufen wird, ansonsten findet die Pagination nicht das aktuelle Item. Außerdem hat diese Pagination den Nachteil, dass man alle URLs zur Verfügung stellen muss. Wenn die Berechnung der Links sehr kostenintensiv ist, muss der Entwickler entsprechende Optimierung betreiben, in dem er z.B. nur die Links zur Verfügung stellt, die auch angezeigt werden.

$links = array(
    'news/items/record_1.html', // "go to first" link
    '', // empty dummy
    '', // empty dummy
    '', // empty dummy
    '', // empty dummy
    '', // empty dummy
    '', // empty dummy
    '', // empty dummy
    'news/items/record_9.html', // visible link
    'news/items/record_10.html', // visible link
    'news/items/record_11.html', // visible link
    'news/items/record_12.html', // active link
    'news/items/record_13.html', // visible link
    'news/items/record_14.html', // visible link
    'news/items/record_15.html', // visible link
    '', // empty dummy
    '', // empty dummy
    '', // empty dummy
    '', // empty dummy
    'news/items/record_20.html', // "go to last" link
);
$pagination = new TwigCustomPagination($links);
echo $pagination->generate();

Abhängig von der Anzahl der angezeigten Links (Standardmäßig sind das 7), muss der Entwickler die notwendigen Links zur Verfügung stellen.

TwigHybrid

Die Klasse TwigHybrid ist eine Hybrid Implementierung die auf Twig aufsetzt. Sie wird genau so eingesetzt, wie die originale Hybrid Klasse von Contao.

TwigSimpleHybrid

Die Klasse TwigSimpleHybrid ist eine vereinfachte Form von TwigHybrid die ohne zweite Tabelle aus kommt. Anstelle die Daten aus einer zweiten Tabelle zu laden, verwendet TwigSimpleHybrid einfach den aktuellen Record (tl_content oder tl_module) als Datenquelle. Das hat natürlich den Nachteil, dass man die Datenfelder sowohl in der Tabelle tl_content, als auch in der Tabelle tl_module anlegen muss, dafür hat man eine Klasse, die sowohl als Inhaltselement, als auch als Modul verwendet werden kann. Von der Klassenbenennung verhält sich der Hybrid wie ein Modul, d.h. auch bei Inhaltselementen wird der Prefix mod_ anstelle von ce_ verwendet.

config.php

// register content element
$GLOBALS['TL_CTE']['my_ext']['my_element'] = 'HybridMyElement';
 
// register frontend module
$GLOBALS['FE_MOD']['my_ext']['my_element'] = 'HybridMyElement';

HybridMyElement.php

class HybridMyElement
    extends TwigSimpleHybrid
{
    /**
     * @var string
     */
    protected $strTemplate = 'mod_my_element';
 
    public function compile()
    {
        $this->Template->foo = $this->bar;
    }
}

Twig Erweitern

Gesteuert wird Twig über die ContaoTwig Klasse. Bei dieser handelt es sich um eine Singleton Klasse, die die Loader und das Twig Environment bereitstellt. Wenn Twig erstmals initialisiert wird (also bei der 1. Verwendung) wird der initializeTwig Hook getriggert, mit dem man Twig Erweitern kann.

$GLOBALS['TL_HOOKS']['initializeTwig'][] = array('MyClass', 'hookInitializeTwig');
 
class MyClass
{
    public function hookInitializeTwig(ContaoTwig $contaoTwig)
    {
        // Twig Environment anpassen
        /** @var Twig_Environment $twig */
        $twig = $contaoTwig->getEnvironment();
        // do somethink with $twig
 
        // Den Standard Filesystem Loader anpassen
        /** @var Twig_Loader_Filesystem $filesystemLoader */
        $filesystemLoader = $contaoTwig->getLoaderFilesystem();
        $filesystemLoader->addPath('custom/path/to/my/templates');
 
        // Eigenen Template Loader hinzufügen
        /** @var Twig_Loader_Chain $loader */
        $loader = $contaoTwig->getLoader();
        $loader->addLoader(new MyTwigLoader());
    }
}