Template Engine

Die WEBSALE Template-Sprache bietet eine leistungsstarke und flexible Möglichkeit, das Frontend eines Onlineshops individuell zu gestalten. Dynamische Inhalte wie Produkt- oder Benutzerdaten können nahtlos in HTML-Templates eingebunden und sprachabhängige Texte oder komplexe Bedingungen berücksichtigt werden. Diese Dokumentation vermittelt die grundlegenden Funktionen und Werkzeuge, die in der täglichen Arbeit bei der Gestaltung von Onlineshops häufig verwendet werden. Von der Verwendung von Variablen über die Anwendung von Schleifen und Bedingungen bis hin zur Nutzung von Modifikatoren wird beschrieben, wie Inhalte dynamisch gestaltet und angepasst werden können.

WEBSALE Template Engine

Die WEBSALE Template Engine wird für die komplette Erstellung und Gestaltung der Storefront verwendet. Sie benötigen keine Kenntnisse in Programmiersprachen wie PHP oder Java und auch kein Wissen über Datenbankzugriffe, um Ihren individuellen WEBSALE Onlineshop zu erstellen und anzupassen. Mit der WEBSALE Template Engine können dynamische Inhalte im Onlineshop einfach angezeigt werden – ganz ohne komplexe Backend-Logik. Als Template-Manager können Sie sich voll und ganz auf HTML, CSS und JavaScript konzentrieren und dynamische Daten wie Produktinformationen, Benutzerprofile oder Preise mithilfe unserer Template Engine und Template-Sprache einbinden.

Grundlagen und Syntax der WEBSALE Template Engine

In der WEBSALE-Template-Umgebung basieren alle Templates auf Standard-HTML-Dateien mit den Endungen .htm oder .html, die innerhalb der Shop-Verzeichnisstruktur abgelegt sind. Innerhalb dieser HTML-Dateien können sogenannte Template-Tags verwendet werden, um dynamische Inhalte oder sprachabhängige Texte in das Frontend einzubinden. Die Template-Tags ermöglichen die Einbindung von:

Textbausteinen für sprachabhängige Inhalte.
Platzhaltern für dynamische Inhalte wie Produktdaten, Benutzerdaten oder Shop-Funktionen.

Textbausteine

Textbausteine werden verwendet, um sprachabhängige Texte wie Button-Beschriftungen oder Überschriften zentral zu verwalten und in die Templates einzufügen. Ihre Syntax ist einfach und eindeutig:

%%Textbausteinname%%

Beispiel: Button “in den Warenkorb”

<button type="button">%%AddToCart%%</button>

Textbausteine werden nicht nur in Templates verwendet, sondern auch in Konfigurationen, sofern dort sprachabhängige Texte für die Frontend-Ausgabe hinterlegt werden, zum Beispiel Anzeigetexte oder Beschreibungen. Weitere Informationen zur Verwendung von Textbausteinen in Konfigurationen finden Sie im Bereich Konfigurationen. Die Schreibweise %%Textbausteinname%% setzt voraus, dass die Bezeichnung beim Erstellen des Templates bereits feststeht. Beim Veröffentlichen der Templates ersetzt der Shop sie durch den Text. Wenn die Bezeichnung erst beim Aufruf der Seite feststeht, beispielsweise weil sie aus einem Statuscode eines externen Systems gebildet wird, verwenden Sie stattdessen die Funktion translate:

{{= translate("shop.basket.addButton") }}

Platzhalter (für dynamische Inhalte)

Platzhalter dienen zur Einbindung von dynamischen Daten, die zur Laufzeit vom Backend bereitgestellt werden. Die Syntax ist HTML-ähnlich und verwendet doppelte geschweifte Klammern {}:

{{= $variable }}

Beispiel: Produktname und Produktbeschreibung

<h1>{{= $myProduct.name}}</h1>
<p>{{= $myProduct.description }}</p>

Die Template Engine interpretiert diese Platzhalter und ersetzt sie zur Laufzeit mit den entsprechenden Werten aus dem System.

Standard-Escaping

Die WEBSALE Template-Engine verfügt über ein integriertes Standard-Escaping, das automatisch auf alle dynamisch eingebundenen Inhalte angewendet wird. Dadurch wird sichergestellt, dass HTML- oder JavaScript-Code, der z. B. in Produktdaten oder CMS-Inhalten enthalten ist, nicht interpretiert, sondern als Klartext dargestellt wird. Viele Inhalte im Shop – z. B. Produktbeschreibungen, CMS-Artikel oder andere redaktionelle Texte – enthalten HTML zur Formatierung. Damit diese Inhalte nicht unbeabsichtigt als echter HTML-Code ausgeführt werden, wird bei der Ausgabe mit {{= ... }} ein automatisches Escaping angewendet. Beispiel: Standard-Escaping aktiviert

