JSON-Schnittstelle
Über die JSON-Schnittstelle können externe Inhalte an beliebigen Stellen in Templates integriert und direkt formatiert werden. Dabei kann es sich um Zusatzinformationen für Produkte, Kategorien oder Kundendaten handeln, die nicht in üblicher Weise über das Warenwirtschaftssystem zur Verfügung gestellt werden können.
Beispiele für den Einsatz der JSON-Schnittstelle:
•zusätzliche Produktinformationen, Bilder und technische Parameter
•Übergabe der Trackingnummer und Anzeige der DHL-Sendungsverfolgung im Kundenkonto (siehe DHL-Sendungsverfolgung)
•gesamtes Hauptmenü mit allen Details, Untermenüs usw.
•Topseller-Struktur und Cross-Links für Kategorien oder Produkte
•PLZ-Listen mit Versandlaufzeiten und europaweite Feiertage für die Lieferzeitberechnung
•Trusted-Shops-Bewertungen
•Inhalte aus einem CMS integrieren
•...
Die externen Daten werden als Datei im JSON-Format auf einem separaten FTP-Server gespeichert. Mit entsprechenden Tags werden die Daten dann in den Shop übertragen und ausgegeben.
Die Verarbeitung von JSON-Daten, die nicht als Datei auf dem FTP-Server vorliegen, ist ebenso möglich. Diese sogenannten "internen" JSON-Daten werden von externen Systemen wie z. B. Zahlungs- oder Versanddienstleistern an das Shopsystem gesendet. Siehe unten Kapitel 6 Laden von intern vorliegenden JSON-Daten.
Darüber hinaus können nicht nur JSON-Daten empfangen, sondern auch beliebige (Shop-)Daten in JSON-Objekte umgewandelt werden. Mit WEBSALE V8s ist es möglich, neue JSON-Daten zu erstellen, bestehende zu verändern und diese dann z. B. per AJAX, Javascript oder als E-Mail etc. beliebig weiterzuverarbeiten. Für die Weitergabe der JSON-Daten an externe Systeme eignet sich die Schnittstelle Asynchronous-Server-Side-Events (ASSE).
Code-Beispiele zur JSON-Schnittstelle finden Sie im Bereich Anwendungsbeispiele: JSON-Schnittstelle Beispiele
1 Freischaltung und separater FTP-Zugang
2 Ordnerstruktur des FTP-Verzeichnisses
3 Anmerkungen zum JSON-Datenformat
5 JSON-Daten neu erstellen und modifizieren
6 Laden von intern vorliegenden JSON-Daten
1 Freischaltung und separater FTP-Zugang
Setzen Sie sich bitte mit Ihrem WEBSALE-Ansprechpartner in Verbindung und lassen Sie die JSON-Schnittstelle für Ihren Shop freischalten. Sie erhalten dann einen separaten FTP-Zugang (Server, Benutzername und Passwort) für das Hochladen der externen JSON-Dateien.
Hinweis: |
|
|
Wenn Sie JSON-Daten ausschließlich für Rückgaben von anderen Systemen ("intern") verwenden wollen, ist keine Freischaltung und kein separater FTP-Zugang erforderlich. |
2 Ordnerstruktur des FTP-Verzeichnisses
Das Root-Verzeichnis des neuen FTP-Servers beinhaltet alle JSON-Dateien, die global – also für alle (Sub-)Shops (Master-, Produktiv-, Mobile-Shops usw.) – benötigt werden.
Wollen Sie verschiedene JSON-Dateien für einzelne Subshops verwenden, erstellen Sie für jeden Subshop ein Verzeichnis mit dem Namen der Subshop-ID und übertragen die JSON-Dateien in diese Subshop-Verzeichnisse. Über einen Tag-Parameter wird im Template gesteuert, ob eine JSON-Datei global (Root-Verzeichnis des FTP-Zugangs) oder Subshop-spezifisch geladen wird (siehe 4.1 Laden von JSON-Daten).
Sie können beliebige Unterverzeichnisse erstellen, um Ihre Daten nach Ihren Vorstellungen strukturiert abzulegen. Wir empfehlen aus Performancegründen nicht mehr als 500 JSON-Dateien in einem FTP-Verzeichnis abzulegen, sondern diese auf mehrere Unterverzeichnisse aufzuteilen.
3 Anmerkungen zum JSON-Datenformat
In einer JSON-Datei muss immer entweder genau ein JSON-Objekt oder genau ein Array mit JSON-Objekten enthalten sein. JSON-Dateien müssen UTF-8-kodiert sein. Namen in einem JSON-Objekt dürfen keine Punkte, eckige/runde/geschweifte Klammern, Dollarzeichen oder Tilden enthalten.
Ungültiges JSON-Objekt:
{
"Name": "Wert",
"Name(2.0)": "Wert (2.0)"
}
Gültiges JSON-Objekt:
{
"Name": "Wert",
"Name2": "Wert (2.0)"
}
Aufgrund der systembedingten Tag-Längenbeschränkung von 128 Zeichen sollten die Namen möglichst kurz sein und die Daten in möglichst flachen Hierarchien gespeichert werden.
Der Einsatz von EJD-Tags ist auf allen Template-Seiten möglich. EJD steht für "External JSON Data". Die Tags mit dem Präfix "EJD-" können Tag-in-Tag verwendet werden, im Gegensatz zu den meisten Tags mit dem Präfix "EJD-DA-". EJD-DA steht für "External JSON Data Direct Access".
Die JSON-Schnittstelle benötigt keine Anpassung der Shopkonfiguration shop.config.
4.1 Laden von JSON-Dateien und ID vergeben
Der Zugriff auf JSON-Dateien erfolgt durch das Laden mit dem Tag EJD-LoadData(Typ,Pfad,ID). Im Argument werden 3 Parameter benötigt:
Der erste Parameter Typ gibt an, ob der Zugriff global oder Subshop-spezifisch erfolgen soll (Typ intern siehe 6 Laden von intern vorliegenden JSON-Daten).
Beispiel für eine globale JSON-Datei aus dem FTP-Root-Verzeichnis der JSON-Schnittstelle:
<!-- Laden der JSON-Datei -->
~EJD-LoadData(global,file.json,ID)~
...
Beispiel für eine JSON-Datei aus einem benutzerdefinierten Verzeichnis innerhalb des Verzeichnisses "benutzer" des Shop-FTP-Servers:
<!-- Laden der JSON-Datei -->
~EJD-LoadData(userdir,navigation/grafiken/JSON/file.json,ID)~
...
Beispiel für Subshop-spezifische JSON-Dateien, die in den gleichnamigen FTP-Verzeichnissen liegen (z. B. "/Englisch/file.json" oder "/Schweiz/file.json"):
<!-- Laden der JSON-Datei -->
~EJD-LoadData(subshop,file.json,ID)~
...
Je nach Subshop wird die JSON-Datei aus dem entsprechenden FTP-Verzeichnis geladen. Der Name der JSON-Datei muss dabei in allen Subshop-Verzeichnissen identisch sein.
Der zweite Parameter Pfad ist eine relative Pfadangabe mit dem JSON-Dateinamen zum separaten FTP-Verzeichnis (beim Typ global oder subshop).
Beispiel für eine global geltende JSON-Datei "file.json" aus einem Unter-Unter-Verzeichnis des FTP-Servers der JSON-Schnittstelle:
<!-- Laden der JSON-Datei -->
~EJD-LoadData(global,Unterverzeichnis1/Unterverzeichnis2/file.json,ID)~
...
Der dritte Parameter ID ist ein eindeutiger alphanumerischer Wert, der vom Designer frei vergeben wird. Diese ID wird für die im Template folgenden EJD-Tags benötigt, um auf die geladenen JSON-Daten zuzugreifen, diese weiterzuverarbeiten und auszugeben. In einem Template können mehrere JSON-Dateien parallel geladen werden (siehe Anwendungsbeispiele: Verschränkter Zugriff auf 2 Dateien).
Referenz: EJD-LoadData()
Hinweis: |
|
|
Beachten Sie, dass max. 100 JSON-Dateien gleichzeitig geladen werden können. |
4.2 Optionale Prüfung, ob JSON-Daten geladen sind
Nach dem Laden kann per Klammerung mit EJD-DataOK(ID) optional geprüft werden, ob die Daten erfolgreich geladen und geparst wurden. Als ID muss der dritte Parameter aus dem Tag EJD-LoadData(Typ,Pfad,ID) eingesetzt werden.
~EJD-LoadData(global,file.json,jdat)~
<!-- Prüfung, ob JSON-Daten vorhanden und geladen sind -->
{EJD-DataOK(jdat)}
JSON-Daten OK.
{/EJD-DataOK(jdat)}
{!EJD-DataOK(jdat)}
JSON-Daten konnten nicht geladen werden (Fehlercode: ~EJD-DataOK(jdat)~).
{/!EJD-DataOK(jdat)}
Referenz: EJD-DataOK()
Der Zugriff auf JSON-Daten erfolgt anhand der ID, die beim Laden mit EJD-LoadData(Typ,Pfad,ID) vergeben wurde.
Die Adressierung eines Datenelements erfolgt dann immer anhand des Zugriffspfads (nicht verwechseln mit dem Datei-Pfad aus EJD-LoadData(Typ,Pfad,ID)). Dieser Zugriffspfad wird durch Verkettung der Namen, getrennt durch einen Punkt, gebildet.
Der Zugriff auf Elemente eines Arrays erfolgt durch den nachgestellten Index in eckigen Klammern.
Auf das Root-Element kann durch Angabe eines leeren Pfads zugegriffen werden. Bei den EJD-DA-Tags kann als Pfad auch "_root_" verwendet werden.
Beispiel 1: Zugriff und Ausgabe einzelner Werte mit EJD-DA-Value()
Inhalt der JSON-Datei "<Produktnummer>.json", Subshop-spezifisch gespeichert
{
"Produktname": "Sportlicher Sneaker",
"Produktnummer": "A-1234",
"AdditionalInfo":
{
"Beschreibung": "Moderne Schuhe für jeden Anlass",
"lieferbar": true,
"Crosslinks": [ "A-5678", "B-9876", "C-2323" ],
"Lagerbestand": 42,
"Preis": 59.95
}
}
Beispiele für Zugriffspfade:
Zugriff auf die Produktnummer "A-1234": Produktnummer
Zugriff auf die Beschreibung "Moderne Schuhe für jeden Anlass": AdditionalInfo.Beschreibung
Zugriff auf den zweiten Crosslink "B-9876": AdditionalInfo.Crosslinks[1]
Verwendung im Template:
<!-- Laden der Datei "<Produktnummer>.json", festlegen der ID "jdat" -->
~EJD-LoadData(subshop,$PR-Number$.json,jdat)~
<!-- Prüfung, ob JSON-Daten mit der ID "jdat" vorhanden und geladen sind -->
{EJD-DataOK(jdat)}
<!-- Ausgabe der Produktnummer -->
Produktnummer: ~EJD-DA-Value(Produktnummer,jdat)~<br>
<!-- Ausgabe der Beschreibung -->
Beschreibung: ~EJD-DA-Value(AdditionalInfo.Beschreibung,jdat)~<br>
<!-- Ausgabe des zweiten Crosslinks -->
zweiter Crosslink: ~EJD-DA-Value(AdditionalInfo.Crosslinks[1],jdat)~
{/EJD-DataOK(jdat)}
Ausgabe:
Produktnummer: A-1234
Beschreibung: Moderne Schuhe für jeden Anlass
zweiter Crosslink: B-9876
Referenz: EJD-DA-Value()
Beispiel 2: Schleife über die Einträge eines Arrays, Verwendung der Daten Tag-in-Tag.
Das Beispiel bezieht sich auf die JSON-Datei von oben.
<!-- Laden der Datei "<Produktnummer>.json", festlegen der ID "jdat" -->
~EJD-LoadData(subshop,$PR-Number$.json,jdat)~
<!-- Prüfung, ob JSON-Daten mit der ID "jdat" vorhanden und geladen sind -->
{EJD-DataOK(jdat)}
<!-- Ausgabe der Anzahl von Elementen in einem Array -->
Anzahl der Croslinks: ~EJD-DA-ArrayElements(AdditionalInfo.Crosslinks,jdat)~<br>
<!-- Legt die Anzahl an Schleifendurchläufen fest (Verwendung Tag-in-Tag) -->
~DC-ZeroLoop1_set($EJD-DA-ArrayElements(AdditionalInfo.Crosslinks,jdat)$)~
<!-- Schleife über Crosslinks (Verwendung Tag-in-Tag) -->
{@DC-ZeroLoop1}
Crosslink #~DC-ZeroLoop1_position~: ~EJD-DA-Value(AdditionalInfo.Crosslinks[$DC-ZeroLoop1_position$],jdat)~<br>
{/@DC-ZeroLoop1}
<!-- Festlegen der Anzahl an Nachkommastellen und Ausgabe des Preises -->
~EJD-SetRealOutputFormat(4)~
Preis: ~EJD-DA-Value(AdditionalInfo.Preis,jdat)~<br>
{/EJD-DataOK(jdat)}
Ausgabe:
Anzahl der Crosslinks: 3
Crosslink #1: A-5678
Crosslink #2: B-9876
Crosslink #3: C-2323
Preis: 59.9500
Referenz: EJD-DA-ArrayElements()
Referenz: DC-ZeroLoop1...3_set()
Referenz: DC-ZeroLoop1...3
Referenz: DC-ZeroLoop1...3_position
Referenz: EJD-SetRealOutputFormat()
4.4 ID standardmäßig setzen (optional)
Um die ID, die mit EJD-LoadData(Typ,Pfad,ID) gesetzt wurde, nicht ständig in den folgenden Tag-Parametern wiederholen zu müssen, kann mit dem Tag EJD-SetUseID(ID) die ID für die im Template folgenden EJD-DA-Tags standardmäßig gesetzt werden. Dies vereinfacht den Code, wenn generell nur eine JSON-Datei verwendet werden soll. Die ID lässt sich aber auch mehrfach wieder überschreiben.
Ausnahme: Beachten Sie, dass bei der Prüfung mit dem Tag EJD-DataOK(ID) die ID zwingend benötigt wird.
~EJD-LoadData(subshop,file.json,jdat)~
{EJD-DataOK(jdat)} <!-- EJD-DataOK benötigt immer die ID "jdat" als Parameter -->
~EJD-SetUseID(jdat)~ <!-- die ID "jdat" wird als Standard-ID gesetzt -->
Beschreibung: ~EJD-DA-Value(AdditionalInfo.Beschreibung)~ <!-- hier wird die ID "jdat" nicht mehr benötigt -->
{/EJD-DataOK(jdat)}
Referenz: EJD-SetUseID()
4.5 Weiterverwenden der JSON-Daten in anderen Tags
Da die EJD-DA-Tags (External-JSON-Data-Direct-Access) mit Parametern (Zugriffspfad und ID) verwendet werden, ist eine direkte Tag-in-Tag-Verwendung in Kombination mit anderen Tags (z .B. DC-Tags) nicht möglich.
Um dieses Problem zu umgehen, wird bei der Verwendung eines EJD-DA-Tags der Wert bzw. Name vorübergehend vom Shop-System gespeichert ("berührt"). Mit den Tags EJD-LastValueAccessed bzw. EJD-LastNameAccessed kann dann auf den jeweils zuletzt "berührten" Wert bzw. Namen zugegriffen werden.
Beispiel: Inhalt der JSON-Datei "<Produktnummer>.json", Subshop-spezifisch gespeichert
{
"Produktname": "Sportlicher Sneaker",
"Produktnummer": "A-1234",
"AdditionalInfo":
{
"Beschreibung": "Moderne Schuhe für jeden Anlass",
"lieferbar": true,
"Crosslinks": [ "A-5678", "B-9876", "C-2323" ],
"Lagerbestand": 42,
"Preis": 59.95
}
}
Verwendung im Template: Zugriff auf einzelne Elemente, Schleife über die Einträge eines Arrays, Verwendung der Daten Tag-in-Tag
<!-- Laden der Datei, setzen der StandardID -->
~EJD-LoadData(subshop,$PR-Number$.json,jdat)~
{EJD-DataOK(jdat)}
~EJD-SetUseID(jdat)~
<!-- Direkter Zugriff ohne ID auf den Wert der Beschreibung -->
Beschreibung: ~EJD-DA-Value(AdditionalInfo.Beschreibung)~<br>
<!-- Zugriff auf das Array der Crosslinks, Ausgabe der Anzahl der Crosslinks, gleichzeitig wird dieser Wert "berührt" -->
Anzahl der Crosslinks: ~EJD-DA-ArrayElements(AdditionalInfo.Crosslinks)~<br>
<!-- Loop über Crosslinks, Verwendung mit Tag-in-Tag -->
<!-- Durch EJD-LastValueAccessed wird der zuletzt "berührte" Wert verwendet. In diesem Beispiel "3", die Anzahl der Array-Elemente -->
~DC-ZeroLoop1_set($EJD-LastValueAccessed$)~
{@DC-ZeroLoop1}
Crosslink #~DC-ZeroLoop1_position~: ~EJD-DA-Value(AdditionalInfo.Crosslinks[$DC-ZeroLoop1_position$])~<br>
<!-- Oder alternativ mit Verwendung eines DC-FP-Tags -->
<!--
~DC-FP1_set(AdditionalInfo.Crosslinks[)~
~DC-FP1_append($DC-ZeroLoop1_position$)~
~DC-FP1_append(])~
Crosslink #~DC-ZeroLoop1_position~: ~EJD-DA-Value($DC-FP1$)~<br>
-->
{/@DC-ZeroLoop1}
{/EJD-DataOK(jdat)}
Ausgabe:
Beschreibung: Moderne Schuhe für jeden Anlass
Anzahl der Crosslinks: 3
Crosslink #1: A-5678
Crosslink #2: B-9876
Crosslink #3: C-2323
Referenz: EJD-LastValueAccessed
Referenz: EJD-LastNameAccessed
Mit folgenden Tags kann auch direkt der Name, der Wert oder die Anzahl der Array-Elemente "berührt" (zwischengespeichert) werden.
Referenz: EJD-DA-TouchName()
Referenz: EJD-DA-TouchValue()
Referenz: EJD-DA-TouchArrayElements()
Mit verschiedenen Bereichs-Tags "EJD-DA-Is..." lässt sich die Art der Werte prüfen. Gleichzeitig wird dabei der Wert des JSON-Elements "berührt", um mit EJD-LastValueAccessed weiter verarbeitet zu werden.
Folgendes Beispiel bezieht sich auf die obige JSON-Datei und prüft, ob der Wert im Element "lieferbar" wirklich "true" ist:
...
{EJD-DA-IsTrue(AdditionalInfo.lieferbar,jdat)}
Der Wert ist "true".
{/EJD-DA-IsTrue(AdditionalInfo.lieferbar,jdat)}
...
Referenz: EJD-DA-IsTrue()
Referenz: EJD-DA-IsFalse()
Referenz: EJD-DA-IsNull()
Referenz: EJD-DA-IsNumber()
Referenz: EJD-DA-IsObject()
Referenz: EJD-DA-IsReal()
Referenz: EJD-DA-IsString()
Referenz: EJD-DA-IsArray()
Mit dem Tag EJD-DA-NameExists() können Sie prüfen, ob in den JSON-Daten ein Element mit dem im Zugriffspfad angegebenen Namen existiert. Dieser Name wird zusätzlich "berührt", um mit EJD-LastNameAccessed weiter verarbeitet zu werden.
...
{EJD-DA-NameExists(AdditionalInfo.Crosslinks,jdat)} <!-- Der Name des Elements wird berührt -->
Es existiert ein JSON-Element mit diesem Namen.
~EJD-LastNameAccessed~ c <!-- Ausgabe: "Crosslinks" -->
{/EJD-DA-NameExists(AdditionalInfo.Crosslinks,jdat)}
...
Referenz: EJD-DA-NameExists()
4.7 Iterieren über JSON-Elemente
Um über mehrere JSON-Elemente zu iterieren, steht das Tag EJD-ElementIterator(Pfad,ID) zur Verfügung.
Das Schleifen-Tag wiederholt den Code für alle vorhanden Elemente. Das Einzel-Tag gibt den Namen des im Zugriffspfad angegebenen JSON-Elements aus.
Beispiel: Ausgabe einer Verkaufsstatistik mit 4 "Items"
JSON-Datei "D200299.json", global gespeichert:
{
"Customer":"D200299",
"Items": {
"001119090":{
"Sales CY":11,
"Sales PY":174
},
"001129090":{
"Sales CY":76,
"Sales PY":650
},
"001169090":{
"Sales CY":5,
"Sales PY":206,
"OrderBacklog":1
},
"001189090":{
"OrderBacklog":1
}
}
}
Verwendung im Template:
~EJD-LoadData(global,D200299.json,bezuege)~
{EJD-DataOK(bezuege)}
~EJD-SetUseID(bezuege)~
Bezüge<br>
{@EJD-ElementIterator(Items)}
Artikel: ~EJD-ElementIterator~
Letztes Jahr: ~EJD-DA-Value(Items.$EJD-ElementIterator$.Sales PY)~
Dieses Jahr: ~EJD-DA-Value(Items.$EJD-ElementIterator$.Sales CY)~
Auftragsbestand: ~EJD-DA-Value(Items.$EJD-ElementIterator$.OrderBacklog)~<br>
{/@EJD-ElementIterator(Items)}
{/EJD-DataOK(bezuege)}
Ausgabe:
Bezüge
Artikel: 001119090 Letztes Jahr: 174 Dieses Jahr: 11 Auftragsbestand:
Artikel: 001129090 Letztes Jahr: 650 Dieses Jahr: 76 Auftragsbestand:
Artikel: 001169090 Letztes Jahr: 206 Dieses Jahr: 5 Auftragsbestand: 1
Artikel: 001189090 Letztes Jahr: Dieses Jahr: Auftragsbestand: 1
Referenz: EJD-ElementIterator()
Ein weiteres Beispiel für EJD-ElementIterator befindet sich unter Anwendungsbeispiele:
Anwendungsbeispiele: JSON-Schnittstelle-Beispiele: EJD-ElementIterator
5. JSON-Daten neu erstellen und modifizieren
Diese Funktion ermöglicht es, JSON-Daten aus dem Shop heraus neu zu erstellen und auszugeben. Aber auch bestehende JSON-Daten, die global, Subshop-spezifisch oder intern mit EJD-LoadData geladen wurden, können bearbeitet und dann mit EJD-RawDataOutput ausgegeben werden.
Es gelten folgende Regeln:
▪Wenn das Element mit dem angegebenen Zugriffspfad bereits existiert, wird das Element überschrieben.
▪Wenn das Element mit dem angegebenen Zugriffspfad noch nicht existiert, wird ein neues angelegt.
▪Es kann immer nur ein Element/Objekt pro Aufruf bearbeitet/angelegt werden (verschachtelte Hierarchie siehe unten 5.3 Verschachtelte JSON-Daten erstellen).
5.1 JSON-Daten erstellen und ausgeben
Mit dem Tag EJD-CreateNewData(ID) erzeugen Sie ein neues, leeres JSON-Objekt. Vergeben Sie als Parameter eine eindeutige ID, die (ähnlich wie bei EJD-LoadData) für die folgenden Tags benötigt wird.
Je nach Art der Werte in den Name-Value-Paaren stehen unterschiedliche Einzel-Tags zur Verfügung, jeweils mit den Parametern Name, Wert und ID (siehe folgendes Beispiel). Die Ausgabe der neuen JSON-Daten erfolgt dann mit EJD-RawDataOutput().
Beispiel für das Erstellen von einfachen JSON-Elementen:
<!-- leeres JSON-Objekt "{}" erzeugen -->
~EJD-CreateNewData(jdat)~
{EJD-DataOK(jdat)}
~EJD-DA-SetStringValue(testString,abc,jdat)~
~EJD-DA-SetNumberValue(testInteger,1,jdat)~
~EJD-DA-SetRealValue(testReal,1.23,jdat)~
~EJD-DA-SetToTrue(testTrue,jdat)~
~EJD-DA-SetToFalse(testFalse,jdat)~
~EJD-DA-SetToNull(testNull,jdat)~
<!-- JSON-Daten ausgeben -->
~EJD-RawDataOutput(jdat)~
{/EJD-DataOK(jdat)}
Ausgabe:
{ "testString": "abc", "testInteger": 1, "testReal": 1.23, "testTrue": true, "testFalse": false, "testNull": null }
Referenz: EJD-CreateNewData()
Referenz: EJD-DA-SetStringValue()
Referenz: EJD-DA-SetNumberValue()
Referenz: EJD-DA-SetRealValue()
Referenz: EJD-DA-SetToTrue()
Referenz: EJD-DA-SetToFalse()
Referenz: EJD-DA-SetToNull()
Referenz: EJD-RawDataOutput()
5.2 Array mit mehreren Werten erstellen
Mit dem Tag EJD-DA-SetToEmptyArray() wird ein leeres Array erstellt, das dann mit dem Tag EJD-DA-ArrayExtend() mehrmals erweitert wird.
Beispiel 1: Erstellen eines Arrays mit 3 Werten (Variante 1: abwechselnd Array erweitern und Wert vergeben)
~EJD-CreateNewData(jdat)~
{EJD-DataOK(jdat)}
~EJD-DA-SetToEmptyArray(Crosslinks,jdat)~
~EJD-DA-ArrayExtend(Crosslinks,jdat)~
~EJD-DA-SetStringValue(Crosslinks[0],A-12345,jdat)~
~EJD-DA-ArrayExtend(Crosslinks,jdat)~
~EJD-DA-SetStringValue(Crosslinks[1],A-2323,jdat)~
~EJD-DA-ArrayExtend(Crosslinks,jdat)~
~EJD-DA-SetStringValue(Crosslinks[2],B-5678,jdat)~
~EJD-RawDataOutput(jdat)~
{/EJD-DataOK(jdat)}
Ausgabe:
{ "Crosslinks": [ "A-12345", "A-2323", "B-5678" ] }
Referenz: EJD-DA-SetToEmptyArray()
Referenz: EJD-DA-ArrayExtend()
Zum Löschen eines JSON-Elements verwenden Sie das Tag EJD-DA-DeleteElement().
...
<!-- zweites Array-Element löschen -->
~EJD-DA-DeleteElement(Crosslinks[1],jdat)~
...
Ausgabe:
{ "Crosslinks": [ "A-12345", "B-5678" ] }
Referenz: EJD-DA-DeleteElement()
Beispiel 2: Erstellen eines Arrays als Root-Element der JSON-Daten (Variante 2: zuerst Array erweitern und dann die Werte setzen)
~EJD-CreateNewData(jdat)~
{EJD-DataOK(jdat)}
~EJD-DA-SetToEmptyArray(_root_,jdat)~
~EJD-DA-ArrayExtend(_root_,jdat)~
~EJD-DA-ArrayExtend(_root_,jdat)~
~EJD-DA-ArrayExtend(_root_,jdat)~
~EJD-DA-SetStringValue(_root_[0],A-12345,jdat)~
~EJD-DA-SetStringValue(_root_[1],A-2323,jdat)~
~EJD-DA-SetStringValue(_root_[2],B-5678,jdat)~
~EJD-RawDataOutput(jdat)~
{/EJD-DataOK(jdat)}
Ausgabe:
[ "A-12345", "A-2323", "B-5678" ]
5.3 Verschachtelte JSON-Daten erstellen
Das folgende Beispiel zeigt JSON-Daten mit mehreren Hierarchien (Unter-Objekte/Knoten):
~EJD-CreateNewData(jdat)~
{EJD-DataOK(jdat)}
~EJD-DA-SetToEmptyObject(Data,jdat)~
~EJD-DA-SetToEmptyObject(Data.Images,jdat)~
~EJD-DA-SetStringValue(Data.Images.Image small,img-5678.jpg,jdat)~
~EJD-DA-SetStringValue(Data.Images.Image big,img-1234.jpg,jdat)~
~EJD-DA-SetToEmptyArray(Data.Crosslinks,jdat)~
~EJD-DA-ArrayExtend(Data.Crosslinks,jdat)~
~EJD-DA-ArrayExtend(Data.Crosslinks,jdat)~
~EJD-DA-SetStringValue(Data.Crosslinks[0],A-2256,jdat)~
~EJD-DA-SetStringValue(Data.Crosslinks[1],B-2323,jdat)~
~EJD-RawDataOutput(jdat)~
{/EJD-DataOK(jdat)}
Ausgabe:
{ "Data": { "Images": { "Image small": "img-5678.jpg", "Image big": "img-1234.jpg" }, "Crosslinks": [ "A-2256", "B-2323" ] } }
Referenz: EJD-DA-SetToEmptyObject()
5.4 Prüfen der neu erstellten oder veränderten JSON-Daten (optional)
Nach der Modifizierung kann per Klammerung geprüft werden, ob diese erfolgreich war.
Da die Fehler-Ausgabe auch nach einer weiteren, erfolgreichen Modifizierung der JSON-Daten nicht automatisch wieder zurückgesetzt wird, muss dies explizit mit dem Einzel-Tag EJD-ResetModificationOK im Template erfolgen.
~EJD-CreateNewData(jdat)~
{EJD-DataOK(jdat)}
...
...
{EJD-ModificationOK}
JSON-Daten erfolgreich modifiziert
{/EJD-ModificationOK}
{!EJD-ModificationOK}
Fehler: ~EJD-ModificationOK~
{/!EJD-ModificationOK}
~EJD-ResetModificationOK~
...
{/EJD-DataOK(jdat)}
Referenz: EJD-ModificationOK
Referenz: EJD-ResetModificationOK
6 Laden von intern vorliegenden JSON-Daten
Neben den JSON-Dateien aus dem separaten FTP-Verzeichnis (bei EJD-LoadData Typ global oder subshop) können auch JSON-Daten, die von WEBSALE oder externen Dienstleistern "on the fly" an den Shop gesendet werden, geladen, manipuliert und ausgegeben werden.
Hinweis: |
|
|
Beim Typ "intern" handelt es sich um JSON-Daten, die vom WEBSALE-Shopsystem oder externen Dienstleistern zur Verfügung gestellt werden (z. B. Antworten der Zahlungsanbieter oder Daten für die Sendungsverfolgung). Unter Umständen ist daher nicht bekannt, welche Daten genau geliefert werden. Diese internen JSON-Daten können nach dem Setzen in die Schnittstelle und dem Laden mit EJD-RawDataOutput() komplett ausgegeben werden. Beim Typ "global" oder "subshop" werden die Daten vom Frontend-Entwickler/Designer selbst angeliefert. Diese JSON-Dateien können Sie sich direkt über den separaten FTP-Zugang der JSON-Schnittstelle ansehen (siehe oben). |
Freischaltung/Aktivierung
Es ist keine Freischaltung seitens WEBSALE nötig, wenn Sie JSON-Daten ausschließlich für Rückgaben von anderen Systemen ("intern") verwenden wollen.
6.1 Interne JSON-Daten in die Schnittstelle setzen
Je nach Anwendungsfall müssen vor dem Laden die übergebenen Daten mit den Tags EJD-SetRawDataInput() oder EJD-SetRawDataHexCodeInput() ausgewählt und in die JSON-Schnittstelle gesetzt werden.
Die Bezeichnung der JSON-Daten, die für das Argument benötigt werden, erfahren Sie von den externen Dienstleistern oder von WEBSALE.
Beispiele:
<!-- JSON-Response vom Aufruf "getOrderDetails" bei Kauf auf Rechnung über PayPal Checkout -->
~EJD-SetRawDataInput($PPC-OrderDetailsRawResponse$)~
<!-- JSON-Response des PaymentToken von Paymorrow -->
~EJD-SetRawDataInput($PAYMORROW-JSONResponseGetPaymentToken$)~
<!-- JSON-Response der Sendungsverfolgung durch "SHIPTRACK-Get()" -->
~EJD-SetRawDataInput($SHIPTRACK-JSONResult$)~
Referenz: EJD-SetRawDataInput()
Referenz: EJD-SetRawDataHexCodedInput()
6.2 Interne JSON-Daten laden und ID vergeben
Analog zum Laden von globalen oder Subshop-spezifischen JSON-Dateien wird das Tag EJD-LoadData(Typ, Pfad,ID) verwendet.
Der erste Parameter Typ lautet nun intern, der zweite Parameter Pfad ist bei internen JSON-Daten eine technische Bezeichnung, die vom Anwendungsfall abhängt. Eine Liste der technischen Bezeichnungen finden Sie in der Tag-Beschreibung von EJD-LoadData().
Die ID ist ein eindeutiger alphanumerischer Wert, der vom Designer frei vergeben wird. Diese ID wird für die im Template folgenden EJD-Tags benötigt, um auf die geladenen JSON-Daten zuzugreifen, diese weiterzuverarbeiten und auszugeben.
<!-- JSON-Daten in die Schnittstelle setzen -->
~EJD-SetRawDataInput($XYZ-technischeBezeichnung-JSON$)~
<!-- Laden von internen JSON-Daten, ID "jdat" vergeben -->
~EJD-LoadData(intern,rawdatainput,jdat)~
<!-- interne JSON-Daten ausgeben -->
~EJD-RawDataOutput(jdat)~...
Referenz: EJD-LoadData()
Referenz: EJD-RawDataOutput()
Für die hreflang-Attribute wird das "in-die-Schnittstelle-setzen" (siehe 6.1) nicht benötigt. Diese von WEBSALE stammenden, internen JSON-Daten lassen sich direkt mit EJD-LoadData laden und ausgeben:
<!-- Laden von internen JSON-Daten, ID "href" vergeben -->
~EJD-LoadData(intern,hreflang-prod-$PR-ProdIndex$,href)~
<!-- interne JSON-Daten ausgeben -->
~EJD-RawDataOutput(href)~
...
Wegweiser: hreflang-Attribut
Die weitere Verarbeitung, der Zugriff auf einzelne JSON-Elemente und die Ausgabe im Shop erfolgt wie oben beschrieben (siehe ab 4.2 Optionale Prüfung, ob JSON-Daten geladen sind)
Weitere Code-Beispiele zur JSON-Schnittstelle finden Sie im Kapitel Anwendungsbeispiele: JSON-Schnittstelle Beispiele