Erste Operationen¶
Die Template-Engine unterstützt einige Manipulationen, die es dem Designer erlauben mit Hilfe von data-
Attributen
Operationen zu definieren. Der Teil nach dem data-
ist hierbei der Name der Operation. Der Webdesigner kann eine valide HTML5
Datei mit Beispieldaten erzeugen. Dies kann in einem zweiten Arbeitsschritt mit einer Brücke zu den Daten versehen werden.
<div data-[OPERATION]=""></div>
Eine konkrete Operation ist das Ersetzen von Werten in einem Tag mittels data-replace
.
<div data-replace="auto"></div>
Der Zugriff auf die Daten kann mittels der folgenden Zugriffsmethoden erfolgen.
Schlüsselwort | Aufruf | Beschreibung | Beispiel |
---|---|---|---|
dataset | dataset:key:[default] | Als Wert wird der Eintrag mit dem Schlüssel key aus dem Dataset genommen. Wird kein Wert mit diesem Schlüssel gefunden, so wird der optionale Defaultwert genommen | data-repace="dataset:index:the default" |
static | static:content | Der Inhalt content wird als statischer Inhalt verwendet. | data-replace="static:my title" |
Syntax¶
Pipes¶
Über die aus Unix bekannten Pipes, können die Daten nachfolgende Funktionen übergeben werden. Für unterschiedliche Datentypen stehen verschiedene Funktionen zur Verfügung.
Zeichenketten¶
Zeichenkettenoperationen erlauben die Manipulation von Zeichen. Mehrere Funktionen können mit einer Pipe verbunden werden. Das nachfolgende Beispiel ersetzt den Inhalt des p-Tags mit dem Text aus dem Dataset mit dem Index text, wandelt die Zeichen in Kleinbuchstaben um und führt ein trim durch.
<div>
<p data-replace="dataset:text | strtolower | trim">My World</p>
</div>
In der folgenden Auflistung sind die verscheidenen Funktionen beschrieben.
Schlüsselwort | Aufruf | Beschreibung | Beispiel |
---|---|---|---|
strtolower | strtolower | Alle Zeichen werden in Kleinbuchstaben umgewandelt.Entspricht der PHP-Funktion mb_strtolower. | dataset:myKey |
strtoupper | strtoupper | Alle Zeichen werden in Großbuchstaben umgewandelt.Entspricht der PHP-Funktion mb_strtoupper. | dataset:myKey |
trim | trim | Alle Leerzeichen am Anfang und Ende werden entfernt.Entspricht der PHP-Funktion trim. | dataset:myKey |
plaintext | plaintext | Alle Tags werden entfernt. Entspricht der PHP-Funktion strip_tags. | dataset:myKey |
rawurlencode | rawurlencode | Die Zeichenkette wir URL-Encoded. Entspricht der PHP-Funktion strip_tags. | dataset:myKey |
ucfirst | ucfirst | Das erste Zeichen der Zeichektte wird in einen Großbuchstaben umgewandeltEntspricht der PHP-Funktion ucfirst. | dataset:myKey |
ucwords | ucwords | Wandelt jeden ersten Buchstaben eines Wortes innerhalb der Zeichenkette in einen Großbuchstaben um. Entspricht der PHP-Funktion ucwords. | dataset:myKey |
intval | intval | Ermittelt den Integer einer ZeichenketteEntspricht der PHP-Funktion intval. | dataset:myKey |
length | length | Länge der Zeichenkette.Entspricht der PHP-Funktion strlen. | dataset:myKey |
base64 | base64 | Base64 codierte Zeichenkette.Entspricht der PHP-Funktion base64_encode. | dataset:myKey |
htmlspecialchars | htmlspecialchars | Wandelt Sonderzeichen in HTML-Codes umEntspricht der PHP-Funktion htmlspecialchars. | dataset:myKey |
htmlentities | htmlentities | Konvertiert alle benannten HTML-Zeichen in ihre entsprechenden UrsprungszeichenEntspricht der PHP-Funktion html_entity_decode. | dataset:myKey |
md5 | md5 | Berechnet den MD5-Hash der ZeichenketteEntspricht der PHP-Funktion md5. | dataset:myKey |
sha1 | sha1 | Berechnet den SHA1-Hash der ZeichenketteEntspricht der PHP-Funktion sha1. | dataset:myKey |
reverse | reverse | Umdrehen der Zeichenfolge. Aus Hallo wird ollaH.Entspricht der PHP-Funktion strrev. | dataset:myKey |
substring | substring:start:length | Schneidet aus der Zeichenkette den Teil von Start bis Length aus.Entspricht der PHP-Funktion substr. | dataset:myKey |
Collections¶
Operationen für Collection erlauben den Zugriff auf spezifische Einträge einer Collection.
<div>
<a data-attributes="href dataset:url | index:2 | strtolower, title string:Mein Titel | trim">My World</a>
</div>
In der folgenden Auflistung sind die verscheidenen Funktionen beschrieben.
Schlüsselwort | Aufruf | Beschreibung | Beispiel |
---|---|---|---|
next | next | Das nächste Element wird für die weitere Verarbeitung verwendet.Entspricht der PHP-Funktion next. | dataset:myKey |
current | current | Es wird mit dem aktuellen Element weitergearbeitet.Entspricht der PHP-Funktion strtoupper. | dataset:myKey |
length | length | Anzahl der Elemente in der Collection.Entspricht der PHP-Funktion count. | dataset:myKey |
index | index:INDEX | Es wird das INDEX Element für die weitere Verarbeitung genommen.Entspricht der PHP-Funktion strtoupper. | dataset:myKey |
Maps¶
Operationen für Maps erlauben den Zugriff auf spezifische Einräge einer Map.
<div>
<a data-attributes="href dataset:url | index:name | strtolower, title string:Mein Titel | trim">My World</a>
</div>
In der folgenden Auflistung sind die verscheidenen Funktionen beschrieben.
Schlüsselwort | Aufruf | Beschreibung | Beispiel |
---|---|---|---|
index | index:INDEX | Es wird das INDEX Element für die weitere Verarbeitung genommen.Entspricht der PHP-Funktion strtoupper. | dataset:myKey |
Standard Operationen¶
Standardoperationen sind direkt in der Komponente implementiert und stehen bei der Verwendung der Komponete sofort zur Verfügung. Die Reihenfolge der Attribute ist von Links nach rechts. Wird zuerst eine replace und dann ein repeat Operation definiert, kann replace nicht auf die Iteration von repeat zugreifen.
Die beiden Definitionen sind unterschiedlich:
<!-- Falsch: In dem Beispiel kann data-replace nicht auf myindex zugreifen -->
<div data-replace="dataset:myindex" data-repeat="myindex dataset:list"></div>
<!-- Richtig: In der Definition kann replace auf myindex zugreifen -->
<div data-repeat="myindex dataset:list" data-replace="dataset:myindex"></div>
Ersetzen (data-replace)¶
Die einfachste Operation ist das Ersetzen des Inhaltes einer Node mit einem statischen Wert.
$html = <<<EOF
<div>
<p data-replace="static:myurl">empty</p>
</div>
EOF;
echo (new \Alvine\Markup\Html\Engine())
->getHTML($html);
return;
ergibt folgende Ausgabe
<div>
<p>myurl</p>
</div>
Neben dem Ersetzen von statischen Werten können die Werte aus einem Dataset ersetzt werden. Dazu muss der Engine ein Dataset übergeben werden.
$html = <<<EOF
<div>
<p data-replace="dataset:url">url</p>
</div>
EOF;
echo (new \Alvine\Markup\Html\Engine())
->setDataset((new \Alvine\Markup\Html\Dataset)
->setValue('url', new \Alvine\Net\Resource\URI('http://www.example.com')))
->getHTML($html);
ergibt folgende Ausgabe
<div>
<p>http://www.example.com</p>
</div>
Ersetzen inklusive des Tags (data-replaceself)¶
Beim Ersetzen einschlißlich des Tags wird der Tag samt Kindern und Inhalt durch den zu ersetzenden Inhalt ersetzt.
$html = <<<EOF
<div>
<p data-replaceself="static:myurl">empty</p>
</div>
EOF;
echo (new \Alvine\Markup\Html\Engine())
->getHTML($html);
ergibt folgende Ausgabe
<div>
myurl
</div>
Wie man sieht wird bei replaceself der Ausgangstag ebenfalls ersetzt. Dies ist nützlich, wenn man eine Markierung einfügen möchte, die aber im finalen HTML nicht erscheinen soll.
Node Entfernen (data-remove)¶
Möchte man einzelne Nodes entfernen, so kann man das Attribute data-remove einsetzen.
$html = <<<EOF
<div>
<p data-remove>empty</p>
</div>
EOF;
echo (new \Alvine\Markup\Html\Engine())
->getHTML($html);
ergibt folgende Ausgabe
<div>
</div>
Wie man sieht wird der komplette Tag inklusive Inhalt entfernt.
Tag entfernen (data-removetag)¶
Der Unterschied dieser Operation zu remove ist, dass der Inhalt des Tags erhalten bleibt.
$html = <<<EOF
<div>
<p data-removetag>em<b>p</b>ty</p>
</div>
EOF;
echo (new \Alvine\Markup\Html\Engine())
->getHTML($html);
ergibt folgende Ausgabe
<div>
em
<b>p</b>
ty
</div>
Wie man sieht wird der Ausgangstag ersetzt, aber der Inhalt bleibt erhalten.
Bedingtes anzeigen (data-condition)¶
Die Bedingung steuert, ob ein Tag ausgeblendet oder angezeigt wird.
$html = <<<EOF
<div>
<p data-condition="exists:myindex">empty</p>
</div>
EOF;
echo (new \Alvine\Markup\Html\Engine())
->getHTML($html);
ergibt folgende Ausgabe
<div>
</div>
Wie man sieht wird der Ausgangstag ersetzt, da kein Wert mit dem Index myindex vorhanden ist.
In der folgenden Tabelle sind die gültigen Ausdrücke zusammengefasst.
Schlüsselwort | Aufruf | Beschreibung | Beispiel |
---|---|---|---|
exists | exists:index | Es wird geprüft ob im Dataset ein Wert mit dem Index index vorhanden und ungleich null ist. | exists:url |
true | true:index | Es wird geprüft ob der Wert verfügbar ist und true (on, 1, true, ...) ergibt. | true:url |
false | false:index | Es wird geprüft ob der Wert verfügbar ist und false (off, 0 false, ...) ergibt. | false:url |
Attribute setzen (data-attributes)¶
Mit der Attributes-Operation können die Attribute innerhalb eines Tags bearbeitet werden. Mit dem folgenden Beispiel
/**
* HTML-Template
*/
$html = <<<EOF
<div>
<a data-attributes="href dataset:url">My World</a>
</div>
EOF;
/**
* Ausgabe
*/
echo (new \Alvine\Markup\Html\Engine())
->setDataset((new \Alvine\Markup\Html\Dataset)
->setValue('url', new \Alvine\Net\Resource\URI('http://www.example.com')))
->getHTML($html);
wird dieses Ergebnis ausgegeben.
<div>
<a href="http://www.example.com">My World</a>
</div>
Mehrere Attribute lassen sich durch ein Komma trennen. Wird der Wert für das Attribute im Dataset nicht gefunden (null) wird das Attribute nicht gesetzt.
<div>
<a data-attributes="href dataset:url, title string:Mein Titel">My World</a>
</div>
Diese Anweisung ergibt
<div>
<a href="http://www.example.com" title="Mein Titel">My World</a>
</div>
Wiederholung (data-repeat)¶
Mit Hilfe der Wiederholung lassen sich ganz Blöcke dupizieren und mit den Werten einer Collection füllen. Die im folgende HTML-Datei soll für jeden Datensatz in der Liste list ein Zeile erhalten. Die Anweisung bei der Iteration besteht aus zwei Bestandteilen: dem Schlüssel und der Collection. Über den Schlüssel (im Beispiel citty) wird die Variabel bei jedem Durchlauf angesprochen. Existiert bereits ein anderer Eintrag mit dem Namen so wird der bestehende überschrieben.
<div>
<table>
<tr data-repeat="city dataset:list">
<td data-replace="dataset:city">placeholder</td>
</tr>
</table>
</div>
In PHP-Code sieht die Funktion folgendermassen aus.
$html = <<<EOF
<div>
<table>
<tr data-repeat="city dataset:list">
<td data-replace="dataset:city">placeholder</td>
</tr>
</table>
</div>
EOF;
echo (new \Alvine\Markup\Html\Engine())
->setDataset((new \Alvine\Markup\Html\Dataset)
->setValue('list', (new \Alvine\Types\Collection())
->append(new \Alvine\Types\String('München'))
->append(new \Alvine\Types\String('Frankfurt'))
->append(new \Alvine\Net\Resource\URI('http://www.example.com'))
->append(new \Alvine\Types\String('Berlin'))))
->getHTML($html);
Das Ergebnis ist eine Tabelle mit 4 Zeilen.
<div>
<table>
<tbody>
<tr><td>München</td></tr>
<tr><td>Frankfurt</td></tr>
<tr><td>http://www.example.com</td></tr>
<tr><td>Berlin</td></tr>
</tbody>
</table>
</div>
An dem Beispiel sieht man auch gut, das andere Typen (die über eine __toString() Methode verfügen verwendet werden können. Wiederholung mit mehreren Werten (data-repeat)
<div>
<table>
<tr data-repeat="city dataset:list">
<td data-replace="dataset:city | index:name">Musterstadt</td>
<td data-replace="dataset:city | index:plz">12345</td>
<td data-replace="dataset:city | index:einwohner">98456</td>
</tr>
</table>
</div>
$cityList=new \Alvine\Types\Collection();
$cityA=new \Alvine\Types\Map();
$cityA->setValue('name', 'München');
$cityA->setValue('plz', '80331');
$cityA->setValue('einwohner', '1365015');
$cityList->append($cityA);
$cityB=new \Alvine\Types\Map();
$cityB->setValue('name', 'Frankfurt');
$cityB->setValue('plz', '60311');
$cityB->setValue('einwohner', '691520');
$cityList->append($cityB);
$dataset=new \Alvine\Markup\Html\Dataset();
$dataset->setValue('list', $cityList);
$engine=new \Alvine\Markup\Html\Engine();
$engine->setDataset($dataset);
// Variable $template muss das HTML-Template als Zeichenkette enthalten
echo $engine->getHTML($template);
5e038617-bc19-414b-f02d-0e83d650c818
<div>
<table>
<tbody>
<tr>
<td>München</td>
<td>80331</td>
<td>1365015</td>
</tr>
<tr>
<td>Frankfurt</td>
<td>60311</td>
<td>691520</td>
</tr>
</tbody>
</table>
</div>
Fehler anzeigen (data-debug)¶
Der Unterschied dieser Operation zu remove ist, dass der Inhalt des Tags erhalten bleibt.
$html = <<<EOF
<div>
<div data-debug></div>
</div>
EOF;
echo (new \Alvine\Markup\Html\Engine())
->getHTML($html);
Dieses Attribute fürgt in das Ergebnis eine Liste mit den während des Parsens auftretenden Fehler an.
Eigene Operationen¶
Neben den in der Komponente verfügbaren Operationen können auch eigene Operationen integriert werden. Dazu muss man lediglich eine Klasse erstellen, die von \Alvine\Markup\Html\AbstractOperation abgeleitet ist.
namespace My\Html;
class MyOperation extends \Alvine\Markup\Html\AbstractOperation {
public static function process($value, \Alvine\Markup\Html\Node $element, \Alvine\Types\Map $map = null) {
$element->setValue('My');
return $element;
}
}
In der HTML-Datei wird die Operation über die folgende HTML5 kompatible Strutur aufgerufen.
<div data-\My\Html\MyOperation="auto"></div>