Contao 5 - Twig Template Funktionen, Filter und Erweiterungen

'Mathias Arzberger'
Mathias Arzberger

Eine Übersicht über die wichtigsten Twig Funktionen und Filter in Contao 5.

Wenn du das Leerzeichen verwendest, setze keine Leerzeichen zwischen das Leerzeichen und das Begrenzungszeichen.

Mit der Freigabe unserer Contao Themes für Contao 5 setzen wir bereits bei einigen Templates auf Twig. Nun erreichen uns immer mehr Fragen "Was ist Twig?", "Wie fange ich am besten an?", "Wie kann ich die Twig-Templates anpassen?", "Wie kann ich auf eine bestimmte Variable zugreifen?" oder "Ist das nicht noch experimentell?".

Experimentell bedeutet nicht das es nicht auch eingesetzt werden darf. Moritz und das Core Team haben hier super Arbeit geleistet und bereits einige Core Templates auf Twig umgestellt. Du solltest dich also auf alle Fälle mit Twig beschäftigen. Wir werden es einsetzen und mit den nächsten Versionen unserer Erweiterungen und Themes immer öfter auf Twig zugreifen. Um dir den Einstieg zu erleichtern möchte ich in diesem Beitrag einige Funktionen und Filter vorstellen, die du auf alle Fälle kennen solltest.

Die Liste ist noch unvollständig und wird in den nächsten Tagen/Wochen immer weiter aktualisiert.
Du beginnst erst mit Twig, schau dir unser Twig Best Practices für Contao an.

Legende

Twig

Contao Core

0.1 Theme

Contao Utils Bundle

 

Twig Best Practices für Contao

Twig Funktionen und Filter

Kommentare