{{= $product.description }}

Inhalt in den Shopdaten:

<p><strong>Super atmungsaktiv</strong> – ideal für Sport und Freizeit. Jetzt in der <em>neuesten Generation</em> erhältlich.</p>

Ausgabe im Browser:

&lt;p&gt;&lt;strong&gt;Super atmungsaktiv&lt;/strong&gt; – ideal für Sport und Freizeit. Jetzt in der &lt;em&gt;neuesten Generation&lt;/em&gt; erhältlich.&lt;/p&gt;

Der HTML-Code wird nicht interpretiert, sondern als normaler Text angezeigt. Das schützt vor unbeabsichtigter Codeausführung. Wenn Inhalte bewusst als HTML ausgegeben werden sollen – z. B. weil Produkttexte oder CMS-Inhalte HTML enthalten und korrekt gerendert werden sollen – kann das Escaping gezielt deaktiviert werden. Dazu wird statt = ein Ausrufezeichen ! verwendet:

{{! $product.description }}

Ausgabe im Browser:

<p><strong>Super atmungsaktiv</strong> – ideal für Sport und Freizeit. Jetzt in der <em>neuesten Generation</em> erhältlich.</p>

Jetzt wird der HTML-Code korrekt interpretiert und gerendert. Wichtig: Die Deaktivierung des Escapings sollte nur bei vertrauenswürdigen Inhalten erfolgen – z. B. bei Daten aus dem eigenen Produkt-Backend oder CMS. Inhalte, die z. B. über Formulareingaben von Kunden stammen, sollten nicht ungefiltert ohne Escaping ausgegeben werden.

Variablen

Mit der WEBSALE Template-Sprache können die Daten ausgegeben werden, die vom Shopsystem bereitgestellt werden. Jede Seite, die von der Template Engine gerendert wird, erhält so die benötigten Daten, um die angeforderten Inhalte anzuzeigen. Diese Daten werden in sogenannten Template-Variablen gespeichert. Alle Template-Variablen können über die Template-Sprache mit einem $ gefolgt vom Variablennamen aufgerufen werden. Variablennamen können frei vergeben werden. Es gibt auch Systemvariablen, die mit $ws beginnen und deren Namen vorgegeben sind. Beispiele hierfür sind die Module $wsProducts und $wsCategories. Eine vollständige Übersicht der WEBSALE Systemvariablen und weitere Informationen zu den Variablen allgemein finden Sie in der Übersicht der Variablen.

Variablen setzen & verwenden

Beispiel: Neue Variable

{{ var $myProduct = $wsProducts.load('1234') }}

Neue Variablen werden immer mit dem var-Keyword definiert. In diesem Beispiel lädt die Funktion $wsProducts.load('1234') die Daten des Produkts mit der Produkt-ID 1234. Diese werden in der Variable $myProduct gespeichert und können später verwendet werden. Beispiel: Verwendung der Variablen

{{ var $myProduct = $wsProducts.load('1234') }}

<h1>{{= $myProduct.name }}</h1>
<p>{{= $myProduct.description }}</p>
<p>Preis: {{= $myProduct.price }} €</p>

Einmal definierte Variablen können an beliebigen Stellen im Template genutzt werden. In diesem Fall:

Die Produktdaten werden in $myProduct gespeichert.
Der Produktname, die Beschreibung und der Preis werden dynamisch in das Template eingefügt.

Beispiel: Verschachtelte Variable

{{ var $myProduct = $wsProducts.load('1234') }}

<img src="{{= $myProduct.custom.mainImage.thumbnail }}" alt="Produktbild">

Variablen können auch verschachtelt sein, um auf spezifische Werte innerhalb von komplexen Datenstrukturen wie Objekten oder Arrays zuzugreifen. Die Verschachtelung erfolgt immer durch Punkte . zwischen den einzelnen Ebenen. In diesem Beispiel:

$myProduct ist die Hauptvariable für das Produkt.
custom verweist auf benutzerdefinierte Daten des Produkts.
mainImage gibt das Hauptbild des Produkts an. Der Feldname ist ein Beispiel und hängt von den Produktdatenfeldern ab, die im Shop angelegt sind.
thumbnail greift auf die verkleinerte Version des Bildes zu.

