Kirby

Kirby ist ein sog. Flat-File-Content-Management-System, das vom deutschen Entwickler Bastian Allgeier und seinem Team entwickelt und vertrieben wird. Kirby ist in PHP programmiert, der Quelltext kann auf Github eingesehen werden. Vor der Veröffentlichung eines mit Kirby erstellten Webprojektes muss eine Lizenz erworben werden (aktuell € 99 netto, Stand April 2019). ACHTUNG: Studenten erhalten auf Anfrage kostenlose Lizenzen!

Kernmerkmale

• Als Flat-File-CMS verzichtet Kirby auf eine Datenbank zur Speicherung von Inhalten und legt Daten stattdessen strukturiert in Dateien auf der Serverfestplatte ab.
• Es entfällt daher die Konfiguration einer Datenbankverbindung, was die Installation außerordentlich einfach macht (s.u.). Gleichzeitig lässt sich eine Kirby-Installation so auch hervorragend backupen.
• Die Seitenstruktur wird durch Ordner vorgegeben, in denen Text- und Mediendateien abgelegt werden.
• Inhalte werden werden in KirbyText, einer Erweiterung der einfachen Auszeichnungssprache Markdown, verfasst. Damit können grundlegende Formatierungen und Verknüpfungen erzeugt sowie Medien eingebunden werden.
• Zur Konfiguration nutzt Kirby das verbreitete, textbasierte YAML-Format, das mit jedem einfachen Texteditor bearbeitet werden.
• Zur Ausgabe einer Website verwendet Kirby direkt PHP und HTML und verzichtet auf andere Template-Engines.
• Der Funktionsumfang von Kirby kann mit einer Vielzahl von Plugins erweitert werden (siehe Plugin Repository). Das wohl populärste Plugin ist das vorinstallierte, aber optionale Kirby Panel, über das eine browserbasierte Administrationsoberfläche zur Verfügung gestellt wird. (Im Grunde ist Kirby auch allein über das Dateisystem nutzbar, in dem Text- bzw. KirbyText-Dateien in die richtigen Verzeichnisse gelegt werden).
• Ähnlich wie Wordpress unterstützt Kirby die Verwendung von "Themes", also vorgefertigter Designs. Derzeit stehen 88 teils kostenlose, teils kostenpflichtige Themes zur Verfügung (Stand April 2019). Themes können natürlich auch selbst entwickelt werden.

Starterkit-Installation

Per SSH

Stelle eine SSH-Verbindung zu deinem Hetzner-Server her und wechsle ins Verzeichnis, in dem Kirby installiert werden soll. Du solltest mit ausreichend Vorlauf z.B. den Ordner kirby und die Subdomain kirby.deinedomain.de dafür angelegt haben.

jkphla@www127:~$ cd public_html/kirby/

Lade Kirby direkt über die Kommandozeile herunter. Da eine Umleitung beteiligt ist, solltest du manuell einen Zieldateinamen angeben, da wget das Kirby-Archiv sonst als index.html abspeichert. Das Kirby-Starterkit kommt in einem ZIP-Archiv und ist gute 9 MB groß:

​x
wget -O kirby.zip https://download.getkirby.com
​
...
​
kirby.zip                [      <=>              ]  10.81M  9.25MB/s    in 1.2s
​
2019-04-24 19:58:57 (9.25 MB/s) - ‘kirby.zip’ saved [11339847]

Wenn du dir nun den Inhalt des aktuellen Verzeichnisses zeigen lässt, sollte das Kirby-Archiv zu finden sein:

xxxxxxxxxx
ls -l
total 11076
-rw-r--r-- 1 jkphla jkphla 11339847 Apr 24 19:58 kirby.zip

Zunächst extrahieren wir das Kirby-Archiv:

xxxxxxxxxx
unzip kirby.zip

Die Kirby-Installation wird dabei zunächst in das Verzeichnis starterkit-master entpackt, was für unsere Zwecke eher störend ist. Wir räumen im Anschluss also sofort auf, verschieben die Kirby-Dateien ein Verzeichnis nach oben, löschen das eigentliche Kirby-ZIP sowie das dann nicht mehr notwendige starterkit-master-Verzeichnis:

