Mit Optionen definieren Sie im Template Einstellungen fest, die anschließend im Admin-Interface pflegbar sind, ohne dass das Template erneut angepasst werden muss. So können Sie beispielsweise steuern, ob das Icon einer Zahlungsart im Footer angezeigt wird.
Eine Option durchläuft immer denselben Ablauf: definieren → im Admin pflegen → im Template lesen. Diese Seite beschreibt das Definieren. Das Auslesen der gepflegten Werte übernimmt das Modul $wsOptions.
Grundlagen
Schreibweise
Eine Option wird mit der Anweisung option, einem eindeutigen Namen und den Angaben hinter with definiert:
{{ option "stringValue" with {"type": "String"} }}
stringValue vom Typ String. Im Admin-Interface entsteht dadurch ein Textfeld; der dort eingetragene Wert wird im Template über $wsOptions.get("stringValue") ausgegeben. Jede Option hat genau einen Typ, der die Eingabemaske im Admin-Interface bestimmt.
Eindeutigkeit und Lebenszyklus
Jede Option darf nur einmal definiert werden. Werden zwei Optionen mit demselben Namen in unterschiedlichen Templates oder an unterschiedlichen Stellen desselben Templates definiert, entsteht ein Fehler.
Die definierten Optionen stehen zur Verfügung, nachdem die Templates erfolgreich kompiliert wurden. Werden Optionen aus dem Template entfernt, verschwinden sie erst nach einer erneuten Kompilierung aus dem Admin-Interface.
Nur statische Angaben
Bei der Definition sind ausschließlich statische Angaben möglich, es dürfen beispielsweise keine Variablen, Operatoren oder Funktionen verwendet werden. Die folgenden Beispiele sind daher nicht möglich:
| Beispiel | Warum ungültig |
|---|
{{ var $name = "invalidOption1"; option $name with {"type": "String" }} | Variablen sind als Optionsname nicht erlaubt. |
{{ var $type = "String"; option "invalidOption2" with {"type": $type }} | Variablen sind auch in den Angaben nicht erlaubt. |
{{ option "invalidOption3" with {"type": "Str" + "ing" }} | Operatoren sind nicht erlaubt. |
{{ option upper("invalidOption4") with {"type": "String" }} | Funktionen sind nicht erlaubt. |
Anzeigelabel und Beschreibung
Anzeigelabel und Beschreibung einzelner Optionen lassen sich im Admin-Interface bzw. über die REST-API bearbeiten. Sie dienen ausschließlich der Anzeige und haben keine weitere Funktion.
Optionstypen
Jede Option hat einen Typ, der die Eingabemaske im Admin-Interface bestimmt.
String
Wird im Admin-Interface als Textfeld dargestellt.
Beispiel
{{ option "freeShippingHint" with {"type": "String"} }}
$wsOptions.get("freeShippingHint") anschließend genau diesen Text aus.
Bool
Wird im Admin-Interface als An/Aus-Schalter dargestellt. Geeignet, um beispielsweise ein Verhalten oder ein Anzeigeelement ein- oder auszuschalten.
Beispiel
{{ option "showTrustBadges" with {"type": "Bool"} }}
$wsOptions.get("showTrustBadges") den Wert true, andernfalls false. Passend, um beispielsweise die Trust-Badges im Template gezielt ein- oder auszublenden.
Int
Erwartet eine ganze Zahl. Optional lassen sich über min und max Wertgrenzen festlegen.
Beispiel
{{ option "productsPerRow" with {"type": "Int", "min": 2, "max": 6} }}
4 ein, liefert $wsOptions.get("productsPerRow") den Wert 4 - beispielsweise um vier Produkte pro Reihe anzuzeigen.
Float
Erwartet eine Kommazahl. Wie bei Int lassen sich optional min und max angeben.
Beispiel
{{ option "minRatingForBadge" with {"type": "Float", "min": 0, "max": 5} }}
4.5 ein, liefert $wsOptions.get("minRatingForBadge") diesen Wert, beispielsweise als Mindestbewertung, ab der ein „Top bewertet”-Badge erscheint.
Enum
Erlaubt die Auswahl aus einer vordefinierten Liste. Die erlaubten Werte werden über values festgelegt.
Beispiel
{{ option "teaserLayout" with {"type": "Enum", "values": ["grid", "list", "slider"]} }}
grid, list und slider. Wählt ein Redakteur slider, liefert $wsOptions.get("teaserLayout") den Wert slider, beispielsweise um die Teaser als Slider statt als Raster darzustellen.
Optionen an Konfigurationen binden
Mit attachTo binden Sie eine Option an einen Konfigurationsknoten, z. B. payment.payment für die Zahlungsarten:
{{ option "showPaymentIconInFooter" with {"type": "Bool", "attachTo": "payment.payment"} }}
- Die Einstellung lässt sich im Admin-Interface direkt in der jeweiligen Konfiguration bearbeiten.
- Bei frei erstellbaren Konfigurationen, beispielsweise einer Konfiguration je Zahlungsart, kann die Einstellung pro Knoten unterschiedlich sein. So lässt sie sich etwa bei „Vorkasse” deaktivieren und bei „Google Pay” aktivieren. Den so gepflegten Wert lesen Sie im Template über
$wsOptions.get(name, nodeId) aus, wobei nodeId die ID des Konfigurationsknotens ist.
Konkret: Ist der Schalter im Admin-Interface bei „Vorkasse” aktiviert und bei „Google Pay” nicht, liefert $wsOptions.get("showPaymentIconInFooter", "payment.payment.bill") für den Vorkasse-Knoten true und für den Google-Pay-Knoten false . Das Footer-Icon erscheint also nur bei der Vorkasse.
Die Konfigurationsknoten-ID ist nicht das Feld id innerhalb einer Konfiguration (die „technische ID”). Welche Objekte die korrekte nodeId bereitstellen, ist unter $wsOptions aufgeführt.
Darstellung im Admin-Interface
Über displayOptions.location legen Sie fest, an welcher Stelle der klickbaren Konfigurationsoberflächen im Admin-Interface die Option erscheint:
{{ option "paymentInfoText" with {"type": "String", "attachTo": "payment.payment", "displayOptions": {"location": "payment.content"}} }}
location wirkt nur in Kombination mit attachTo. Ohne passendes attachTo hat die Angabe keinen Effekt.
| Konfiguration | Location | Darstellung |
|---|
payment.payment | payment.image | Im Abschnitt „Bild” der Zahlungsarten-Konfiguration. |
payment.payment | payment.content | Im Abschnitt „Inhalt” der Zahlungsarten-Konfiguration. |
location nicht angegeben, erscheint die Option in einem allgemeinen Abschnitt „Template Optionen” des jeweiligen Konfigurationsknotens.
Werte auslesen
Das Auslesen der gepflegten Optionswerte im Template beschreibt das Modul $wsOptions. Sowohl für globale Optionen als auch für an Konfigurationsknoten gebundene Optionen. 