{# Dies ist ein Kommentar im Twig-Template #}

Um eine oder mehrere Codezeilen (oder einen Teil einer Zeile) auszukommentieren, verwende
die Syntax {# #}.

Anwendungsbeispiele

  • <p>Sie können auch nur einen {# Teil einer Zeile #} auskommentieren.</p>
  • {# Dies ist ein
    mehrzeiliger
    Kommentar.
    #}

Hinweis

Kommentare sind nicht nur nützlich, um Notizen zu deinem Code zu machen. Sie können auch bewirken, dass Codeblöcke nicht ausgeführt werden. Jeder Twig-Code, der zwischen Kommentar-Tags steht, wird nicht ausgeführt oder ausgegeben.

{# Der folgende Code wird nicht ausgeführt und es wird nichts ausgegeben
{% if category.posts %}
  Diese Kategorie enthält keine Beiträge
{% endif %}
#}

Ausgabe von Variablen

{{ foo.bar }}

Auf die verfügbaren Variablen kannst du mit {{ NAME_DER_VARIABLE }} zugreifen. So hast du auch Zugriff auf das aktuelle Model, da die Daten als Array in data bereitgestellt werden.

Anwendungsbeispiele

  • {{ data.guests }}
  • {{ data.addImage }}
  • {{ data.headline }}
  • {{ data.singleSRC }}
  • {{ var }}
  • {{ var|escape }}
  • {{ var|e }} {# Abkürzung für die Escape-Funktion einer Variablen #}

escape

{{ var|escape }}

Der escape Filter nutz für die Ausgabe eine kontextabhängige Strategie. Standardmäßig wird als HTML escaped. Der Escape-Filter unterstützt die folgenden Escape-Strategien für HTML-Dokumente html, js, css, url, html_attr.

Kurzform {{ var|e }}

Anwendungsbeispiele

  • {{ user.username|escape('js') }}
  • {{ user.username|e('js') }}

date

{{ data.tstamp|date("m/d/Y") }}

Der date Filter formatiert ein Datum in einem bestimmten Format.

Anwendungsbeispiele

  • {{ "now"|date("m/d/Y") }}
  • {{ post.published_at|date("F jS \\a\\t g:ia") }}
  • {{ data.tstamp is empty ? "" : data.tstamp|date("m/d/Y") }}

dump

{{ dump() }}

Über die Funktion dump() werden alle verfügbaren Variablen eines Twig-Templates ausgegeben. Durch Angabe einer bestimmten Variable wird nur diese ausgegeben.

Anwendungsbeispiele

  • {{ dump(data.headline) }}
  • {{ dump(user.username) }}
  • {{ dump(variable, variable2, variable3) }} {% Mehrere Variablen auf einmal debuggen %}

Weitere Twig Funktionen und filter findest du in der Twig Dokumentation. Wenn dir etwas wichtiges fehlt, schreib uns gern eine E-Mail und wir nehmen deine Idee mit auf.

Contao Core Funktionen und Filter

include

{% include "@Contao/component/_headline.html.twig" with {headline: {unit: 'h1', value: article.title}} %}

Die include Funktion kann dazu eingesetzt werden um Templates oder Dateien zu laden. Hier hat Contao die include Funktion von Twig erweitert um die Contao eigene Template Hierarchie abzubilden.

Anwendungsbeispiele

  • {{ include('@ContaoCore/Collector/contao.svg') }}
  • {{ include('@WebProfiler/Profiler/toolbar_item.html.twig', { link: true, name: 'contao', additional_classes: (((collector.summary.preview) ? 'sf-toolbar-status-yellow ' : '') ~ 'sf-toolbar-block-right') }) }}

prefix_url

{{ prefix_url }}

Über die Funktion prefix_url kannst du an eine beliebe Url den URL prefix anhängen lassen. Siehe Url Settings.

Anwendungsbeispiele

  • {{ prefix_url('meine-erste-seite.html') }}
  • {{ dump(prefix_url('mylink')) }}

Funktionen und Filter anderer Erweiterungen

0.1 Theme

Es gibt zwei spezielle Twig-Filter die derzeit nur im 0.1 Themes verwendet werden. Hast du den 0.1 Theme installiert, kannst du die Filter in jeder Funktion nutzen.

file

{{ uuid|file }}

Der Filter file kann genutzt werden um Attribute einer Datei auszugeben. Es muss die uuid angegeben werden und es kann optional das gewünschte Attribut angegeben werden.

Anwendungsbeispiele

  • {{ data.singleSRC|file }} => Ausgabe "6"
  • {{ data.singleSRC|file('pid') }} => Ausgabe "b"µø\x0F¿TP\x11Ýæ©9Óì«w░""
  • {{ data.singleSRC|file('tstamp') }} => Ausgabe "1666779006"
  • {{ data.singleSRC|file('type') }} => Ausgabe "file"
  • {{ data.singleSRC|file('path') }} => Ausgabe "files/zeroOne/img/think-big.png"
  • {{ data.singleSRC|file('extension') }} => Ausgabe "png"
  • {{ data.singleSRC|file('hash') }} => Ausgabe "d41d8cd98f00b204e9800998ecf8427e"
  • {{ data.singleSRC|file('lastModified') }} => Ausgabe "1666778776"
  • {{ data.singleSRC|file('name') }} => Ausgabe "think-big.png"
  • {{ data.singleSRC|file('importantPartX') }} => Ausgabe "0.0"
  • {{ data.singleSRC|file('importantPartY') }} => Ausgabe "0.0"
  • {{ data.singleSRC|file('importantPartWidth') }} => Ausgabe "0.0"
  • {{ data.singleSRC|file('importantPartHeight') }} => Ausgabe  "0.0"
  • {{ data.singleSRC|file('absolutePath') }} => Ausgabe "PATH/TO/CONTAO/INSTALLATION/files/zeroOne/img/think-big.png"

{%- set metaFields = data.singleSRC|file('metaFields') %}

{{ dump(metaFields) }}

{%- set metaData = data.singleSRC|file('metadata') %}

{{ dump(metaData) }}

 

elementStyles

{{ elementStyles|addToThemeStyles }}

Der Filter addToThemeStyles kann genutzt werden um SCSS Datei zur Stylesheet Generierung hinzuzufügen. Es werden alle Stylesheets berücksichtigt die im Theme Ordner unter "vendor/contao-themes-net/zero-one-thme-bundle/public/scss/" und im Files Ordner unter "files/zeroOne/scss/" liegen. Dies Funktion wird genutzt um für jede Seite nur die notwendigen CSS Dateien auszuliefern.

Anwendungsbeispiele

{{% set elementStyles = ['_buttons', 'contao/buttons'] %}
{{ elementStyles|addToThemeStyles}}

oder

{{ ['_buttons', 'contao/buttons']|addToThemeStyles }}

 

Contao Utils Bundle

Es gibt einige spezielle Twig-Filter die du durch die Installation des Contao Utils Bundle nutzen kannst.

deserialize

{{ array|deserialize }}

Der Filter deserialize kann genutzt werden um ein Array zu deserialisieren.

Anwendungsbeispiele

  • {{ user.group|deserialize }}
  • {%- set metaFields = user.group|deserialize %}

 

Twig Best Practices

Bitte nutze beim erstellen von Twig Templates bewerte Praktiken um den Code für jeden lesbar zu gestalten. Einige Best Practices möchten wir die hier vorstellen.

Einrücken des Codes

Rücke deinen Code mit einem Tabulator innerhalb von Tags ein. Dies verbessert die Lesbarkeit. In den meisten Editoren entspricht ein Tabulator 4 Leerzeichen. In den Templates von pdir wirst du allerdings 2 Zeichen für das Einrücken finden, hier weichen wir vom Standard ab, weil größere Templates sonst zu schnell nach rechts "ausufern".

{% if category.posts %}
    {% for post in category.posts %}
        <p><a href="{{ post.url }}">{{ post.postTitle }}</a></p>
    {% endfor %}
{% endif %}

Abstand zwischen Begrenzungszeichen

Setze (und nur ein) Leerzeichen nach dem Beginn eines Trennzeichens ( {{, {%, und {# ) und vor dem Ende eines Trennzeichens ( }}, %}, und #} )

{{ variable }}
{% if variable %}
{% endif %}
{# comment #}

Wenn du das Leerzeichen verwendest, setze keine Leerzeichen zwischen das Leerzeichen und das Begrenzungszeichen.

{{- variable -}}
{%- if variable -%}{%- endif -%}
{#- comment -#}

Abstand zwischen den Operatoren

Setze ein (und nur ein) Leerzeichen vor und nach den folgenden Operatoren: Vergleichsoperatoren ( ==, !=, <, >, >=, <= ), mathematische Operatoren ( +, -, /, *, %, //, ** ), logische Operatoren ( not, and, or ), ~, is, in, und der ternäre Operator ( ?: ).

{{ 1 + 2 }}
{{ foo ~ bar }}
{% if variable is not null %}
{{ true ? true : false }}

Setze keine Leerzeichen vor oder nach ...

{% for i in 1..10 %}{% endfor %}

Abstände in Arrays und Hashes

Setze ein (und nur ein) Leerzeichen nach dem : Zeichen in Hashes und , in Arrays und Hashes.

{{ [1, 2, 3] }}
{{ {'foo': 'bar', 'foo2': 'bar2'} }}

Setze keine Leerzeichen beim Öffnen und Schließen von Arrays und Hashes.

{% set array = [1, 2, 3] %}
{% set hash = {'foo': 'bar' } %}

Abstände zwischen Array-, Hash- und Bereichsoperatoren

Setze keine Leerzeichen vor oder nach . oder [ ].

{{ user.firstName }}
{{ user[firstName] }}

Abstand zwischen den Klammern

Setze in Ausdrücken keine Leerzeichen nach einer öffnenden und vor einer schließenden Klammer.

{{ 1 + (5 * 3) }}

Setze keine Leerzeichen vor und nach den Klammern, die für Filter- und Funktionsaufrufe verwendet werden.

{{ variable|truncate(100) }}
{{ range(1, 10) }}

Abstand zwischen Begrenzungszeichen für Zeichenketten

Setze keine Leerzeichen vor oder nach Zeichenkettenbegrenzern (z. B. Anführungszeichen ' oder " ), es sei denn, du beabsichtigst, ein Leerzeichen in die Zeichenkette einzufügen.

{{ "string" }}
{{ 'string' }}

{{ ' string' }} {% Es soll ein Leerzeichen vor "string" stehen. %}

Filterabstände

Setze keine Leerzeichen vor oder nach dem Filteroperator |.

{{ variable|upper|lower }}
{{ variable|truncate(100) }}

Letzte Update: 29.10.2022

Zurück

pdir+ webtools für Freelancer & Agenturen
Instagram
Facebook
Twitter
LinkedIn