Eine vollständige Liste aller Variablen sowie deren Beschreibung finden Sie in der Übersicht der Variablen.

Gültigkeitsbereich von Variablen

Der Gültigkeitsbereich einer Variablen definiert, wo sie im Template verwendet werden kann. Variablen, die außerhalb von Bereichsanweisungen wie if oder foreach definiert werden, sind im gesamten Template gültig:

{{ var $myCategory = $wsCategories.loadCategory('5678') }}

<h2>{{= $myCategory.name }}</h2>
{{ if $myCategory.active }}
    <p>Diese Kategorie ist aktiv.</p>
{{ /if }}

Variablen, die innerhalb von Bereichsanweisungen definiert werden, existieren nur innerhalb dieses Bereichs:

{{ foreach $myProduct in $wsCategories.loadProducts('5678') }}
    <h3>{{= $myProduct.name }}</h3>
    <p>{{= $myProduct.price }} €</p>
{{ /foreach }}

<p>{{= $myProduct.name }}</p>  -> $myProduct ist außerhalb der Schleife nicht gültig

Modifiers (Modifikatoren)

Manchmal reicht es nicht aus, den Inhalt einer Variable einfach nur auszugeben. Der Wert muss zuvor verändert oder angepasst werden. Genau dafür gibt es die sogenannten Modifiers. Modifiers können auf alle Variablen angewendet werden, um deren Inhalt zu verändern. Dazu fügen Sie der entsprechenden Variable ein | (Pipe-Zeichen) und den Modifiernamen hinzu. Zusätzliche Parameter werden in runden Klammern angegeben. Beispiel: Kürzen eines Textes

{{= $myProduct.name | take(30) }}

In diesem Beispiel wird der Modifier take auf den Produktnamen angewendet. Er gibt nur die ersten 30 Zeichen aus. Beispiel: Mehrere Modifiers auf eine Variable anwenden Sie können auch mehrere Modifiers hintereinander auf eine Variable anwenden. Sie werden in der angegebenen Reihenfolge verarbeitet.

{{= $myProduct.description | stripHtml | take(120) }}

Hier entfernt stripHtml zunächst die HTML-Formatierungen aus der Produktbeschreibung. Anschließend kürzt take den reinen Text auf 120 Zeichen. Eine vollständige Liste aller Modifiers sowie deren Beschreibung finden Sie in der Übersicht der Modifikatoren.

Bedingungen (Conditions)

Mithilfe von Bedingungen können Sie die Ausgabe in der Storefront abhängig von bestimmten Werten variieren. Eine Bedingung wird mit {{ if }} eingeleitet und mit {{ /if }} abgeschlossen. Dazwischen sind beliebig viele {{ elseif }}-Zweige und ein {{ else }}-Zweig erlaubt. Der Inhalt eines Zweigs wird nur ausgegeben, wenn die Prüfung darin wahr (true) ist. Beispiel:

{{ if $myProduct.description }}
    {{= $myProduct.description }}
{{ else }}
    {{= $myProduct.custom.shortdescr }}
{{ /if }}

In diesem Beispiel wird geprüft, ob die Variable $myProduct.description einen Inhalt hat. Wenn ja, wird ihr Inhalt ausgegeben. Andernfalls wird der alternative Inhalt im else-Zweig ausgegeben, hier eine Kurzbeschreibung aus einem Produktdatenfeld. Zusätzlich zu if und else können auch mehrere Prüfungen hintereinander definiert werden, indem {{ elseif }} hinzugefügt wird. Beispiel: Begrüßung des Besuchers im Onlineshop

Ist ein Kunde eingeloggt und hat er eine Rechnungsadresse hinterlegt, wird er mit seinem Vornamen begrüßt.
Ist ein Kunde eingeloggt, aber ohne hinterlegte Rechnungsadresse, wird eine allgemeine Begrüßung angezeigt.
Für alle nicht eingeloggten Besucher wird ein Hinweis zur Registrierung angezeigt.

{{ if $wsAccount.isLoggedIn and $wsAccount.defaultBillAddress.firstName }}
    <p>Willkommen zurück, {{= $wsAccount.defaultBillAddress.firstName }}!</p>
{{ elseif $wsAccount.isLoggedIn }}
    <p>Willkommen zurück!</p>
{{ else }}
    <p>Willkommen! Registrieren Sie sich.</p>
{{ /if }}

