In diesem Tutorial bauen wir mit Statamic in 20 Minuten einen simplen Blog. Wir modellieren einen Blogbeitrag, bauen eine Übersichtsseite mit allen Beiträgen und gestalten das Ganze mit Tailwind.

Voraussetzungen: Für dieses Tutorial werden folgende Programme und Bibliotheken verwendet: PHP 8.1, Node, Yarn/NPM und Statamic CLI. Das Tutorial wurde auf einem Debian basierten Linux getestet, sollte aber auch auf anderen OS funktionieren.

Lizenz

Wir nutzen eine Statamic Solo Developer Lizenz. Diese Lizenz ist gratis und bietet ausreichend Features für viele kleinere Projekte, so auch unseren Blog. Multi-User, Git-Integration und Mehrsprachigkeit sind leider nicht drin. Dazu später mehr.

Projekt starten (2min)

Beginnen wir mit einem neuen Statamic Projekt. Dieses Tutorial geht davon aus, dass du die Statamic CLI link TBD bereits installiert hast:

# Hier wird auch der Admin User mit Password erstellt. Diesen bitte aufschreiben
statamic new statamic-ch-blog
cd statamic-ch-blog
# Git initialisieren
git init
git add .
git commit -m "init project"
# Frontend Bibliotheken (tailwind-css) installieren
yarn 

Blog Collection und Blueprint (5min)

Statamic organisiert Inhalte in Collections. Jede Collection ist eine Sammlung von Beiträgen, die ein gemeinsames Schema - genannt Blueprint - teilen. Die Blueprints sind die Definition des Inhaltes eines Beitrages. Ein Beitrag hat beispielsweise einen Titel, einen Abriss, ein Beitragsbild, ein Autor und Tags. All dies wird in der Blueprint festgelegt.

Statamic kommt nur mit einer vorkonfigurierten Collection "Pages" daher. Wir erstellen also als erstes eine weitere Collection für unsere Blogbeiträge. Am einfachsten geht dies im Controllpanel von Statamic. Starten wir Statamic und melden uns an:

# startet einen simplen Entwicklungsserver
php artisan serve

Nun können wir uns auf localhost:8000/cp anmelden. Den entsprechenden User haben wir bereits angelegt. Wir navigieren zu "Collections" und klicken auf "Create Collection" um unsere Blog-Collection zu erstellen. Wir nennen unsere Collection "Posts" und klicken auf "Save". Wir konfigurieren die Collection und navigieren dazu auf "Configure Collection". Aktuell interessiert uns nur das Routing. Wir wollen definieren, unter welchem URL-Pfad unsere Posts auffindbar sind. In unserem Fall setzen wir die Route auf "/blog/{slug}":

Als nächstes erstellen wir die Blueprint für unsere Posts. Unsere Posts sollen einen Abrisstext, einen Autor, ein Vorschaubild und einen Inhalt haben. Über "Configure Blueprint" können wir den Inhalt unseres Blogs definieren. Aktuell sind hier "Titel", "Content", "Autor" und "Template" definiert.

Löschen wir als erstes "Content" und "Template" und fügen ein neues Feld mit "Create field" ein. Es erscheint eine Auswahlmaske, wo wir definieren können, welcher Type unser Feld haben soll:

Wir erstellen als erstes unser Vorschaubild und wählen als Fieldtype "Assets". Wir erhalten eine Maske zur Eingabe des Namens, des Handlers und zur allgemeinen Konfiguration des Feldes. Wir beschriften unser Feld mit Vorschaubild und vergeben den englischen handler "feature_image". Es ist egal wie der Handler benannt wird. Dieser Name wird als Referenz im Code verwendet und Englisch ist hier standard:

Wir wechseln auf den Reiter "Validation" und stellen das Feld auf "required". Dadurch erzwingen wir für jeden Post ein Beitragsbild.

Neben dem Vorschaubild braucht unser Post noch einen Abriss und einen Content. Wir fügen entsprechend weitere Felder hinzu. Für den Abriss wählen wir den Fieldtype "Textarea" und nennen den handler "lead". Wir legen auch ein "Character Limit" von 120 fest, so dass die Textlänge begrenzt wird.

Für den Content wählen wir den Fieldtype "Bard". Wir nennen den handler "content" und geben ihm einen netten Titel und gute Instructions.

Bard ist der mächtigste Fieldtype in Statamic und ermöglicht es, Felder zu verschachteln. Der Fieldtype bietet einen Wysiwyg Editor, der Formatierungen des Textes zulässt. So können wir unseren Beitrag ohne Code gestalten:

Zum Schluss sortieren wir unsere Fields und speichern den Blueprint. Zuerst der Titel, dann Autor, Vorschaubild, Abriss und zuunterst der Content.

Ein Blick in unser Git zeigt, dass Statamic nun einige Dateien erstellt hat. Am besten wir adden und commiten diese Dateien, so dass nachvollziehbar bleibt, was gemacht wurde:

git add content/ resources/ && git commit -m "Add posts collection and blueprint"

Erster Post erstellen (2min)

