Kirby-Struktur verstehen: Templates, Snippets, Blueprints, Assets

Nachdem wir im vorherigen Abschnitt einen ersten Blick in das Backend von Kirby, das sogenannte Panel, geworfen haben, wollen wir uns intensiver mit der Struktur einer Kirby-Webseite befassen.

Alles schön geordnet

Schauen wir uns erst einmal die Ordnerstruktur einer Kirby-Seite an, so wie sie auf dem Webserver liegt. Das Kirby Starter Kit enthält die wichtigsten Bestandteile einer Webseite nebst einigen Inhalten. Die Namen der Ordner sind überwiegend selbsterklärend, was die Einarbeitung erleichtert.

Um den Rahmen dieses Artikels nicht zu sprengen, werden wir nicht auf die Themen „selbst erstellte Funktionen“ (controllers) oder „Plugins“ (plugins) eingehen. Auch die Mehrsprachenfunktion lassen wir außen vor.

In der Standardinstallation (Kirby Starter-Kit) sind verschiedenartige Inhalte (sogenannte Inhaltstypen), wie z.B. Blogbeiträge, statische Seiten oder Projects, bereits definiert. Dies geschieht in Kirby in den schon erwähnten Blueprints.

Inhaltsschablonen, die Blueprints

Eine Blueprint-Datei ist nichts weiter als eine Textdatei, die eine genaue Beschreibung eines bestimmten Inhaltstypen enthält. Das Blueprint erscheint später als Eingabemaske für Inhalte im Panel. Die Fields (Felder) definieren die Abschnitte, in die später Inhalte eingetragen werden und werden gleichzeitig verwendet, um in Templates oder in Snippets als Platzhalter notiert zu werden, damit die Feldinhalte auf der Webseite ausgespielt werden. Wir wollen uns das am Beispiel des Blueprints für die Blogbeiträge unserer Beispielinstallation anschauen. Diese Datei heißt blog.php und liegt im Ordner /site/blueprints/.

<code>

<?php if(!defined('KIRBY')) exit ?> //Eine Sicherheitsprüfung, die fassen wir nicht an.

title: Blog Article  // der Name des Inhaltstypen, so wie er im Kirby-Panel später erscheint.

pages: false // dieser Inhaltstyp erlaubt keine eigenständige Seite

files: true // dieser Inhaltstyp erlaubt Dateianhänge

fields: // ab hier werden die Felder des Inhaltstypen zusammengebaut.
   title:
      label: Title
     type: title
   date:
      label: Date
      type: date
      width: 1/2  // legt die Breite des Feldes auf dem Bildschirm fest (hier: halbe Breite)
      default: today // standardmäßig wird das heutige Datum voreingestellt
    author:
       label: Author
       type: user
       width: 1/2
   tags:
      label: Tags
      type: tags
   text:
      label: Text
      type: textarea
      required: true  // ein Pflichtfeld, Eingabe erforderlich.

</code>

Schauen wir uns die Bestandteile dieser Blueprint-Datei genauer an. Einige haben wir mit Kommentaren versehen, da sie praktisch selbsterklärend sind. Interessant ist der Abschnitt, der mit “fields” beginnt. Hier werden alle Felder definiert, die später mit Inhalten befüllt werden können. Jedes Feld hat mindestens ein “label”, damit man später im Backend erkennt, was dieses Feld beinhalten wird, und einen “type”, der festlegt, welche Art Inhalt es ist. Für unseren Inhaltstypen “Blog” brauchen wir zumindest mal das Feld “Title”. Darin steht später die Überschrift des Blogbeitrages. Der Typ “text” erlaubt nur eine Zeile Text. Als nächstes gibt es ein Datumsfeld (“date”) darin wird das Erscheinungsdatum eines Blogbeitrages gespeichert. Dieses Feld nimmt die halbe Spaltenbreite ein und ist standardmäßig mit dem aktuellen Datum vorbelegt. Kirby bietet Spaltenbreiten in den Rastern Fünftel, Viertel, Drittel oder Halb. Was für die meisten Anwendungen völlig ausreicht.

