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

1 Templates
2 Modulübersicht
3 Variablen
4 Methoden
- 4.1 $wsExternalData.load()
- 4.2 $wsExternalData.read()
- 4.3 $wsExternalData.getLastError()
5 Beispiele
6 Weiterführende Links

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 erfolgen.

Modulübersicht

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):

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()

Variablen

Dieses Modul enthält keine eigenen System- oder WEBSALE-Variablen, die im Template verfügbar sind. Stattdessen werden externe Daten über die Funktionen geladen und einer eigenen Template-Variable zugewiesen (z.B. $data). Erst danach können die Inhalte im Frontend ausgegeben werden.

Beispiel: Produkt-Zusatzdaten per JSON laden und verwenden

Ein Praxisfall sind beispielsweise Dokumente (z.B. PDFs), die über eine JSON-Datei gepflegt werden und Zusatzinformation über Artikel enthalten.

Für ein Produkt mit der Produktnummer 137497 werden über die JSON-Datei 137497.json PDF-Verlinkungen und die passende Linksbeschriftung geliefert:

{
  "pdf": [
    {
      "link": "https://www.ihr-medienserver.de/FAQs_allgemein_volla.pdf",
      "name": "Häufige Fragen und Antworten zu Volla OS"
    },
    {
      "link": "https://www.ihr-medienserver.de/Bedienungsanleitung_Volla_Phone_22.pdf",
      "name": "Bedienungsanleitung Volla Phone 22"
    }
  ]
}

Datei laden, Variable befüllen und Informationen ausgeben:

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

{{ if $data }}
  {{ if $data.pdf }}
    <ul>
      {{ foreach $doc in $data.pdf }}
        <li>
          <a href="{{= $doc.link }}" target="_blank" rel="noopener">
            {{= $doc.name }}
          </a>
        </li>
      {{ /foreach }}
    </ul>
  {{ /if }}
{{ /if }}

Methoden

$wsExternalData.load()

Lädt den Inhalt einer Datei aus der externen Datenschnittstelle und gibt die Daten abhängig davon, ob die JSON-Datei ein Objekt oder ein Array enthält, als Map oder Liste zurück, um den Inhalt anschließend im Template verfügbar zu machen und ausgeben zu können (z. B. PDFs, Zusatzattribute, CMS-Inhalte).

Signatur
string $wsExternalData.load(<file>, <options>)

Rückgabe
map | list - Map oder Liste (abhängig von der JSON-Struktur)

Parameter

Name	Typ	Pflicht	Beschreibung

Name

Typ

Pflicht

Beschreibung

file

string

ja

Pfad zur Datei innerhalb der gewählten Quelle (z. B. products/product_123.json oder json/Deutsch/ws_start.json).

Eine Übersicht der verfügbaren Quellen gibt es hier.

options

map

ja

Optionen für Format und Quelle der zu ladenden Datei:

type
source
maxDepth

Optionen (options)

Key	Typ	Pflicht	Default	Beschreibung

Key

Typ

Pflicht

Default

Beschreibung

type

string

ja

–

Dateiformat. Aktuell erlaubt: json.

source

string

nein

user

Datenquelle: Verfügbare Werte sind user (Bucket external-data) oder system (Bucket system).

Eine Übersicht der verfügbaren Quellen gibt es hier.

maxDepth

int

nein

7

Begrenzt, wie tief verschachtelte JSON-Strukturen beim Laden in die Datenstruktur ausgelesen werden. Sehr tiefe Strukturen werden entsprechend gekürzt.

Beispiel

{{ var $cCMSData = $wsExternalData.load(["json/Deutsch/ws_start.json"] | join, {"source":"system","type":"json","maxDepth":20}) }}
 
{{ foreach $cCMSContentItem in $cCMSData.attributes.Content }}
  {{ if $cCMSContentItem.__component == "elemente.categories" }}
    {{ include "components/cms/categories.htm" with $cContentItem = $cCMSContentItem }}
  {{ /if }}
{{ /foreach }}

Erklärung des Beispiels:

in die Variable $cCMSData wird die JSON-Datei json/Deutsch/ws_start.json mit den entsprechenden Optionen geladen (source, type, maxDepth).
| join wird verwendet, um aus dem Array ["json/Deutsch/ws_start.json"] einen String zu erzeugen, den load() verarbeiten kann.
Die hier relevanten Content-Elemente befinden sich in der JSON-Struktur unter $cCMSData.attributes.Content.
anschließend wird über alle Content-Elemente iteriert. Nur Elemente vom Typ elemente.categories werden herausgefiltert und über include mit der passenden Template-Komponente (components/cms/categories.htm) im Frontend ausgegeben.
die Auswahl über __component ist nötig, weil strapi in Content unterschiedliche Block-Typen mischt (z.B. Kategorie, Teaser, Text, Slider etc.). Jeder Block ist in der JSON-Datei gekennzeichnet, beispielsweise so:
{ "id": 1, "__component": "elemente.categories", "CategoryIDs": "10-04418,2-06719,3-82749", "ClassList": "row mb-3" }

$wsExternalData.read()

