Zum Hauptinhalt springen
Mit der JSON-Schnittstelle bringt ein Template Daten in den Shop, die nicht aus den Produktdaten stammen: eine Nährwerttabelle je Artikel, Umsatzzahlen für den angemeldeten Kunden, die Antwort eines Zahlungsdienstleisters. Umgekehrt baut sie auch JSON auf, das der Shop an ein Tracking- oder Fremdsystem weitergibt. Die Tags mit dem Präfix EJD- (External JSON Data) sind der Zugang dazu. Sie decken drei Aufgaben ab. Wegweiser: JSON-Schnittstelle

Der Ablauf

Jeder Zugriff läuft in drei Schritten: laden, prüfen, zugreifen. Die Daten bekommen beim Laden eine frei gewählte ID, über die alle weiteren Tags sie wiederfinden.
Mehrere JSON-Daten lassen sich gleichzeitig geladen halten. Die ID hält sie auseinander. Deshalb trägt jedes Zugriffs-Tag die ID als letzten Parameter, und EJD-SetUseID() erspart es, sie jedes Mal zu wiederholen. Die Beispiele auf dieser Seite beziehen sich auf diese Datei:

Daten laden

Der Typ

Beim Typ subshop wählt der Shop das passende Unterverzeichnis selbst. Im englischen Subshop lädt ~EJD-LoadData(subshop,file.json,jdat)~ also die Datei /English/file.json. Dieselbe Zeile im Template funktioniert damit in allen Subshops.

Der Pfad beim Typ “intern”

Beim Typ intern steht im zweiten Parameter keine Datei, sondern die technische Bezeichnung der bereitliegenden Daten.
Daneben stellen einzelne Module ihre Antworten bereit. Weitere Bezeichnungen kommen mit neuen Modulen hinzu und sind bei der WEBSALE AG oder beim jeweiligen Dienstleister zu erfragen. Bei internen Daten wissen Sie oft nicht im Voraus, welche Felder geliefert werden. EJD-RawDataOutput() gibt den kompletten Datensatz aus und ist der schnellste Weg, sich einen Überblick zu verschaffen.

Prüfen, ob das Laden geklappt hat

EJD-DataOK() klammert auf den Erfolg. Als Einzel-Tag gibt es den Fehlercode aus.
EJD-DataOK() braucht die ID immer ausgeschrieben. EJD-SetUseID() wirkt hier nicht, denn es steht ja selbst erst innerhalb der Klammerung.

Die ID einmal setzen

EJD-SetUseID() legt die ID fest, die alle folgenden Zugriffs-Tags verwenden, wenn sie selbst keine mitbekommen.
Bei allen Zugriffs-, Prüf- und Änderungs-Tags ist die ID deshalb optional. Sie ist nur dann nötig, wenn keine Standard-ID gesetzt ist oder wenn Sie zwischen mehreren Datensätzen wechseln. Die Standard-ID lässt sich beliebig oft neu setzen. Bei mehreren gleichzeitig geladenen Datensätzen wechseln Sie damit hin und her.

Der Zugriffspfad

Alle Zugriffs-Tags erwarten als ersten Parameter den Pfad zum Element.
Array-Elemente werden ab 0 gezählt. Das erste Element ist [0]. Deshalb passt DC-ZeroLoopX als Schleife über ein Array besser als DC-LoopX, das ab 1 zählt.

Werte lesen

EJD-DA-ArrayElements() greift als Bereichs-Tag nur, wenn das Element wirklich ein Array und nicht leer ist. Die Klammerung beantwortet damit in einem Schritt die Frage, ob sich eine Schleife überhaupt lohnt.

Den Typ eines Werts prüfen

JSON kennt mehrere Werttypen. Acht Bereichs-Tags prüfen, welcher vorliegt.
Die acht Prüf-Tags sind reine Bereichs-Tags. Als Einzel-Tag geschrieben bleiben sie wirkungslos.
Bei fremden Daten lohnt sich die Typprüfung. Ein Feld, das gestern eine Zahl war und heute null ist, lässt eine ungeprüfte Ausgabe sonst leer.

Werte weiterverwenden

Die Zugriffs-Tags tragen Parameter. Damit lassen sie sich nicht als $…$ in ein anderes Tag schreiben, denn Tag-in-Tag funktioniert nur mit Einzel-Tags ohne eigenes Argument. Deshalb merkt sich der Shop bei jedem Zugriff den angesprochenen Namen und Wert. Zwei parameterlose Tags geben sie wieder aus. EJD-DA-TouchName(), EJD-DA-TouchValue() und EJD-DA-TouchArrayElements() gibt es nur dafür: Sie merken sich etwas, ohne selbst etwas auszugeben.
Ausgabe:
Das ist das Standardmuster für Arrays: Anzahl merken, damit eine Zählschleife aufziehen und die Position als Index einsetzen. DC-ZeroLoopX zählt ab 0 und passt damit genau auf die Array-Indizes. Referenz: DC- (Schleifen)