Im Feld “author” wird der User-Name des Autors eines Beitrages eingetragen. Das ist keine freies Textfeld, sondern erlaubt nur User, die Kirby bekannt sind. Im Feld “tags” können zu jedem Beitrag Stichworte eingegeben werden. Zum Schluss dann noch das Feld “text” für den eigentlichen Blogbeitrag. Der Typ “textarea” erlaubt es hier einen beliebig langen Text einzugeben und darin auf Bilder oder Links einzubauen. Dieses Feld ist außerdem als Pflichtfeld markiert.

Kirby bietet noch zahlreiche weitere Feldtypen (z.B. für Zahlen oder Bilder) und Optionen, wie  Validierungsfunktionen, Hilfetexte, Platzhalter oder Icons. Damit lassen sich auch aufwändige Inhaltstypen konfigurieren.

Wichtig bei einem Blueprint sind die Einrückungen, die nach dem YAML-Schema vorgenommen werden. Macht man hier einen Fehler, funktioniert die Eingabemaske nicht und bleibt leer, gibt eine Fehlermeldung aus oder unerwartete Ergebnisse, je nachdem, wo man die Einrückung falsch gesetzt hat. Schnelle Hilfe bietet der YAML-Validator.

Jetzt wollen wir aber erst einmal daran gehen, die verschiedenen Seiten mit Hilfe von Templates zu gestalten.

Templates - einmal schön machen bitte

Eine einfache Webseite besteht aus den Grundbestandteilen

<code>

<!DOCTYPE html>
<html lang="de">
   <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Titel</title>
   </head>
   <body>

      <main> // Hier wird der Seiteninhalt eingefügt
      </main>

   </body>
</html>

</code>

Im Beispiel ist das Grundgerüst einer modernen HTML5-Webseite aufgeführt. Zwischen <body> und </body> wird der Inhalt der Webseite ausgegeben. Bei einfachen statischen Webseiten müssen dort auf jeder Webseite auch wiederkehrende Elemente wie das Menü oder der Footer notiert werden. Ändert sich ein Menüpunkt, muss das in jeder zugehörigen HTML-Datei notiert werden. Content Management Systeme arbeiten an dieser Stelle mit Platzhaltern, die die in gesonderten Dateien (die bei Kirby “Snippets” genannt werden, dazu weiter unten) definiert werden und dann automatisch in die Seitentemplates übernommen werden. Anstatt als HTML werden die Seiten jetzt als PHP gespeichert, und aus einer statischen Seite wird eine dynamische Webseite. Die Vorteile liegen klar auf der Hand: Durch das baukastenartige System muss man Änderungen an wiederkehrenden Elementen nur einmal durchführen und sie werden dann automatisch übernommen. Zusätzlich zu dieser grundlegenden und sehr praktischen Funktion kann die Inhaltsausgabe auch manipuliert werden. Bleiben wir bei der Blogseite. Hier werden der Seitenheader mit dem Seitentitel und dem Menü und der Seitenfooter aus externen Dateien geholt, dazwischen werden Felder aus dem Blog- und dem Article-Blueprint aufgerufen. Dank PHP können wir festlegen, wie viele Anrisstexte auf einer Blog-Seite ausgegeben werden und was passiert, wenn dieses Limit überschritten wird. Wer kein PHP kann, stößt hier scheinbar schnell an seine Grenzen, aber genau dafür eignet sich die Standardinstallation mit den Beispielen besonders gut: Hat man das Grundprinzip verstanden, kann man die Elemente, die die gewünschte Funktion bereithalten, leicht kopieren und anpassen, wenn man z.B. eine andere Seite mit dieser Funktion ausrüsten möchte.