Liest alle Dateien aus einem Verzeichnis der externen Datenschnittstelle (optional inkl. Unterordnern) und liefert eine Liste der gefundenen Dateien zurück. Der Dateiinhalt wird dabei nicht geladen. Die Funktion ist hilfreich, 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 weiterzuverarbeiten.

Signatur
list $wsExternalData.read(<path>, <options>)

Rückgabe
list - Liste aller gefundenen Dateien/Pfade im Verzeichnis unter Berücksichtigung der Optionen.

Parameter

Name	Typ	Pflicht	Beschreibung

Name

Typ

Pflicht

Beschreibung

path

string

ja

Verzeichnis-Pfad innerhalb der gewählten Quelle (z. B. json/Deutsch/).

options

map

nein

Optionen zur Auswahl der Quelle und zur Einschränkung der Treffer:

source
recursive
glob

Optionen (options)

Key	Typ	Pflicht	Default	Beschreibung

Key

Typ

Pflicht

Default

Beschreibung

source

string

nein

user

Datenquelle: Verfügbare Werte sind user (Bucket external-data) oder system (Bucket system).

Eine Übersicht der verfügbaren Quellen gibt es hier.

recursive

bool

nein

false

true: Verzeichnisbaum rekursiv durchsuchen (es werden auch Unterordner durchsucht). false: nur aktuelles Verzeichnis durchsuchen.

glob

string

nein

--

Pattern zum Filtern, z. B. product_*.json (alle Dateien, die mit product_ beginnen und auf .json enden).

Beispiel

{{ var $cCMSFiles = $wsExternalData.read(["json/Deutsch/"] | join, {"source":"system","glob":"ws_*.json","recursive":false}) }}

{{ if $cCMSFiles }}
  <ul>
    {{ foreach $cCMSFile in $cCMSFiles }}
      <li>{{= $cCMSFile }}</li>
    {{ /foreach }}
  </ul>
{{ /if }}

Erklärung des Beispiels:

in $cCMSFilessteht der Pfad zum Verzeichnis inklusive der Optionen für read() (source, glob, recursive). | join macht daraus einen String, den read() verwenden kann.
$cCMSFiles enthält anschließend eine Liste der gefundenen Dateien. Im Template werden diese Dateinamen als Liste ausgegeben.
Hinweis: Für das Laden der Inhalte dieser Dateien muss die Funktion load() verwendet werden.

$wsExternalData.getLastError()

Stellt die letzte Fehlermeldung als String bereit, wenn bei load() oder read() ein Fehler aufgetreten ist (z.B. Datei nicht vorhanden, Zugriff nicht möglich). Die Fehlermeldung steht im Template-Kontext zur Verfügung und ist für die Fehlerbehebung gedacht, sie sollte nicht im Frontend für Kunden ausgegeben werden.

Wenn mit externen Daten gearbeitet wird, sollte immer geprüft werden, ob Daten tatsächlich geladen werden. So lassen sich leere Platzhalter oder “tote” Strukturen vermeiden.

Signatur
string $wsExternalData.getLastError()

Rückgabe
string - Fehlerbeschreibung oder leer/null, wenn kein Fehler vorliegt

Beispiel

{{ var $cCMSData = $wsExternalData.load(["json/Deutsch/ws_start.json"] | join, {"source":"system","type":"json","maxDepth":20}) }}

{{ if $cCMSData }}
  {{ foreach $cCMSContentItem in $cCMSData.attributes.Content }}
    {{ if $cCMSContentItem.__component == "elemente.categories" }}
      {{ include "components/cms/categories.htm" with $cContentItem = $cCMSContentItem }}
    {{ /if }}
  {{ /foreach }}
{{ else }}
  {{ var $error = $wsExternalData.getLastError() }}
  {{ if $error }}
    <script>
      console.error("$wsExternalData Error: {{= $error }}");
    </script>
  {{ /if }}
{{ /if }}

Erklärung des Beispiels:

die Ausgabe der Inhalte erfolgt nur, wenn die JSON-Datei erfolgreich geladen wurde. ($cCMSData ist vorhanden).
schlägt das Laden fehl, wird die Fehlermeldung über getLastError()ausgelesen und in die Browser-Konsole geschrieben.
dadurch werden leere oder unvollständige HTML-Strukturen vermieden und Fehler sind für die Template-Entwicklung leichter nachvollziehbar.

Beispiele

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 }}

$wsExternalData

Inhaltsverzeichnis

Templates

Modulübersicht

Datenquellen (source)

Dateien aus einem Verzeichnis lesen (read)

Einzelne Datei laden (load)

Fehlerbehandlung (getLastError)

Variablen

Methoden

$wsExternalData.load()

$wsExternalData.read()

$wsExternalData.getLastError()

Beispiele

Dateien aus einem Verzeichnis lesen (inkl. glob)

JSON-Datei laden (Default: external-data)

JSON-Datei laden (Quelle: system)

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

Weiterführende Links

Datenquellen (`source`)

Dateien aus einem Verzeichnis lesen (`read`)

Einzelne Datei laden (`load`)

Fehlerbehandlung (`getLastError`)

Dateien aus einem Verzeichnis lesen (inkl. `glob`)

JSON-Datei laden (Default: `external-data`)

JSON-Datei laden (Quelle: `system`)