Statamic nutzt Antlers als Template-Engine. Antlers ist eine Erfindung von Statamic und dient der Ausgabe von Informationen. Es ist einfach und schnell zu lernen, hat aber auch seine Beschränkungen.

Antlers ist eine Domain Specific Language ("DSL") für das Frontend von Statamic. Es ist vergleichbar zu anderen Template Sprachen wie Twig, Blade oder Smarty. Antlers ermöglicht es Entwickler:innen, den Programmfluss im Frontend zu kontrollieren und Daten auszugeben. Dazu verwendet Antlers Tags, die von geschweiften Klammern umgeben sind.

Statamic hat einen Parser für Antlers Dateien. Alle Dateien in /resources/views/*.antlers.html werden durch diesen gerendert.

Datentypen

Statamic speichert die Daten in Yaml Files im Verzeichnis /content ab. Diese Datenstrukturen werden indexiert und sind beim Aufruf einer Seite im Frontend verfügbar. Antlers muss/kann mit den in der Yaml definierten Datentypen umgehen. Dazu gehören: String, Integer, Float, Array und Directory.

Datenausgabe

Die Struktur der Daten im CMS werden von Statmic über Blueprints definiert. Hat man eine Datenstruktur definiert und will diese ausgeben, dann kann man den verwendeten Handler in geschweifte Klammern setzen. Im folgenden Beispiel geben wir das Textfeld "Title" (String) über Antlers aus:

<h1>noparse_b7f3919a99d4093361004e8fd25d5a1e</h1>

Ausgabe:

<h1>Beitragstitel</h1>

Je nach Feldtype kann die darin enthaltene Struktur komplex sein. Über den Bueprint können wir ein Feld vom Type Array erstellen. Zum Beispiel, wenn wir ein Replicator Field "Titles" (Array) verwenden mit einem eingebetteten Textfeld "Title" (String). Wollen wir nun alle Titel ausgeben, dann können wir einen einfachen Loop generieren:

noparse_a74b1d5b1b157739e325b4ba2ab38279
	<h2>noparse_b7f3919a99d4093361004e8fd25d5a1e</h2>
noparse_fc2c4b68b1e7e15ecf7c51de247a9d7d

Ausgabe:

<h2>Erster Beitragstitel</h2>
<h2>Zweiter Beitragstitel</h2>
<h2>Dritter Beitragstitel</h2>

Hier wird durch alle Titel iteriert und innerhalb des Scopes der Schlaufe können wir dann auf die eingebetteten Daten zugreifen.

Viele Feldtypen in Statamic speichern mehr als nur einfachen Text. Legt man ein Feld vom Type Assets an, dann bietet das Feld Zugriff auf die Url des Bildes und den alternativen Text. In Yaml wird dies als Map (Dictionaries) abgelegt. In Antlers können wir bequem über folgenden Syntax darauf zugreifen:

<img src="feature_image:src" alt="feature_image:alt">

Daten modifizieren

Meist reicht es nicht Daten einfach auszugeben. Häufig müssen die Daten noch formatiert oder transformiert werden. Dazu bietet Statamic sogenannte Modifiers an. Diese können Daten vor der Ausgabe verändern und sind ein einfaches Mittel um Daten anzupassen:

<h1>noparse_2ba17e9534b8b17cf0a38cd098e3b084</h1>

Ausgabe:

<h1>BEITRAGSTITEL</h1>

Die Modifier können auch helfen, direkt auf ein Element eines Arrays zuzugreifen. Will ich das erste Element eines Arrays, dann kann ich dies wie folgt machen:

<h1>noparse_131589ca3ecab635f5e7e90f6a4c3068</h1>

Ausgabe:

<h1>ERSTER BEITRAGSTITEL</h1>

Modifiers können helfen, Daten zu formatieren. Klassischerweise will man ein Datum länderspezifisch formatieren:

noparse_6c2dcb062d314547d2e698887f9adef9

Ausgabe:

23.10. 2022

Modifier können fast beliebig kombiniert werden. Ähnlich wie Unix Commands kann man Modifier verbinden (pipen) und so den gewünschten Effekt erzielen:

noparse_2f5dd042ebb7fc08cce2190635b73748

Ausgabe:

UEBER UNSER TEAM

Auch zum Vergleich von Daten können Modifier verwendet werden. Dazu weiter unten mehr.

Programmfluss

Neben der Ausgabe von Daten kann auch der Fluss des Programms durch Antlers gesteuert werden. Dies ist wichtig, will man Daten nur unter gewissen Bedingungen anzeigen oder will man durch eine Menge an gleichförmigen Daten iterieren.

If und else

Im folgenden Beispiel wird geprüft, ob ein feature_image existiert oder nicht:

noparse_4a2ac52c4f424d7b1c70429f35207864
	Bild existiert
noparse_3a0a06724dfc4260f640a76aa21acf93
	Bild existiert nicht
noparse_6bcd448fd3428ca9411a416c06c66026

Häufig ist die Abfrage jedoch komplexer als "existiert das Feld". Man will beispielsweise wissen, ob ein Text eine gültige E-Mail-Adresse darstellt. Hierzu kann man wiederum Modifiers nutzen, die einen Boolean zurückgeben. Im folgenden Beispiel prüfen wir, ob contact_email eine gültige E-Mail-Adresse repräsentiert und geben diese verschleiert aus:

noparse_26140dd03fee9819a384047d97b81b33
	<a href="mailto:noparse_89c390215d881599134cf2ecfee2fb1b">noparse_80911cf34472782e9000a0d722c89b61 </a>
noparse_6bcd448fd3428ca9411a416c06c66026

Loops

Antlers kennt keine klassischen for, foreach oder while -Loops. Schlaufen werden meist mittels der Daten generiert. Hat man ein Array von Images, dann kann man wie folgt durch dessen Werte iterieren:

noparse_fbdc80d34eb32fafe57d971574e80eaf	
     <img src="noparse_ba70a1b4f844d0c3e0c0047df810e605" alt="noparse_068e4a82d83cb97c5b8a7986a6739c45">
noparse_7d4755b8f50c43a85cc5d9a9e52ebc16

Das Tag loop ermöglicht es, eine Schlaufe zu konstruieren.

Tags

Bis jetzt haben wir uns mit den Grundlagen von Antlers beschäftigt. Diese ermöglichen es Daten auszugeben, die bereits im Kontext eines Seitenaufrufs von Statamic bereitgestellt wurden. Ruft man im Browser direkt eine Seite auf, dann stehen die Inhalte der Seite im Kontext zur Verfügung. Diese können dann einfach als Variablen, z.B. noparse_b7f3919a99d4093361004e8fd25d5a1e, in der View ausgegeben werden.

Häufig will man aber darüber hinaus mit Statamic interagieren. Man will zusätzliche Daten abfragen oder Interaktionen zwischen der Nutzer:in und Statamic zulassen. Tags ermöglichen genau dies. Es sind zusätzliche Bausteine, die Daten aus Statamic holen und filtern können. Mit den Tags lassen sich Formulare bauen und Interaktionen mit der Nutzer:in werden möglich.

Collection

Das am meisten verwendete Tag ist collection. Das Tag ermöglicht es, eine Liste von Einträgen aus Statamic abzufragen. Hat man beispielsweise eine Collection "Posts" und will auf der Startseite eine Liste der letzten zehn Einträge darstellen, dann kann dies mit dem Collection-Tag zusammengestellt werden.

Im folgenden Beispiel werden die letzten Zehn Beiträge der Collection Posts abgebildet. Pro Post wird der Titel und die Anzahl Kommentare ausgegeben:

<section>
noparse_331197aee927c1d133ca322c0dfcd304
	<article>
		<h3><a href="noparse_721f9ce8db056acb6fb739e19fc8e3a3">noparse_b7f3919a99d4093361004e8fd25d5a1e</a></h3>
		<small>Comments: noparse_60f4c165195ba7b1691c14331e085435</small>
	</article>
noparse_d8c88461c29a721a228a0e7363499fa5
</section>

Das collection Tag bietet verschiedene Möglichkeiten zum Filtern der Daten an. Folgendes Snippet zeigt alle Produkte, die der Kategorie "spielzeug" zugeordnet sind:

noparse_5a703fca315602aa7989aca3f7d2b19a
	<h3><a href="noparse_721f9ce8db056acb6fb739e19fc8e3a3">noparse_b7f3919a99d4093361004e8fd25d5a1e</a></h3>
noparse_e546bdf985e81aa1c58c7fcfe3c856c7

Oder es sollen alle Artikel und Produkte eines Autors gelistet werden:

noparse_a0103afe01421daf3bc258024bb7c550
	<h3><a href="noparse_721f9ce8db056acb6fb739e19fc8e3a3">noparse_b7f3919a99d4093361004e8fd25d5a1e</a></h3>
noparse_1f6416b59ab9c972d9ee0fd670c75825

Bei grösseren Seiten muss auch durch die Resultate geblättert werden können. Statamic bietet hier eine einfache Pagination an:

noparse_2e67b2734eab71f67ee77fb835186b0f
    noparse_4e888f1b3dec93176bb07ead12d39235
        <p>Keine Resultate.</p>
    noparse_6bcd448fd3428ca9411a416c06c66026
    noparse_0e0a5e370cc841b0ffa30440743e7588
	<article>
		<h3><a href="noparse_721f9ce8db056acb6fb739e19fc8e3a3">noparse_b7f3919a99d4093361004e8fd25d5a1e</a></h3>
		<small>Autor: noparse_f7313302a51e6da7f22a10575417145f</small>
	</article>
    noparse_92885649d5794acc51f3c5e2b9c5bf89
    noparse_ab421025ac0292aab0809e7d70ed863e
        <a href="noparse_22148b75dbde5483c2a65519d7833c43">⬅ Vorherige Seite</a>
        noparse_d9db7ffcab73d9db8073260b496b853f von noparse_01276df4b8084c027cbfc5a75cbc1110 Seiten
        (Total noparse_d37f5e40cd364b0700f193344a580a63 Beiträge)
        <a href="noparse_d10be1efa1ba89588928636ef761aedd">Nächste Seite  ➡</a>
    noparse_9b08dbfd2b5906a9baebb6f50b7a4695
noparse_d8c88461c29a721a228a0e7363499fa5

Taxonomy

Neben collection ist taxonomy eines der am häufigsten genutzten Tags. Eine Taxonomy ist eine Ordnungsstruktur für Artikel. Klassische Taxonomien sind Tags oder Kategorien. Artikel werden diesen zugeordnet und können entsprechend gefiltert werden. Dadurch kann man Artikel inhaltlich gruppieren.

Mit dem Taxonomy-Tag können alle Tags oder Kategorien abgefragt werden. Dies ist beispielsweise hilfreich, wenn ein Filter für alle Artikel erstellt werden soll.

Im folgenden soll eine Liste aller möglichen Tags ausgegeben werden, mit der Anzahl verlinkter Artikel:

<ul>
noparse_172da330f0bfbff164035c79758941ac
    <li><a href="noparse_721f9ce8db056acb6fb739e19fc8e3a3">noparse_b7f3919a99d4093361004e8fd25d5a1e (noparse_6578b775204ca75b95bf73aaa047e045</a></li>
noparse_7d9880fc296622cf79fcf0cca0fe2209
</ul>

Nav

Das nav Tag frag die in Statamic erstellte Navigation ab. Eine Navigation ist eine hierarchische Struktur. In Statamic werden hierarchische Inhaltstypen wie Navigationen oder hierarchische Collections als sogenannte structures abgebildet.

Im folgenden Beispiel wird eine Navigation mit einer maximalen Verschachtelungstiefe von drei Ebenen abgebildet. Die noparse_8207a068acd3179f2cb3f451407f53bc-Anweisung wiederholt die Anweisungen des Nav Tages für jedes Kind des aktuellen Knotens.

<ul>
   noparse_180cb8ed660b2523782baf92bcae32a1
      <li>
         <a href="noparse_721f9ce8db056acb6fb739e19fc8e3a3"noparse_dd4fbbd9841cf829da2fc3510c322bdd class="active"noparse_6bcd448fd3428ca9411a416c06c66026>noparse_b7f3919a99d4093361004e8fd25d5a1e</a>
         noparse_dd4fbbd9841cf829da2fc3510c322bdd
            noparse_1d09647aa8b299369c94eabfdd298ccc
               <ul>noparse_946bf27e3d4442ce881e163719728f51</ul>
            noparse_6bcd448fd3428ca9411a416c06c66026
         noparse_6bcd448fd3428ca9411a416c06c66026
      </li>
   noparse_df1516e545c192c0b298da86c7bc3ca5
</ul>

Ausgabe:

<ul>
	<li>
	         <a href="/erster-beitrag" class="active">erster Beitrag</a>
	</li>
	<li>
	         <a href="/zweiter-beitrag" class="active">zweiter Beitrag</a>
		<ul>
			<li>
			         <a href="/dritter-beitrag">dritter Beitrag</a>
			</li>
		</ul>
	</li>
</ul>

Layout, Templates und Partials

Um das Thema Frontend Basics abzuschliessen, muss geklärt werden, wie Layouts, Templates und Partials miteinander interagieren. Gibt es wie in WordPress eine Template Hierarchie? Die Antwort lautet Nein. Es ist der Entwickler:in überlassen, welches Template für welchen Aspekte der Seite zuständig ist.

Wird eine Statamic Seite aufgerufen, dann lädt Statamic ein Layout für die Seite. Standardmässig ist dies /resources/views/layout.antlers.html. Im Layout wird die Basisstruktur der Webseite definiert. Innerhalb des Layouts wir dann je nach Inhalt ein Template oder ein Partial geladen.

Das folgende Layout-Beispiel aus der Statamic Basisinstallation definiert einige Basics einer HTML-Seite und ruft dann noparse_b7d9a11ffa3e16af77442ad6d4c5721b auf. Template_content ruft das im Entry definierte Template auf oder lädt default.antlers.html:

<!doctype html>
<html lang="noparse_896f9d8326a8774e7a021f151813d378">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>noparse_d7224b838425e8c8a0c4830b93108f9b</title>
        <link rel="stylesheet" href="noparse_a08833c1019befab20cb24d934bf05ed">
    </head>
    <body class="bg-gray-100 font-sans leading-normal text-gray-800">
        <div class="max-w-4xl mx-auto px-2 lg:min-h-screen my-2">
            noparse_b7d9a11ffa3e16af77442ad6d4c5721b
        </div>
        <script src="noparse_db888c3cf5afc3e0bcb42ea8a2f51868"></script>
    </body>
</html>

Ein Template definiert das Markup des Inhaltes. Die konkrete Ausformulierung des Templates richtet sich nach dem Inhalt. Im folgenden ein Beispiel für eine sehr simples Template zur Darstellung einer Einzelseite. Das Template kann als /resources/views/page.antlers.html gespeichert werden. Damit das Template angewandt wird, muss es der Seite zugewiesen werden. Dazu dient das template fieldtype:

<article>
	<h1>noparse_b7f3919a99d4093361004e8fd25d5a1e</h1>
	<p>Von <address class="inline" rel="author">noparse_b4d2005370371723e209ea4b9702c2e2</address></p>
	noparse_c2314c3a9c3412a38d14b312d3df83c1
</article>

Unter Partials versteht Statamic Elemente, die an beliebigen Stellen geladen werden können. So können wiederverwendbare Komponenten erstellt werden und der Code wird insgesamt besser organisiert. Ein Partial kann beispielsweise für ein Fieldset verwendet werden. Oder der Footer kann in ein Partial ausgelagert werden. Partials können an beliebiger Stelle in Antlers eingebunden werden:

<article>
	<h1>noparse_b7f3919a99d4093361004e8fd25d5a1e</h1>
	noparse_726d603b3b902280c317fec40b0a1dc2
	noparse_9410663f7a0d0cf945d5fa942c66dee1
	noparse_c2314c3a9c3412a38d14b312d3df83c1
</article>

Das Partial /resources/views/partials/author.antlers.html wird über das Tag noparse_9410663f7a0d0cf945d5fa942c66dee1 aufgerufen. Darin befindet sich die Darstellung der Autor:in, die nun auch anderswo in statamic verwendet werden kann.

<p>Von <address class="inline" rel="author">noparse_b4d2005370371723e209ea4b9702c2e2</address></p>  

Takeaway

Dies war nur eine Einführung in die von Statamic verwendeten Frontend Konzepte. Antlers ist eine einfache aber mächtige Sprache um Daten auszugeben und zu manipulieren. Antlers hat aber auch seine Einschränkungen. Müssen Daten in der View verarbeitet werden, ist dies müham. Bis Statamic 3.4 war es beispielsweise gar nicht möglich Variablen in Antlers zu setzen. Heute geht dies, aber es ist nicht gerade elegant oder intuitiv.

Modifiers springen in die Lücke, wenn es darum geht, Daten für die Darstellung zu formatieren. Zum Beispiel dann, wenn ein Datum formatiert werden soll. Mit Modifiers bietet Statamic Bausteine an, die kombiniert ein mächtiges Tool ergeben, um Daten die Form zu geben, die wir für die Ausgabe brauchen.

Interaktionen mit Statamic finden in Antlers über Tags statt. Diese ermöglichen es, Daten aus Statamic zu holen, zu filtern und zu manipulieren. Die Tags bieten ein Interface zu den verwalteten Daten und machen den Zugriff darauf zum Kinderspiel.