Noch einmal zum HTML-Grundgerüst. Egal ob man eine Seite aus einer eigenen einfachen HTML-Vorlage mit dem Bootstrap-Framework oder mit dem weniger komplexen Basscss Low-Level CSS Toolkit oder was auch immer zusammenbauen möchte, alles ist machbar. Das Grundgerüst wird leicht aufgebohrt und “dynamisiert”:

<code>

<!DOCTYPE html>
<html lang="<?= site()->language() ? site()->language()->code() : 'de' ?>">
   <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title><?= $site->title()->html() ?> | <?= $page->title()->html() ?></title>
   </head>
   <body>
      <header>
      </header>
      <main>
      </main>
   </body>
</html>

</code>

Man ahnt, was hier passiert: Kirby unterstützt mehrsprachige Webseiten und man kann an der Stelle der Definition der Seitensprache (“lang”) die jeweils gewählte Sprache (hier standardmäßig deutsch) ausgeben lassen. Das wird wichtig, wenn Elemente wie Buttons verwendet werden, für die für die jeweilige Sprache eine Übersetzung ausgespielt werden kann (z.B. “Senden” auf deutsch, “send” auf englisch). Auch den Seitentitel muss man nicht auf jeder Unterseite separat eintragen. Hier wird gleich eine suchmaschinenfreundliche Variante generiert: Der Titel der Webseite ($site) wird vorne angestellt, danach folgt ein | und danach der Titel der Unterseite ($page), auf der man sich gerade befindet. Fährt man mit der Maus im Browser über den Kartenreiter mit der Webseite, wird diese Titelkonstruktion angezeigt.

Schaut man in den Kirby-Templateordner und öffnet die Templates, sucht man das HTML-Grundgerüst aber vergeblich, zumindest als vollständigen Text in nur einer Datei. Tatsächlich wird jede Seite aus unterschiedlichen Dateien zusammengestellt. Dazu gleich mehr.

Zurück zur Blog-Seite. Die HTML-Struktur vereinfacht dargestellt sieht wie folgt aus (öffnet man die Quelltextansicht der Blog-Seite im Browser, ist die Struktur noch um einiges komplexer; Details wie Skripte oder CSS-Klassen und IDs wurden für die Übersichtlichkeit größtenteils weggelassen):

<code>

<!doctype html>
<html lang="en">
<head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width,initial-scale=1.0">
   <title>Kirby Starterkit | Blog</title>
   <meta name="description" content="This is Kirby's Starterkit.">
</head>

<body>
   <header>
     <div>
        <div>
           <a href="/kirby" rel="home">Kirby Starterkit</a>
        </div>
        <nav role="navigation">
           <ul>
              <li>
                 <a href="/kirby/projects">Projects</a>
              </li>
              <li>
                 <a href="/kirby/blog">Blog</a>
              </li>
              <li>
                 <a href="/kirby/about">About</a>
              </li>
              <li>
                 <a href="/kirby/contact">Contact</a>
              </li>
           </ul>
        </nav>
    </div>
</header>