Über Elemente iterieren

Bei einem Objekt, dessen Schlüssel Sie nicht kennen, hilft keine Zählschleife. EJD-ElementIterator() läuft stattdessen über die Kinder eines Elements und gibt deren Namen aus.
Als Einzel-Tag innerhalb der Schleife gibt EJD-ElementIterator den Namen des aktuellen Elements aus. Weil es dann parameterlos ist, lässt es sich als $EJD-ElementIterator$ in den Zugriffspfad einsetzen. Genau darauf beruht das Muster oben.
Die Schleife lässt sich schachteln, aber nur bis zu einer festen Tiefe von zehn Ebenen. Wird sie überschritten, schreibt der Shop einen kritischen Fehler ins Protokoll und die Schleife läuft nicht an.

Fließkommazahlen ausgeben

EJD-SetRealOutputFormat() legt fest, mit wie vielen Nachkommastellen Fließkommazahlen ausgegeben werden. Zulässig sind 0 bis 6.
Eine Angabe außerhalb von 0 bis 6 macht das Tag ungültig, die bisherige Einstellung bleibt dann bestehen. Die Einstellung gilt ab der Stelle im Template, an der sie gesetzt wird, und für alle geladenen Datensätze.

JSON erzeugen und ändern

EJD-CreateNewData() legt ein leeres JSON-Objekt an, das Sie im Template füllen.
Ausgabe:
Alle diese Tags funktionieren nicht nur auf neu erzeugten Daten, sondern ebenso auf geladenen. Damit lässt sich eine eingelesene Datei im Template anreichern und anschließend weitergeben.
Existiert der Pfad schon, wird der bisherige Wert ersetzt. Existiert er noch nicht, wird er angelegt, sofern das übergeordnete Element vorhanden ist. EJD-DA-ArrayExtend() und EJD-DA-DeleteElement() legen dagegen nichts an: Zeigt ihr Pfad ins Leere, melden sie einen Fehler.Das Wurzelelement lässt sich nur in ein Objekt oder ein Array verwandeln. Jeder Versuch, ihm einen einfachen Wert zu geben, endet mit dem Fehlercode 14.

Ein Array aufbauen

Ausgabe:
Soll das Wurzelelement selbst ein Array sein, geben Sie als Pfad _root_ an: ~EJD-DA-SetToEmptyArray(_root_,jdat)~ ergibt [].

Ein Beispiel aus dem Tracking

Auf der Produktübersichtsseite ein JSON mit Index und Preis aller gezeigten Produkte aufbauen:
Schalten Sie die Preisformatierung ab, bevor Sie einen Preis als Zahl übergeben. Sonst kommt er mit Tausendertrennzeichen und Komma an und wird beim Umwandeln in eine Zahl abgeschnitten.

Prüfen, ob die Änderung geklappt hat

EJD-ModificationOK klammert auf den Erfolg der letzten Änderung und gibt als Einzel-Tag den Fehlercode aus.
Der Fehlercode bleibt stehen, auch wenn die nächste Änderung gelingt. Setzen Sie ihn deshalb nach jeder Prüfung mit EJD-ResetModificationOK zurück, sonst melden alle folgenden Prüfungen denselben alten Fehler.

Rohdaten ein- und ausgeben

Die beiden Eingabe-Tags gehören zusammen mit der jeweils passenden Bezeichnung beim Laden: EJD-SetRawDataInput() mit rawdatainput, EJD-SetRawDataHexCodedInput() mit rawdatahexcodedinput. Vertauscht liefert die Schnittstelle unbrauchbare Daten, weil hexcodierte Zeichen als Klartext gelesen werden oder umgekehrt.EJD-RawDataOutput() gibt die Daten ohne HTML-Kodierung aus. Das ist gewollt, damit gültiges JSON entsteht, macht das Tag aber für fremde Daten gefährlich. Schreiben Sie damit niemals ungeprüfte Fremddaten in den sichtbaren Seiteninhalt. Für die Fehlersuche gehört die Ausgabe in einen HTML-Kommentar, im Livebetrieb in ein Skript-Element oder in eine Schnittstelle.

Ein JSON Web Token erzeugen

EJD-GenerateJWT() signiert die geladenen JSON-Daten und gibt sie als JSON Web Token aus. Damit lassen sich Daten fälschungssicher an ein Fremdsystem übergeben.
Das Geheimnis für die Signatur ist derselbe Konfigurationseintrag, den auch DC-FPX_hash() und DC-FPX_encrypt() verwenden. Referenz: Abschnitt <[DesignControl](/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/grundlagen-und-technik#designcontrol)>

Die Tags im Überblick

Zulässig sind alle Tags auf allen Templates. Die ID ist bei allen Tags optional, sobald sie mit EJD-SetUseID() gesetzt wurde, mit Ausnahme von EJD-DataOK() und EJD-RawDataOutput().

Verwandte Themen