Themes erstellen

Alles, was du in FolioPress schreibst — Seiten, Beiträge, Tags — lebt getrennt davon, wie es dargestellt wird. Diese Darstellungsschicht ist ein Theme, und dieser Leitfaden nimmt eines auseinander: den Ordner, die Templates, die Einstellungsdatei und genau die Daten, die jedes Template bekommt. Wer mit HTML und CSS vertraut ist, hat alles, was nötig ist.

Ein Theme ist ein Ordner

Wechsle das Theme, und dieselben Seiten, Beiträge und das Menü werden neu gezeichnet — am Inhalt ändert sich nichts, nur an seiner Kleidung. Ein Theme ist ein Ordner mit drei Dingen: einer Einstellungsdatei, Templates und statischen Dateien.

Vier Templates sind Pflicht — base.html, home.html, page.html und post.html —, ein Theme ohne sie lädt nicht. Alles andere ist optional: ein Tag-Archiv, eine Suchseite, eigene Fehlerseiten, ein eigenes Layout für eine bestimmte Seite und ein Ordner locales/ für die Texte des Themes selbst. Themes lassen sich direkt in der Verwaltung unter Themes bearbeiten, als Zip exportieren und in eine andere Website importieren.

Von einer URL zu einer Seite

Es hilft zu sehen, was FolioPress mit einer Anfrage tut, bevor dein Template überhaupt läuft — denn es erklärt, warum Templates so kurz sind.

Zwei Dinge fallen auf. Die Sprache wird aus dem URL-Präfix gelesen, sodass /pt-pt/sobre und /about dieselbe Seite in zwei Sprachen sind, und der Kontext, den dein Template bekommt, ist bereits in der richtigen — jeder Titel, Slug, Menüeintrag und Inhalt. Und das Template wird für dich gewählt: Für eine Seite, deren Slug in der Hauptsprache about lautet, sucht FolioPress zuerst page-about.html und fällt auf page.html zurück. Nichts muss verdrahtet werden.

Ein Gerüst, viele Seiten

Templates sind Jinja2 — HTML mit zwei zusätzlichen Klammerarten. {{ page.title }} gibt einen Wert aus. {% if page.poster_image_url %} … {% endif %} ist eine Anweisung: Schleifen, Bedingungen und Vererbung.

base.html enthält alles, was jede Seite teilt — den <head>, die Navigation, den Sprachumschalter, die Fußzeile, die Skripte — mit einer einzigen Lücke in der Mitte. Jedes andere Template beginnt gleich und füllt diese Lücke:

{% extends "base.html" %}

{% block content %}
  <h1>{{ page.title }}</h1>
  {{ page.content | safe }}
{% endblock %}

Alles, was sich über Templates hinweg wiederholt — eine Beitragskarte, eine Seitennavigation — gehört nach partials/ und wird mit {% include "partials/post-card.html" %} eingebunden.

theme.yml: das Einstellungsfeld

Hier beschreibt sich ein Theme selbst und legt ein paar Verhaltensweisen fest, ohne ein Template anzufassen. So nutzen es die mitgelieferten Themes:

title: "Ink"
description: "Ein klares, minimalistisches Theme"
version: "1.0.0"
author: "FolioPress"

meta:
  supports_dark_mode: true
  responsive: true
  categories: [minimal, portfolio]

settings:                    # frei; in Templates als theme_settings verfügbar
  primary_color: "#2563eb"

home:
  posts: 10                  # wie viele Beiträge die Startseite bekommt
  order_by: "-published_at"  # neueste zuerst
  has_pagination: false      # ein Abschnitt, oder echte Seitenlinks?
  image_ratios:
    poster: "16:9"           # was der Bildzuschnitt der Verwaltung hier anbietet
    gallery: "free"

page:  { posts: 10, order_by: "-published_at", has_pagination: false }
post:  { posts: 3,  order_by: "-published_at" }   # verwandte Beiträge unter einem Beitrag
tag:   { posts: 12, order_by: "-published_at", has_pagination: true }

page-about:                  # Überschreibung für eine Seite, per Slug in der Hauptsprache
  image_ratios: { poster: "1:1" }
post-tutorials:              # Überschreibung für Beiträge, deren erster Tag diesen Slug hat
  image_ratios: { poster: "4:3" }

Was jedes Template sehen kann

