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.

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:

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

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 System-Variablen, die mit $ws beginnen und deren Namen vorgeben sind, z.B. $wsProduct, $wsCategory etc. Eine vollständige Übersicht der WEBSALE System-Variablen und mehr Informationen zu den Variablen allgemein finden Sie hier.

Variablen setzen & verwenden

Beispiel: Neue Variable

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

Neue Variablen werden immer mit dem var-Keyword definiert.

In diesem Beispiel lädt die Funktion $wsProduct.load('1234') die Produktdaten des Produkts mit der Artikelnummer 1234. Diese werden in der Variable $myProduct gespeichert und können später verwendet werden.

Beispiel: Verwendung der Variablen

{{ var $myProduct = $wsProduct.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 = $wsProduct.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:

• $product ist die Hauptvariable für das Produkt.
• custom verweist auf benutzerdefinierte Daten des Produkts.
• mainImage gibt das Hauptbild des Produkts an.
• 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 = $wsCategory.load('5678') }}
  
  <h2>{{= $myCategory.name }}</h2>
{{ if $myCategory.isActive }}
      <p>Diese Kategorie ist aktiv.</p>
  {{ /if }}

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

{{ foreach $myProduct in $wsCategory.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 vorher verändern oder angepasst werden. Genau dafür gibt es die Modifiers.

Modifiers können auf alle Variablen angewendet werden, um deren Inhalt zu verändern. Dazu hängen sie einfach ein | (Pipe-Zeichen) und den Modifiernamen an die entsprechende Variable an. Zusätzliche Parameter werden mit : hinzugefügt.

Beispiel: Kürzen der Produktbeschreibung

{{= $myProduct.description|truncate:120 }}

In diesem Beispiel wird der Modifikator truncate auf die Produktbeschreibung angewendet. Dieser kürzt den Text auf eine maximale Länge von 120 Zeichen.

Beispiele: Mehrere Modifikatoren auf eine Variable anwenden

Sie können auch mehrere Modifikatoren hintereinander auf eine Variable anwenden. Diese werden in der Reihenfolge verarbeitet, in der sie angegeben werden.

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

---

Bedingungen (Conditions)

Die WEBSALE {if}-Bedingungen erlauben die selbe Flexibilität wie in PHP oder Javascript, bis auf ein paar Erweiterungen für die Template-Engine. Jedes {if} muss mit einem {/if} kombiniert sein. {else} und {elseif} sind ebenfalls erlaubt. Alle gängigen PHP Vergleichsoperatoren und Funktionen, wie ||, or, &&, and, is_array(), etc. sind erlaubt.

Mit den WEBSALE {if}-Bedingungen können Sie die Ausgabe in der Storefront abhängig von bestimmten Bedingungen variieren. Um zu entscheiden, was ausgegeben wird, können Sie eine Bedingung definieren, die eine Variable überprüft. Eine einfache Bedingung wird durch einen {if}-Block dargestellt, der eine Prüfung enthält. Dieser Block wird nur dann ausgeführt, wenn die Prüfung wahr (true) ist.

Beispiel:

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

In diesem Beispiel prüfen wir, ob die Variable $myProduct.description Inhalt besitzt. Wenn ja, wird ihr Inhalt ausgegeben. Ist das nicht der Fall, wird der alternative Inhalt im else-Block gerendert. Hier verwenden die Kurzbeschreibung.

Zusätzlich zu if und else können auch komplexere Bedingungen definiert, indem {elseif} hinzugefügt wird. Dadurch können mehrere Prüfungen in einer einzigen Bedingung kombiniert werden.

Beispiel: Begrüßung des Besuchers im Onlineshop

• Es wird eine persönliche Begrüßung angezeigt, wenn sich ein Bestandskunde eingeloggt.
• Es wird eine andere Begrüßung angezeigt, wenn sich ein Neukunde eingeloggt.
• Für alle nicht eingeloggte Besucher wird eine allgemeine Nachricht angezeigt.

{{ if $wsAccount.isLoggedIn }}

  <p>Willkommen zurück, {{= $wsAccount.name }}!</p>
  
{{ elseif $wsAccount.isLoggedIn.newUser }}

    <p>Willkommen in unserem Onlineshop, {{= $wsAccount.name }}</p>
    
{{ else }}

    <p>Willkommen! Registrieren Sie sich.</p>
     
{{ /if }}

Beispiel: Komplexe Bedingungen mit Operatoren, z.B. für den Lagerbestand

Sie können unterschiedliche Operatoren verwenden, um komplexe Bedingungen zu erstellen, z. B.:

• > oder < für Vergleiche der Stückzahl eines Produktes

{{ if $myProduct.stock > 0 }}
    <p>Dieses Produkt ist verfügbar.</p>
{{ else }}
    <p>Dieses Produkt nicht verfügbar.</p>
{{ /if }}

Eine vollständige Übersicht der verfügbaren Operatoren und deren Verwendung finden Sie in der Dokumentation der Bedingungen (Conditions).

---

Loops (Schleifen)

Schleifen ermöglichen es, durch ein Array zu iterieren, das mehrere Datensätze (z. B. Produkte) enthält, und automatisch Inhalte für jeden einzelnen Datensatz zu generieren. Damit können Sie wiederholende Strukturen wie Produktlisten, Bildergalerien oder ähnliche Inhalte effizient erstellen.

Eine foreach-Schleife wird mit dem Tag {{ foreach }} geöffnet und mit {{ /foreach }} geschlossen. Der Name der Schleife (die sogenannte Laufvariable) kann frei definiert werden und darf Buchstaben, Zahlen sowie Unterstriche enthalten.

Die foreach-Schleife durchläuft jedes Element des Arrays einmal und führt den eingeschlossenen Codeabschnitt für jedes Element aus. Mit jedem Durchlauf wird das aktuelle Element der Laufvariable zugewiesen.

Beispiel: Produktliste einer Kategorie

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

Die Schleife durchläuft alle Produkte einer Kategorie mit der ID 5678 und erstellt für jedes Produkt ein neues <div>-Element.

Wenn keine Produkte in der Kategorie gefunden werden, wird der foreachelse-Bereich ausgeführt, und eine entsprechende Nachricht angezeigt.

Vollständige Informationen zu den Schleifen finden Sie hier hier.

---

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.