xxxxxxxxxx
mv starterkit-master/* starterkit-master/.* .
mv: cannot move 'starterkit-master/.' to './.': Device or resource busy
mv: cannot move 'starterkit-master/..' to './..': Device or resource busy
rm kirby.zip
rmdir starterkit-master

• mv steht für "move" und bewegt alle Dateien, die auf die Muster starterkit-master/* und starterkit-master/.* zutreffen ("globbing"), in das Zielverzeichnis .. Dabei ist . ein Alias für das aktuelle Verzeichnis, in dem du dich derzeit befindest.
• Unter Linux gelten Dateien, deren Namen mit einem . beginnen, standardmäßig als "versteckt" und werden von normalen Befehlen zunächst nicht erfasst. Da Kirby wichtige Dateien enthält, deren Namen mit einem . beginnen, und wir auch diese verschieben müssen, müssen wir solche versteckten Dateien ausdrücklich adressieren (starterkit-master/.*).
• Die zwei mv: cannot move ...-Warnungen kannst du in dieser Situation ignorieren.
• rm steht für "remove" und löscht die Datei kirby.zip
• rmdir steht für "remove directory" und löscht das (nun leere) Verzeichnis starterkit-master.

Gratuliere — du hast soeben erfolgreich die Installation von Kirby abgeschlossen! Ganz schön einfach, oder? Öffne nun deinen Browser und rufe deine Domain auf. Du solltest eine Kirby-Beispielseite sehen:

Per FTP

Solltest du Kirby per FTP installieren wollen, so musst du zunächst das Kirby-Archiv manuell von https://getkirby.com/try herunterladen, auf deinem lokalen Rechner entpacken (mit einem geeigneten Archiv-Programm) und schließlich den Inhalt des starterkit-master-Verzeichnisses per FTP in das Kirby-Verzeichnis deines Hetzner-Accounts hochladen. Das ist ebenfalls nicht schwierig, nimmt aber möglicherweise mehr Zeit in Anspruch als die SSH-Strategie.

Grundkonzepte

Unter der Haube

Ein Blick ins Kirby-Verzeichnis offenbart die folgende Grundstruktur:

xxxxxxxxxx
ls -l
total 32
drwxr-xr-x  3 jkphla jkphla 4096 Apr 23 16:13 assets
-rw-r--r--  1 jkphla jkphla  742 Apr 23 16:13 composer.json
drwxr-xr-x  8 jkphla jkphla 4096 Apr 23 16:13 content
-rw-r--r--  1 jkphla jkphla   78 Apr 23 16:13 index.php
drwxr-xr-x  9 jkphla jkphla 4096 Apr 23 16:13 kirby
drwxr-xr-x  2 jkphla jkphla 4096 Apr 23 16:13 media
-rw-r--r--  1 jkphla jkphla 1990 Apr 23 16:13 README.md
drwxr-xr-x 11 jkphla jkphla 4096 Apr 23 16:13 site

• Das Verzeichnis assets ist z.B. für CSS- oder JavaScript-Dateien und wird vom Starterkit genutzt. Es muss kein Verzeichnis mit diesem Namen existieren, ist aber eine Konvention bei Kirby-Nutzern.
• Die Datei composer.json wird benötigt, wenn Kirby über Composer installiert wird, ist für dich in dieser Installation jedoch nicht relevant.
• Die Datei index.php ist die zentrale PHP-Datei, die für das Frontend-Rendering von Kirby zuständig ist. Sie wird bei jedem Aufruf über den Browser bemüht und nutzt den URL zur Identifikation der Inhalte, die ausgeliefert werden sollen ("Routing").
• Das Verzeichnis kirby enthält die eigentliche Kirby-Programmierung. Du solltest in diesem Verzeichnis nichts ändern.
• Im Verzeichnis media liegen öffentlich zugängliche Mediendateien, die von Kirby und seinen Komponenten genutzt und verwaltet werden. Hier solltest du keine manuellen Änderungen vornehmen.
• Die Datei README.md enthält einige Informationen zur Installation und Nutzung von Kirby.
• Im Verzeichnis site liegen alle Programmierungen, die deine Kirby-Installation individuell machen, darunter die zentrale Konfiguration, HTML-Templates für das Frontend-Rendering, Plugins und sog. Blueprints für die individuelle Gestaltung von Eingabemasken in der Administrationsoberfläche.

Inhalte

Die Verzeichnisse unterhalb von content bilden das strukturelle Rückgrat deiner Website und beherbergen alle Inhalte (zur Vereinfachung wurden die Verzeichnisinhalte ab 2_trees weitgehend ausgelassen):

xxxxxxxxxx
content/
├── 1_photography
│   ├── 1_animals
│   │   ├── abba.jpg
│   │   ├── abba.jpg.txt
│   │   ├── album.txt
│   │   ├── bird-reynolds.jpg
│   │   ├── bird-reynolds.jpg.txt
│   │   ├── dumbo.jpg
│   │   ├── dumbo.jpg.txt
│   │   ├── free-wheely.jpg
│   │   ├── free-wheely.jpg.txt
│   │   ├── peter-fox.jpg
│   │   ├── peter-fox.jpg.txt
│   │   ├── steve-turtle.jpg
│   │   └── steve-turtle.jpg.txt
│   ├── 2_trees
│   ├── 3_sky
│   ├── 4_ocean
│   ├── 5_desert
│   ├── 6_mountains
│   ├── 7_waterfall
│   ├── 8_plants
│   ├── 9_landscape
│   └── photography.txt
├── 2_notes
├── 3_about
├── error
├── home
├── sandbox
└── site.txt

• Jedes Verzeichnis entspricht einer einzelnen, im Frontend aufrufbaren Seite. Die Verzeichnisnamen bilden die Basis für die URLs der Website.
• Die vorangestellten Ziffern in den Verzeichnisnamen dienen der Sortierung und werden von Kirby automatisch "herausgerechnet".
• In jedem Verzeichnis kann eine gleichnamige Textdatei liegen (ohne vorangestellte Sortierziffer, z.B. photography.txt). Die Dateien nutzen das YAML-Format und enthalten sowohl die markdown-formatierten Textinhalte der Seite, als auch Metadaten und Konfigurationsparameter, etwa den Seitentitel. Es ist von "Feldern" die Rede. Ein gutes Beispiel findet sich im Verzeichnis 3_about.
• home ist ein reservierter Name und entspricht der Startseite, error einer allgemeinen Fehlerseite.
• Die Konfigurationsdatei site.txt bezieht sich auf die komplette Website.

Frontend-Rendering

Die für das Frontend-Rendering zuständigen Templates befinden sich im Verzeichnis site/templates:

xxxxxxxxxx
site/templates/
├── about.php
├── album.php
├── default.php
├── home.php
├── note.php
├── notes.php
└── photography.php

• Jede Inhaltsseite kann ein individuelles Template nutzen. Die Verbindung wird über die Verzeichnisnamen bzw. über den Template-Namen hergestellt: Gibt es ein Template site/templates/about.php, so wird dieses zum Rendern der Seite content/about (bzw. content/3_about) herangezogen.
• Seiten, zu denen es keine Template-Entsprechung gibt, nutzen automatisch das Template default.php.

Templates sind mit PHP angereicherte HTML-Dateien. Die PHP-Teile sprechen die umfangreiche Kirby-API an und bestücken das HTML dynamisch mit den Werten der Inhalte:

xxxxxxxxxx
<?php snippet('header') ?>
​
<article>
  <header>
    <h1><?= $page->title() ?></h1>
  </header>
  <div class="text">
    <?= $page->text()->kirbytext() ?>
  </div>
</article>
​
<?php snippet('footer') ?>

• Kirby nutzt neben den Templates auch sog. Snippets (in anderen Systemen / Sprachen oft auch "Partials"). Dabei handelt es sich um wiederverwendbare "Unter-Templates", die mehrfach verwendet werden können, dafür aber nicht mehrfach verfasst werden sollen (DRY-Prinzip). Snippets werden im Verzeichnis site/snippets gespeichert und können aus Templates oder anderen Snippets heraus über die API-funktion snippet() eingebunden werden. Im obigen Beispiel werden so etwa der Seitenkopf- und -fußbereich integriert.
• Die in Templates stets verfügbare Variable $page entspricht der aktuellen Seite und ihrer Felder. Jedes gültige Feld kann automatisch über eine gleichnamige Methode des $page-Objekts abgerufen werden (z.B. title-Feld → $page->title()-Methode).
• Ein PHP-Block im Format <?= ... ?> ist eine Kurzform für <?php echo ...; ?>.

Das Panel

Das optionale Kirby-Panel bietet eine browserbasierte Administrationsoberfläche für Inhalte. Es kann unter dem Pfad /panel aufgerufen werden (z.B. https://kirby.meinedomain.de/panel). Beim ersten Aufruf ist das Panel noch nicht installiert:

Zum Schutz vor unerlaubtem Zugriff muss die Panel-Installation zunächst freigeschalten werden. Öffne dazu die Konfigurationsdatei site/config/config.php und ergänze die Option panel.install im Konfigurations-Array. Deine Konfiguration sollte nun so aussehen:

xxxxxxxxxx
<?php
​
return [
    'debug' => true,
    'panel.install' => true,
];

Sodann lässt sich das Panel erfolgreich aufrufen und installieren:

Lege dir persönliche Daten fest, mit denen du künftig den Administrationsbereich nutzen wirst. Ab jetzt kannst du das Panel zur Bearbeitung deiner Inhalte nutzen:

Template-Anpassung

Einfache Anpassungen an Templates sind recht einfach zu bewerkstelligen. Als beispielhafte Fingerübung wollen wir eine Autorenangabe in das Template für Notizen integrieren.

Wechsle im Panel in die Bearbeitungsmaske einer Notiz. Du siehst rechterhand, dass ein Auswahlfeld für den Autor zur Verfügung steht. Im Frontend wird der Autor aber nirgends genutzt. Wähle hier zunächst einen Autor:

Notizen werden über das Template site/templates/note.php gerendert. Öffne dieses Template in deinem PHP-Editor (z.B. PhpStorm) und erfasse zunächst den Aufbau:

xxxxxxxxxx
<?php snippet('header') ?>
​
<main>
  <article class="note">
    <header class="note-header intro">
      <h1><?= $page->title() ?></h1>
      <time class="note-date"><?= $page->date()->toDate('d F Y') ?></time>
      <?php if ($page->tags()->isNotEmpty()) : ?>
      <p class="note-tags tags"><?= $page->tags() ?></p>
      <?php endif ?>
    </header>
​
    <div class="note-text text">
      <?= $page->text()->kt() ?>
    </div>
  </article>
</main>
​
<?php snippet('footer') ?>
​

Integriere dann an geeigneter Stelle Code wie den folgenden, um eine Autorenangabe anzuzeigen (vielleicht direkt nach der Überschrift?):

xxxxxxxxxx
<?php
​
$user = $page->author()->toUser();
if ($user):
​
?>
<p class="author">by <?= $user->name(); ?></p>
<?php
​
endif;
​
?>

• Der Aufruf $page->author() liefert den Wert des author-Felds. Der daran anschließende Aufruf ->toUser() spricht die Kirby-API an und liefert das dahinterliegende Benutzerobjekt, dessen ->name()--Methode sodann verwendet werden kann.
• Sobald im Panel ein Autor ausgewählt und gespeichert wurde, sollte dieser im Frontend zu finden sein. Nebenbei: Du kannst diese Ergänzung des Autors natürlich auch nachvollziehen, indem du unter content/02_notes in die Textdatei der entsprechenden Notiz blickst.

Anlegen einer neuen Seite

Das Anlegen einer neuen Seite erledigst du am besten ebenfalls über das Panel. Wechsle zur Notizübersicht und nutze die Schaltfläche "Hinzufügen".

• Gib einen Titel für die neue Seite ein.
• Kirby konstruiert aus dem Titel automatisch einen Vorschlag für den URL der neuen Seite. Du kannst diesen bei Bedarf manuell anpassen, z.B. wenn seltsame Sonderzeichen enthalten sind.
• Als Vorlage hast du in diesem Fall nur "Note" zur Auswahl — dies ist für alle Seiten unterhalb von /notes so vorkonfiguriert.
• Neue Seiten werden zunächst als Entwurf gespeichert, der anschließend durch eine Statusänderung veröffentlicht werden kann:

Blueprints: Vorlagen fürs Panel

Die Auswahl und Anordnung der Felder im Panel werden über sog. Blueprints gesteuert. Blueprints werden als YAML-Dateien verfasst und im Verzeichnis site/blueprints/pages gespeichert. Wirf einen Blick in den Blueprint für Notizen (note.yml) und studiere die Angaben.

Aufgabe

1. Ergänze an geeigneter Stelle im Blueprint ein zusätzliches Feld für die Angabe einer Kurzzusammenfassung für die Notiz (Tipp: der type dieses Felds könnte z.B. text oder textarea sein). Prüfe, ob deine Änderungen im Panel sichtbar werden.
2. Ergänze im Notiz-Template ein geeignetes Rendering für die Kurzzusammenfassung. Trage bei einer Notiz eine Zusammenfassung ein und prüfe, ob die Ausgabe im Frontend erscheint.