Wir haben nun unsere Collection und die dazugehörige Blueprint abgelegt und können unseren ersten Post schreiben. Wir navigieren zu "Collections" -> "Posts" und klicken "Create Entry". Nun sehen wir das von uns definierte Formular mit seinen Eingabefelder. Wir erfassen Titel und Bild, geben einen Dummy Content ein und speichern:

Design (2min)

Die Installation von Statamic kommt mit minimalem Design daher. Als erstes wollen wir dieses anpassen. Dazu öffnen wir mit einem Editor die Datei /resources/views/layout.antlers.html und fügen einige Tailwind Klassen hinzu. Tailwind ist ein CSS-Framework, das mit Utility Classes arbeitet:

<!doctype html>
<html lang="{{ site:short_locale }}">
    <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>{{ title ?? site:name }}</title>
        <link rel="stylesheet" href="{{ mix src='css/tailwind.css' }}">
    </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">
            {{ template_content }}
        </div>
        <script src="{{ mix src='/js/site.js' }}"></script>
    </body>
</html>

Post darstellen (5min)

Wir haben einen ersten Blog veröffentlicht und möchten diesen nun gerne auf unserer Seite darstellen. Dazu fehlt uns noch die entsprechende View. Als erstes scaffolden wir unsere Views. Dadurch werden zwei leere Template-Files erstellt: für einen einzelnen Blog und für die Liste der Blogbeiträge:

Einzelner Post

Ein einzelner Post wird mit der View ressources/views/posts/show.antlers.html dargestellt. Wir starten mit einem sehr rudimentären Markup:

<article>
    <h1>{{title}}</h1>
    <img src="{{feature_image}}">
    <p>{{lead}}</p>
    <div>{{content}}</div>
</article>

Das Resultat können wir über den Button "Visit URL" betrachten:

Es sieht noch nicht schön aus, aber es wird deutlich, dass das Handling von Informationen aus Statamic ins Frontend sehr simpel ist. Man schreibt HTML-Markup und wenn man Informationen vom CMS haben möchte, dann kann man diese mit geschweiften Klammern abrufen. It's simpel like that.

Stylen mit Tailwind

Das Ganze sieht noch sehr Basic aus und es fehlen auch noch einige Angaben. Um ein besseres visuelles Resultat zu erzeugen, fügen wir Tailwind Klassen in unser Template ein. Wir ergänzen auch die Autor:in des Artikels und das Veröffentlichungsdatum.

<article>
    <h1 class="font-black text-4xl mb-6">{{ title }}</h1>
    <div class="mb-2 text-sm">
        Von <address class="inline" rel="author">{{ author:name }}</address>
        veröffentlicht am
        <time pubdate datetime="{{ updated_at format="Y-m-d" }}">{{ updated_at format="d.M Y" }}</time>
    </div>
    <img src="{{ feature_image }}" alt="{{ feature_image:alt }}" class="responsive min-w-full">
    <p class="italic my-4 text-xl">{{ lead }}</p>
    <div>{{ content }}</div>
</article>

Liste der Posts (5min)

Bis jetzt können wir einen einzelnen Post anzeigen. Wir möchten aber gerne eine Übersichtsseite mit allen Posts. Dazu müssen wir die View resources/views/posts/index.antlers.html bearbeiten.

In Statamic sind Collections nicht direkt über eine Url ansprechbar. Wenn die Seite http://localhost:8000/blog geöffnet wird, dann erscheinen nicht alle Blogbeiträge, sondern eine 404 Fehlermeldung. Die Liste der Posts wird in der View zusammengestellt.

<h1 class=" text-5xl font-black mb-8">Blog</h1>
<div class="grid grid-cols-2 gap-8">
    {{ collection:posts }}
    <article>
        <img src="{{ feature_image }}" alt="{{ feature_image:alt }}" class="responsive min-w-full mb-4">
        <h2 class="font-black text-4xl mb-2">{{ title }}</h2>
        <p>{{ lead }}</p>
        <a href="{{ url }}" class="bg-blue-800 hover:bg-blue-700 text-white font-bold p-1.5 rounded">mehr lesen</a>
    </article>
    {{ /collection:posts }}
</div>

Das {{ collection:posts }}-Tag lädt alle Posts von Statamic und iteriert über diese. Innerhalb dieses Tags können wir wie gewohnt mittels geschweiften Klammern auf die Inhalte zugreifen.

Das Template wird jedoch noch nirgends verwendet und entsprechend ist unsere Übersichtsseite noch nicht aufrufbar. Öffnen wir unsere Home-Seite und legen fest, dass das Template posts/index verwendet werden soll:

Dadurch wird anstatt des Inhaltes unser Template geladen. Laden wir unsere Seite neu, dann sehen wir eine Liste der Posts in Statamic.

Optional können wir noch einen Mountpoint für unsere Posts festlegen. Dies verbessert das Handling im Controllpanel. Wir Öffnen die Konfiguration der Collection Posts und definieren unsere Startseite als Mountpoint für unsere Collection:

Nun können wir direkt von der Home-Seite neue Posts erstellen: