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>

Kommentare