<main role="main">

   <header>
      <h1>Blog</h1>
          <div class="intro text">
             <p>Blogging with Kirby is as easy as it’s fun. This simple blog shows just a basic implementation of a blogging engine, realized with only a few lines of code. It can easily be extended with tags, categories or whatever feature you need.</p>        
          </div>
       <hr />
   </header>

   <section>

      <article>
         <header>
             <h2>
                 <a href="/kirby/blog/content-in-kirby">Content in Kirby</a>
             </h2>
             <p class="article-date">August 4th, 2016</p>
          </header>
          <figure>
             <img src="/kirby/content/2-blog/20160804-content-in-kirby/content.png" alt="" />
           </figure>
           <div class="text">
              <p> How content is stored
                 In Kirby, content is stored within the /content directory, where every page is a folder. Pages can be nested, so every of those pages/folders may also contain subfolders.

                 Take this blog demo for example; all posts are just subfolders of the blog folder. This comes
                 <a href="/kirby/blog/content-in-kirby" class="article-more">read more</a>
             </p>
          </div>
       </article>

       <hr />

       <article>
           <header class="article-header">
               <h2>
                   <a href="/kirby/blog/licensing-kirby">Licensing Kirby</a>
               </h2>
               <p class="article-date">August 3rd, 2016</p>
           </header>

           <div class="text">
              <p>
                  As you probably already know, Kirby is a commercial product. You can try it as long as you want on your local machine and the source code is available on GitHub. But as soon as your want to use Kirby in production, you need to purchase a license. To keep ...     
                 <a href="/kirby/blog/licensing-kirby" class="article-more">read more</a>
             </p>
          </div>
       </article>

       <hr />

   </section>

   <nav>

       <span class="pagination-item left is-inactive">
       <svg viewBox="0 0 24 12"><path d="M1.94 6a28.38 28.38 0 0 0 8-4.47L8.71 5h12.23v2H8.71L10 10.47A28.4 28.4 0 0 0 1.94 6z"/></svg>
       </span>

       <a class="pagination-item right" href="/kirby/blog/page;2" rel="next" title="older articles">
       <svg viewBox="0 0 24 12"><path d="M22 6a28.38 28.38 0 0 1-8-4.47L15.22 5H3v2h12.22L14 10.47A28.4 28.4 0 0 1 22 6z"/></svg>
       </a>
   </nav>

</main>

<footer role="contentinfo">
   <div>
      <p class="footer-copyright">© 2009–2018 The Kirby Team</p>
      <p class="footer-madewithkirby">
         <a href="http://getkirby.com/made-with-kirby-and-love">Made with Kirby and <b class="heart">♥</b>
         </a>
      </p>
   </div>
</footer>

</body>

</html>

</code>

Dieser Code wurde zusammengesetzt aus den Dateien blog.php (Template), header.php (Snippet), menu.php (Snippet), coverimage.php (Snippet), pagination.php (Snippet) und footer.php (Snippet). Spätestens hier hat sich ein Anfänger in der Dateistruktur von Kirby verlaufen und schmeißt hin… Aber keine Angst, die Einteilung ist überaus logisch und wenn man sie verstanden hat, kann man jede HTML-Vorlage, die man verwenden möchte, in Kirby umsetzen!

Snippets - die modulare Seite

Für jede unterschiedliche Seite mit besonderen Funktionen benötigen wir ein Template. Welches Template verwendet wird, legen wir im Panel beim Anlegen einer neuen Seite fest (mehr zur Benutzung des Panels folgt später).

Rufen wir uns nochmal den Quelltext der Blogseite aus dem letzten Abschnitt ins Gedächtnis. Um diesen Quelltext in Kirby zu generieren, verwenden wir folgende Template- und Snippet-Dateien:

blog.php (Template)
   header.php (Snippet)
      menu.php (Snippet)
   coverimage.php
   pagination.php (Snippet)
footer.php (Snippet) 

Die Einrückungen zeigen bildlich, wie hier eine Verschachtelung von Snippets innerhalb des Templates stattfindet. Das Snippet header.php, das im Template blog.php ganz oben eingefügt wird, enthält ein weiteres Snippet, nämlich menu.php. Dieses Spiel kann man unendlich weiter in die Tiefe treiben, wenn man es für angemessen hält, Teile des Codes in kleine Portionen aufzuteilen. Diese Snippets sind natürlich wiederverwertbar und können auch in anderen Templates und an anderen Stellen verwendet werden, die Pagination zum Beispiel, die im Blog unter den Artikel-Vorschautexten zum Blättern zwischen den nächsten oder gegebenenfalls vorherigen drei Vorschautexten führt.

Hier einmal unsere HTML-Struktur in den Farben der verwendeten PHP-Dateien

<code>