Beispiel: Bedingungen mit Operatoren, beispielsweise für den Lagerbestand Mit Operatoren lassen sich auch Werte vergleichen, beispielsweise mit > oder < die verfügbare Stückzahl eines Produktes. Die Bestandsdaten liefert das Modul $wsInventory:

{{ var $myInventory = $wsInventory.load($myProduct.id) }}
{{ if $myInventory.amount > 0 }}
    <p>Dieses Produkt ist verfügbar.</p>
{{ else }}
    <p>Dieses Produkt ist nicht verfügbar.</p>
{{ /if }}

Eine vollständige Übersicht der verfügbaren Operatoren und deren Verwendung finden Sie in der Referenz der Operatoren.

Loops (Schleifen)

Schleifen ermöglichen es, durch eine Liste mit mehreren Datensätzen, beispielsweise Produkten, zu iterieren und automatisch Inhalte für jeden einzelnen Datensatz zu erzeugen. So können Sie wiederkehrende Strukturen wie Produktlisten oder Bildergalerien effizient erstellen. Eine Schleife wird mit {{ foreach <Laufvariable> in <Liste> }} geöffnet und mit {{ /foreach }} geschlossen. Der Name der Laufvariable kann frei gewählt werden und darf Buchstaben, Zahlen sowie Unterstriche enthalten. Die foreach-Schleife durchläuft alle Elemente einer Liste und führt den eingeschlossenen Codeabschnitt für jedes Element aus. Dabei wird mit jedem Durchlauf das aktuelle Element der Laufvariable zugewiesen. Beispiel: Produktliste einer Kategorie

{{ var $myProducts = $wsCategories.loadProducts('5678') }}
<div class="product-list">
    {{ foreach $myProduct in $myProducts }}
        <div class="product-item">
            <h2>{{= $myProduct.name }}</h2>
            <p>{{= $myProduct.description }}</p>
            <p>Preis: {{= $myProduct.price }} €</p>
        </div>
    {{ /foreach }}
    {{ if not $myProducts }}
        <p>Keine Produkte in dieser Kategorie verfügbar.</p>
    {{ /if }}
</div>

Die Schleife durchläuft alle Produkte der Kategorie mit der ID 5678 und erstellt für jedes Produkt ein neues <div>-Element. Enthält die Kategorie keine Produkte, ist die Liste leer und die anschließende Bedingung gibt eine entsprechende Nachricht aus. Vollständige Informationen zu den Schleifen finden Sie unter Loops.

Vollständige Referenzdokumentation

Natürlich bietet die WEBSALE Template-Sprache noch viele weitere Funktionen und Möglichkeiten. Die oben beschriebenen Grundlagen gehören jedoch zu den am häufigsten genutzten Werkzeugen in der täglichen Arbeit bei der Bearbeitung des WEBSALE Onlineshops. Eine vollständige Übersicht aller Funktionen, Module, Aktionen und Möglichkeiten finden Sie in unserer Referenzdokumentation.

WEBSALE

Frontend

Die Basics

Getting Started

Referenz – Aktionen

Referenz – Sprache

Referenz – Module

Integrationsanleitung

Praxisbeispiele

WEBSALE Template Engine

Grundlagen und Syntax der WEBSALE Template Engine

Textbausteine

Platzhalter (für dynamische Inhalte)

Standard-Escaping

Variablen

Variablen setzen & verwenden

Gültigkeitsbereich von Variablen

Modifiers (Modifikatoren)

Bedingungen (Conditions)

Loops (Schleifen)

Vollständige Referenzdokumentation

​WEBSALE Template Engine

​Grundlagen und Syntax der WEBSALE Template Engine

​Textbausteine

​Platzhalter (für dynamische Inhalte)

​Standard-Escaping

​Variablen

​Variablen setzen & verwenden

​Gültigkeitsbereich von Variablen

​Modifiers (Modifikatoren)

​Bedingungen (Conditions)

​Loops (Schleifen)

​Vollständige Referenzdokumentation

WEBSALE Template Engine

Grundlagen und Syntax der WEBSALE Template Engine

Textbausteine

Platzhalter (für dynamische Inhalte)

Standard-Escaping

Variablen

Variablen setzen & verwenden

Gültigkeitsbereich von Variablen

Modifiers (Modifikatoren)

Bedingungen (Conditions)

Loops (Schleifen)

Vollständige Referenzdokumentation