/
$wsExternalData - Externe Daten

$wsExternalData - Externe Daten

  • Verified

    • Das Modul $wsExternalData ermöglicht den Zugriff auf dateibasierte externe Daten, die im shopeigenen S3 liegen. Typische Anwendungsfälle sind Zusatzinformationen, die nicht aus den Standard-Shopdaten stammen (z. B. projektbezogene JSON-Dateien aus einem PIM oder Inhalte aus WEBSALE-Komponenten wie der WEBSALE Strapi-Instanz).

    Allgemeine Informationen zur externen Datenschnittstelle finden Sie hier.

    Inhaltsverzeichnis

    Templates

    Externe Daten können über $wsExternalData in jedes beliebige Template geladen und dort verarbeitet bzw. ausgegeben werden. Je nach Use Case kann dies z. B. auf Produktdetailseiten (Zusatzdaten), Kategorieseiten (Zusatzlisten) oder Content-Seiten (Startseite, Impressum etc.) erfolgen.

    Datenübersicht & Zugriff

    Datenquellen (source)

    Über die Option source wird festgelegt, aus welchem S3-Bereich gelesen wird:

    • source: "user" (Default) → Bucket external-data

    • source: "system" → Bucket system

    Im Bucket system liegen ausschließlich Dateien von WEBSALE-Komponenten, während im Bucket external-data die eigenen Projekt-Dateien liegen.

    Mehr Informationen dazu siehe Externe Datenschnittstelle (Datei-/Bucket-basiert)

     

    Dateien aus einem Verzeichnis lesen (read)

    Anders als bei Modulen mit festen Maps besteht die Datenübersicht bzw. der Datenzugriff hier vor allem darin, zu wissen, welche Dateien in einem Verzeichnis vorhanden sind.

    Ohne direkten S3-Zugriff ist read() die passende Methode, um sich im Template einen Überblick über Dateien und Verzeichnisse zu verschaffen. Mit read() werden die Dateinamen eines Verzeichnisses geladen – nicht der Dateiinhalt.

    Der Zusatzparameter glob dient dabei als Filter. Damit lässt sich festlegen, welche Dateinamen zurückgegeben werden (z. B. nur product_*.json oder alle *.json).

    Die Funktion ist auch hilfreich, wenn im Template dynamisch ermittelt werden soll, welche Dateien in einem Verzeichnis vorhanden sind (z. B. für CMS-/Strapi-Seiten), um diese anschließend im Template aufzulisten und deren Inhalte dynamisch weiterzuverarbeiten.

    Anschließend können einzelne Dateien gezielt mit load() geladen werden.

    Syntax

    $wsExternalData.read(path, options)

    • path (String): Verzeichnis-Pfad (z. B. products/)

    • options (Map, optional):

      • source (String): user (Default) oder system

      • recursive (Boolean): rekursiv durch Unterordner, Default false

      • glob (String): Filter-Pattern (z. B. product_*.json)

     

    Die Rückgabe ist eine Liste mit den gefundenen Dateien (unter Berücksichtigung der Optionen). Zum Laden des Inhalts wird anschließend load() verwendet. Ein Praxisbeispiel ist hier zu finden.

     

    Einzelne Datei laden (load)

    Mit load() wird eine einzelne JSON-Datei geladen, damit deren Inhalte anschließend im Template verwendet und ausgegeben werden können.

    Syntax

    $wsExternalData.load(file, options)

    • file (String): Pfad zur Datei innerhalb der gewählten Quelle (z. B. products/product_123.json)

    • options (Map):

      • type (String, Pflicht): Dateiformat, aktuell nur json

      • source (String, optional): user (Default) oder system

      • maxDepth (Integer, optional): maximale Verschachtelungstiefe, Default 7

     

    Die Rückgabe ist eine Map oder Liste – abhängig von der Struktur der JSON-Datei. Wenn das Laden fehlschlägt, steht die Fehlerbeschreibung über getLastError() zur Verfügung. Ein Praxisbeispiel ist hier zu finden.

    Debug-Hinweis:
    Um die geladene Struktur zu prüfen, kann die Ausgabe formatiert per | json erfolgen (auskommentiert, damit nichts im Frontend erscheint):

    <!-- {{= $wsExternalData.load("products/product_123.json", { type: "json" }) | json }} -->

     

    Fehlerbehandlung (getLastError)

    Wenn beim Laden/Lesen ein Fehler auftritt (z. B. Datei nicht vorhanden, S3 nicht erreichbar), kann die Fehlermeldung als String abgefragt werden.

    Syntax

    $wsExternalData.getLastError()

     

    Beispiele für den Datenzugriff

     

    Dateien aus einem Verzeichnis lesen (inkl. glob)

    Mit $wsExternalData.read() werden Dateinamen aus einem Verzeichnis geladen (nicht der Dateiinhalt). Das ist nützlich, wenn mehrere Dateien (z.B. Produktlisten oder Konfigurationen) strukturiert abgelegt sind und anschließend iteriert werden sollen.

    Der Parameter glob dient dabei als Filter mit dem festgelegt werden kann, welche Dateinamen zurückgegeben werden (z.B. nur product_*.json oder alle *.json).

    In diesem Beispiel werden aus dem Verzeichnis json/Deutsch/ (Quelle: system) alle Dateien geladen, die auf .json enden. Die Rückgabe ist eine Liste von Dateinamen - es wird nur die Verzeichnisstruktur gelesen, nicht der Inhalt.

    {{ var $cCMSFiles = $wsExternalData.read(["json/Deutsch/"] | join, {"source":"system","glob":"*.json","recursive":false}) }} {{ if $cCMSFiles }} <ul> {{ foreach $cCMSFile in $cCMSFiles }} <li>{{= $cCMSFile }}</li> {{ /foreach }} </ul> {{ /if }}

     

    JSON-Datei laden (Default: external-data)

    Mit $wsExternalData.load()werden externe, dateibasierte Daten aus dem shop-eigenen S3 geladen. Typische Anwendungsfälle sind Zusatzinformationen, die nicht aus den Standard-Shopdaten stammen. (z.B. manuell gepflegte Ergänzungen).

    In diesem Beispiel wird die Datei products/product_123.json geladen. Da keine source-Option gesetzt ist, wird die Default-Quelle verwendet (mehr Informationen zu den Quellen gibt es hier). Der Pfad ist innerhalb der gewählten Quelle anzugeben - die Datei liegt in der Regel unter external-data/products/product_123.json und dient als Beispiel für Produkt-Zusatzdaten, die im Template weiterverarbeitet oder ausgegeben werden können.

    {{ var $data = $wsExternalData.load("products/product_123.json", { type: "json" }) }} {{ if $data }} {{= $data }} {{ /if }}

    Hinweis: Die direkte Ausgabe {{= data }} ist als schneller Check gedacht. Für Debug-Zwecke ist häufig eine formatierte Ausgabe per | json sinnvoll. Siehe Abschnitt Datenstruktur debuggen.

    JSON-Datei laden (Quelle: system)

    Neben projektbezogenen Dateien aus der Default-Quelle können auch Daten aus der Quelle system geladen werden. Dort liegen Dateien, die von WEBSALE-Komponenten bereitgestellt werden - ein typisches Beispiel sind Strapi-Exporte (z.B. Seiten- oder Content-Strukturen).

    In diesem Beispiel wird eine Startseiten-Definition aus dem system-Bereich geladen (strapi/pages/home.json).

    Die Option source: ”system” sorgt dafür, dass die Datei aus dem entsprechenden system-Bucket gelesen wird.

    {{ var $data = $wsExternalData.load("strapi/pages/home.json", { type: "json", source: "system" }) }} {{ if $data }} {{= $data }} {{ /if }}

     

    Prüfen, ob eine Datei existiert (inkl. Fehlermeldung)

    Wenn beim Laden ein Fehler auftritt (z.B. Datei nicht vorhanden oder Quelle/Bucket nicht erreichbar), kann die letzte Fehlermeldung über $wsExternalData.getLastError() abgefragt werden. Diese Ausgabe ist nicht für Kunden im Frontend gedacht, sondern ausschließlich für die Fehlerbehebung (z.B. im Browser über console.error).

    Das folgende Beispiel lädt eine Datei direkt im Template. Nur wenn das Laden erfolgreich ist, werden Daten ausgegeben. Wenn nicht, wird die Fehlermeldung in die Browser-Konsole geschrieben.

    {{ var $data = $wsExternalData.load("products/product_123.json", { type: "json", source: "user" }) }} {{ if $data }} {{= $data }} {{ else }} {{ var $error = $wsExternalData.getLastError() }} {{ if $error }} <script> {{ autoescape "js" }} console.error("$wsExternalData Error: {{= $error }}"); {{ /autoescape }} </script> {{ /if }} {{ /if }}

     

    Referenz

    In der Modul-Referenz für $wsExternalData finden Sie eine Übersicht aller verfügbaren Eigenschaften und Parameter.

    © 2025 WEBSALE AG | Impressum | Datenschutz