<!doctype html>
<html>
   <head>
   </head>

    <body>

       <header>

          <nav>
          </nav>

       </header>

       <main>

          <header>
          </header>
          <section>
             <article>
                <figure>
                </figure>
             </article>
             <hr />
          </section>
          <nav>
          </nav>

      </main>

     <footer>
     </footer>

   </body>

</html>

</code>

Das Template blog.php enthält also streng genommen nur den Inhalt der Seite innerhalb des HTML-Tags <main>. Die Tags aus dem HTML-Grundgerüst <html> und <body> werden in der Datei header.php geöffnet und in der Datei footer.php geschlossen.

Und hier die komplette header.php aus dem Kirby Starter Kit:

<code>

<!doctype html>
<html lang="<?= site()->language() ? site()->language()->code() : 'en' ?>">
<head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width,initial-scale=1.0">
   <title><?= $site->title()->html() ?> | <?= $page->title()->html() ?></title>
   <meta name="description" content="<?= $site->description()->html() ?>">
   <?= css('assets/css/index.css') ?>
</head>

<body>

 <header class="header wrap wide" role="banner">

   <div class="grid">
      <div class="branding column">
       <a href="<?= url() ?>" rel="home"><?= $site->title()->html() ?></a>
      </div>    
      <?php snippet('menu') ?>

    </div>

 </header>

</code>

Für fehlerfreies HTML müssen der <html>- und der <body>-Tag geschlossen sein. Das geschieht in der footer.php:

<code>

    <footer role="contentinfo">
       <div>
          <p class="footer-copyright"><?php
            // Parse Kirbytext to support dynamic year,
            // but remove all HTML like paragraph tags:
            echo html::decode($site->copyright()->kirbytext())
           ?></p>

           <p class="footer-madewithkirby">
              <a href="http://getkirby.com/made-with-kirby-and-love">Made with Kirby and <b class="heart">♥</b></a>
           </p>

         </div>
       </footer>
   </body>
</html>

</code>

Innerhalb des normalen HTML-Codes werden Standard-PHP-Anweisungen verwendet wie echo und Variablen wie $page oder $site. Die Konstruktion <?= $site->title()->html() ?> aus der header.php z.B. sucht nach einem Inhalt namens “site” (befindet sich als Text-Datei in \kirby\content\site.txt) und dort nach einem Feld, das “title” heißt. Der Inhalt wird als HTML ausgegeben (in dem Eingabefeld im Panel darf also HTML verwendet werden, z.B. “Kirby Starterkit <span style="color:#f90;">meins</span>”). Nach diesem einfachen Prinzip können beliebige Inhalte aus beliebigen Feldern in beliebigen Blueprints an jeder Stelle ausgespielt werden.

Code im Blueprint site.yml:

<code>

title: Site

fields:
   title:
      label: Title
      type:  text

</code>

Eingabe im Panel:

Ausgabe auf der Seite:

Header und Footer sind zwei Bereiche, die voraussichtlich auf jeder unserer (Unter-)Seiten immer gleich sein werden. Zwischen diese Bereiche kommt der Hauptbereich der Seite, der je nach Inhalt variieren kann und sich im Ordner /kirby/site/templates befindet.

Würden wir den kompletten HTML-Code für die vollständige Seite in einer einzigen Datei notieren und wollten  eine Kleinigkeit in Header oder Footer ändern, so müssten wir diese Änderung in jedem einzelnen Template durchführen - was für ein Aufwand, wenn die Seite mehr ist als ein Onepager!

Durch diese Technik wird eine Kirby-Seite in kleinere, überschaubare Code-Teile zerlegt. Das erleichtert nicht nur die Programmierarbeit. Es reduziert auch Fehler und erleichtert die Wartung der Webseite.

Soviel für heute. Im Teil 3 befassen wir uns dann ausführlicher mit dem Backend von Kirby, dem Panel, und wie man dort Inhalte eingibt. Eine kurze Zusammenfassung der Vor- und Nachteile schließt die kleine Artikelserie ab.