Ein Template holt nie etwas selbst. Es bekommt ein Bündel gebrauchsfertiger Werte — FolioPress nennt es den Kontext — und gibt aus, was es braucht. Ein Teil des Bündels ist auf jeder Seite gleich; der Rest hängt davon ab, welches Template gerendert wird.

Allen Templates gemeinsam

Das page-Objekt

Dieselbe Form, ob Seite, Beitrag oder Eintrag in einer beliebigen Beitragsliste:

Beitragslisten

Jede Beitragsliste kommt mit einer Paginierung gleicher Form: has_pagination, current_page, total_pages, has_previous, has_next, previous_page, next_page und pagination_urls mit first, previous, next und last — None, wo es nicht weitergeht. Ist `has_pagination` in der `theme.yml` aus, wird die Liste einfach bei `posts` abgeschnitten und die Flags bleiben falsch.

Sprachen und der Umschalter

Zwei der Sprachfelder werden für dich berechnet. short_code ist nur der Sprachcode — EN —, es sei denn, die Website hat auch eine andere Variante derselben Sprache aktiviert; dann behält er seine Region: EN-US und EN-GB. menu_label folgt derselben Regel mit Namen: English, oder English (US) und English (UK). Das ist genau die Regel des Sprachumschalters der Verwaltung, sodass Website und Verwaltung sich nie über eine Beschriftung uneinig sind. Ein vollständiger Umschalter ist deshalb kurz:

{% if languages | length > 1 %}
<button type="button" aria-label="{{ t('Change language') }}">
  {{ current_language.short_code }}
</button>
<ul>
  {% for lang in languages.values() | sort(attribute='menu_label') %}
  <li>
    {% if lang.code == current_language.code %}
      <span aria-current="true">{{ lang.menu_label }}</span>
    {% else %}
      <a href="{{ language_switch_urls[lang.code] }}" hreflang="{{ lang.code }}">{{ lang.menu_label }}</a>
    {% endif %}
  </li>
  {% endfor %}
</ul>
{% endif %}

language_switch_urls zeigt bereits auf dieselbe Seite in jeder Sprache — auf den übersetzten Slug oder, falls diese Übersetzung noch fehlt, auf die Startseite —, sodass ein Umschalter nie selbst eine URL baut.

Die Texte des Themes selbst

Inhalte übersetzt der Autor in der Verwaltung. Die eigenen Texte eines Themes — „Weiterlesen“, „Suche“, „Alle Rechte vorbehalten“ — übersetzt das Theme, in templates/locales/<sprache>.json:

{
  "Read more": "Weiterlesen",
  "Search": "Suche",
  "Change language": "Sprache wechseln"
}

Umschließe den Satz mit {{ t('Read more') }}, und er erscheint in der Sprache des Besuchers. Fehlt ein Satz in der Datei dieser Sprache, fällt er auf die Datei der Hauptsprache zurück, dann auf den Satz selbst — ein halb übersetztes Theme funktioniert also weiter, nur auf Englisch, wo noch keine Übersetzung geschrieben wurde. Die Dateien reisen beim Export mit dem Theme.

Eine Seite mit eigenem Layout

Eine Landingpage, ein Kontaktformular, ein Portfolio-Raster — manchmal verdient eine Seite ein Layout, das keine andere braucht. Lege ein Template namens page-<slug>.html an, wobei <slug> der Slug dieser Seite in der Hauptsprache ist, und FolioPress nutzt es für diese Seite in jeder Sprache. Lösche die Datei, und die Seite kehrt still zu page.html zurück.

{# templates/page-about.html #}
{% extends "base.html" %}
{% block content %}
<section class="about">
  <img src="{{ page.poster_image_url }}" alt="">
  <h1>{{ page.title }}</h1>
  {{ page.content | safe }}
</section>
{% endblock %}

Die Seite, die ein Administrator als Kontaktformular-Seite festlegt, bekommt etwas extra: is_contact_page ist wahr, contact_form_action ist das Ziel des Formulars, und contact_guard_token / contact_honeypot_field sind zwei versteckte Felder, die Bots fernhalten. Nach dem Absenden sagt contact_status, ob ein Dank oder ein Fehler anzuzeigen ist.

Beginne mit einem Theme, das funktioniert

Der schnellste Weg zu einem Theme ist, eines der mitgelieferten zu öffnen — jedes hat eine Live-Demo — und es neben dieser Seite zu lesen. Dupliziere es in der Verwaltung, ändere das CSS, dann die Templates, und du hast etwas Eigenes, ohne je mit einer leeren Datei begonnen zu haben.