Handlebars

Erstellen und Verwenden von Views (= Templates)

Eine Vorlage ist eine Textdatei, die ein beliebiges textbasiertes Format (HTML, XML, CSV, LaTeX ...) erzeugen kann. Der bekannteste Template-Typ ist eine PHP-Vorlage - eine von PHP analysierte Textdatei, die eine Mischung aus Text und PHP-Code enthält:

<!DOCTYPE html>
<html>
  <head>
    <title>Hallo brandbox.</title>
  </head>
  <body>
    <h1><?php echo $title ?></h1>
    
    <ul>
      <?php foreach ($list as $item): ?>
      <li>
        <a href="<?php echo $item->getHref() ?>">
          <?php echo $item->getCaption() ?>
        </a>
      </li>
      <?php endforeach ?>
    </ul>
  </body>
</html>

Aber brandbox bietet eine noch mächtigere Templating-Sprache namens Handlebars. Handlebars ermöglicht es Ihnen, prägnante, lesbare Vorlagen zu schreiben, die für Webdesigner freundlicher und in vielerlei Hinsicht leistungsfähiger als PHP-Vorlagen sind:

<!DOCTYPE html>
<html>
  <head>
    <title>Welcome to Symfony!</title>
  </head>
  <body>
    <h1>{{ title }}</h1>
    
    <ul id="navigation">
      {{#each serve.list}}
        <li><a href="{{ item.getHref }}">{{ item.getCaption }}</a></li>
      {{/each}}
    </ul>
  </body>
</html>

Handlebars definiert drei Arten spezieller Syntax:

"Sagt etwas": Gibt eine Variable aus oder das Ergebnis eines Ausdrucks auf die Vorlage.

{{# ...}}...{{/...}}

"Tut etwas": Ein Tag, das die Logik der Vorlage steuert. Es wird verwendet, um Anweisungen wie zum Beispiel for-Schleifen auszuführen.

"Kommentier etwas": Es ist das Äquivalent der PHP / * Kommentar * / Syntax. Es wird verwendet, um ein- oder mehrzeilige Kommentare hinzuzufügen. Der Inhalt der Kommentare ist nicht in den gerenderten Seiten enthalten. Handlebars enthält auch die Möglichkeit Helper zu erstellen, die den Inhalt vor dem Rendern ändern.

Eine ausführliche Beschreibung der Syntax finden Sie hier und auf handlebarsjs.com.

Warum Handlebars?

Handlebars-Templates sollen einfach sein und PHP-Tags nicht verarbeiten.

Das ist beabsichtigt: Das Handlebars-Vorlagensystem soll die Präsentation und nicht die Programmlogik zum Ausdruck bringen. Je mehr Sie Handlebars verwenden, desto mehr schätzen und profitieren Sie von dieser Auszeichnung.

Handlebars kann auch Dinge tun, die PHP nicht kann, wie automatisches HTML-Escaping, manuelles kontextabhängiges Ausgabe-Escaping und die Einbeziehung von benutzerdefinierten Funktionen und Filtern, die nur Templates betreffen.

Handlebars enthält kleine Funktionen, die das Schreiben von Templates einfacher und prägnanter machen.

Nehmen Sie das folgende Beispiel, das eine Schleife mit einer logischen else-Anweisung kombiniert:

<ul>
  {{#each datasets}}
    <li>{{ propertyA }}</li>
  {{else}}
    <li>Keine Datensätze gefunden.</li>
  {{/each}}
</ul>

Handlebar-Caching

Handlebars ist schnell, da jede Vorlage in eine native PHP-Klasse kompiliert und zwischengespeichert wird. Dies geschieht automatisch und Sie müssen nichts tun. Während Sie entwickeln, stellen Sie diese Funktion in der /config.php. Beispiel:

Template-Vererbung und Partials (...und Benennung/Speicherort)

Templates können verschachtelt werden, sodass wiederkehrende Elemente nicht mehrfach geschrieben werden müssen. In Handlebars stehen dafür sogenannte Partials zur Verfügung.

Im hier gezeigten Beispiel muss es diese Datei geben:

^{/plugin/remote/plugin_type/plugin_name/views/path/to/view.hbs}

Partials sind Dateien, die ohne Logik (ohne PHP) ausgeführt werden.

Features

Eine Alternative zu Partials bietet brandbox in Form von Feature-Aufrufen.

Feature-Aufrufe ermöglichen das gleiche Verhalten wie Partials, zusätzlich wird eine PHP-Methode aufgerufen. Beispiel:

Aufrufendes Template

plugin/remote/plugin_type/plugin_name/engine.php (Basis-Controller)

Die Rückgabe-Werte der Methode pathToView stehen im Template per serve zur Verfügung.

plugin/remote/plugin_type/plugin_name/views/path/to/view.hbs

Wenn Sie mit der Vererbung von Templates arbeiten, sollten Sie folgende Tipps beachten:

Partials und Feature-Calls unterscheiden sich in der Anzahl verwendeter Klammern. Drei Klammern werden benötigt um den HTML-Code nicht zu escapen.
Partial-Calls werden mit einem > gepräfixed, mit dem gleichen Ergebnis.
Feature-Calls müssen den Rückgabe-Wert der PHP-Methode durchgereicht bekommen, sodass der Kontext auch bei den nächsten Rekursions-Ebenen nicht verloren geht.
Beide Wege bieten die Möglichkeit, statische Parameter durchzureichen. Im Fall von Feature-Calls werden die statischen Parameter nach serve gelistet.

Beachten Sie die Syntax von Handlebars. Geschachtelte Handlebars-Templates können auch ../ Segmente enthalten, die ihre Pfade gegen einen übergeordneten Kontext auswerten. Es kann einfacher sein, direkt auf den Root-Kontext zuzugreifen. Beispiel:

Helper

Helper sind Funktionen, die beim Verarbeiten der Templates zur Verfügung stehen. So ist es möglich, die Eingabewerte direkt im Template zu verändern. Sie sollten jedoch nach Möglichkeit darauf verzichten, um die Trennung von Templates und Geschäftslogik nicht zu stark aufzuweichen. Auf Handlebars-Helper kann von jedem Kontext in einer Vorlage zugegriffen werden. Sie können Helper mit einer Klasse des Speicherorts lib/helper.php registrieren und darin Methoden ergänzen. Beachten Sie, dass der Cache geleert werden muss, damit der Helper registriert wird.

plugin/remote/plugin_type/plugin_name/lib/helper.php

Bitte verwenden Sie den Präfix helper, um Helper-Methoden von Variablen bzw. integrierten Methoden unterscheiden zu können.

Escaping

Handlebars führt beim Rendern von Inhalten automatisch Ausgabe-Escaping aus, um Sie vor Cross-Site-Scripting-Angriffen (XSS) zu schützen.

Debugging

Um zu prüfen, welche Daten im Template ankommen, sind folgende Helper-Funktionen hilfreich:

brandbox – Eine Plattform, unendliche Möglichkeiten