$wsExternalData - Externe Daten

Externe JSON-Daten aus dem shop-eigenen S3-Bucket in Templates laden, auflisten und Fehler behandeln – für CMS-Inhalte, Feeds und Drittdaten.

Mit dem $wsExternalData-Modul laden Sie dateibasierte externe Daten (JSON) aus dem shop-eigenen S3 in Ihre Templates und verarbeiten sie dort. Typische Anwendungsfälle sind Zusatzinformationen, die nicht aus den Standard-Shopdaten stammen, beispielsweise PDF-Listen zu einem Produkt oder Inhalte aus WEBSALE-Komponenten wie einer Strapi-Instanz.

Auf dieser Seite geht es um den lesenden Zugriff auf abgelegte Dateien. Das Befüllen der Buckets (Upload, Strapi-Export) erfolgt über die Datenschnittstelle, nicht über dieses Modul.

---

​

Grundkonzept

$wsExternalData hat keine eigenen Variablen. Stattdessen laden Sie Daten über eine Methode in eine eigene Template-Variable und arbeiten dann mit dieser weiter. Der Ablauf ist immer derselbe:

1. Laden - load() liest eine Datei und gibt ihren Inhalt zurück; das Ergebnis weisen Sie einer Variable zu (z. B. $data).
2. Prüfen - Sie prüfen mit {{ if $data }}, ob das Laden geklappt hat.
3. Ausgeben - erst danach iterieren oder zeigen Sie die Inhalte.

​

Immer auf Erfolg prüfen

Externe Daten können fehlen oder nicht erreichbar sein (falscher Pfad, leerer Bucket, Zugriffsproblem). Umschließen Sie die Ausgabe deshalb immer mit {{ if $data }} – sonst entstehen leere Platzhalter oder „tote” HTML-Strukturen. Im Fehlerfall liefert getLastError() eine Diagnosemeldung (nur für die Entwicklung, nicht fürs Frontend).

​

Die drei Methoden im Zusammenspiel

• load() lädt den Inhalt einer Datei (Map oder Liste, je nach JSON).
• read() listet die Dateien eines Verzeichnisses auf, ohne deren Inhalt zu laden – nützlich, um dynamisch zu ermitteln, welche Dateien vorhanden sind, und diese anschließend mit load() zu laden.
• getLastError() gibt die letzte Fehlermeldung zurück.

​

Datenquellen (source)

Beide Lade-Methoden kennen zwei Quellen: user (Bucket external-data, Standard) für eigene, projektbezogene Dateien und system (Bucket system) für Dateien, die WEBSALE-Komponenten bereitstellen (z. B. Strapi-Exporte).

​

Hinweis zum Zeitpunkt

load() und read() greifen beim Seitenaufbau auf das S3 zu. Jeder Aufruf ist ein Netzwerkzugriff. Somit laden Sie gezielt, was die Seite braucht, statt unnötig viele Dateien pro Seitenaufruf.

---

​

Modulübersicht

Beispiel / Ausschnitt über $wsExternalData

{{= $wsExternalData | json }}

JSON-Ausgabe

{
  "load": "ƒ()",
  "read": "ƒ()",
  "getLastError": "ƒ()"
}

Anmerkung: "ƒ()" kennzeichnet eine Funktion.

Methoden in der Übersicht

Methode	Rückgabe-Typ	Beschreibung
load()	map | list	Lädt den Inhalt einer JSON-Datei.
read()	list	Listet die Dateien eines Verzeichnisses auf (ohne Inhalt).
getLastError()	string	Letzte Fehlermeldung von load() / read().

---

​

Grundkonzept

$wsExternalData hat keine eigenen Variablen. Stattdessen laden Sie Daten über eine Methode in eine eigene Template-Variable und arbeiten dann mit dieser weiter. Der Ablauf ist immer derselbe:

1. Laden - load() liest eine Datei und gibt ihren Inhalt zurück; das Ergebnis weisen Sie einer Variable zu (z. B. $data).
2. Prüfen - Sie prüfen mit {{ if $data }}, ob das Laden geklappt hat.
3. Ausgeben - erst danach iterieren oder zeigen Sie die Inhalte.

​

Immer auf Erfolg prüfen

Externe Daten können fehlen oder nicht erreichbar sein (falscher Pfad, leerer Bucket, Zugriffsproblem). Umschließen Sie die Ausgabe deshalb immer mit {{ if $data }} – sonst entstehen leere Platzhalter oder „tote” HTML-Strukturen. Im Fehlerfall liefert getLastError() eine Diagnosemeldung (nur für die Entwicklung, nicht fürs Frontend).

​

Die drei Methoden im Zusammenspiel

• load() lädt den Inhalt einer Datei (Map oder Liste, je nach JSON).
• read() listet die Dateien eines Verzeichnisses auf, ohne deren Inhalt zu laden – nützlich, um dynamisch zu ermitteln, welche Dateien vorhanden sind, und diese anschließend mit load() zu laden.
• getLastError() gibt die letzte Fehlermeldung zurück.

​

Datenquellen (source)

Beide Lade-Methoden kennen zwei Quellen: user (Bucket external-data, Standard) für eigene, projektbezogene Dateien und system (Bucket system) für Dateien, die WEBSALE-Komponenten bereitstellen (z. B. Strapi-Exporte).

​

Hinweis zum Zeitpunkt

load() und read() greifen beim Seitenaufbau auf das S3 zu. Jeder Aufruf ist ein Netzwerkzugriff. Somit laden Sie gezielt, was die Seite braucht, statt unnötig viele Dateien pro Seitenaufruf.

---

​

Modulübersicht

Beispiel / Ausschnitt über $wsExternalData

{{= $wsExternalData | json }}

JSON-Ausgabe

{
  "load": "ƒ()",
  "read": "ƒ()",
  "getLastError": "ƒ()"
}

Anmerkung: "ƒ()" kennzeichnet eine Funktion.

Methoden in der Übersicht

Methode	Rückgabe-Typ	Beschreibung
load()	map | list	Lädt den Inhalt einer JSON-Datei.
read()	list	Listet die Dateien eines Verzeichnisses auf (ohne Inhalt).
getLastError()	string	Letzte Fehlermeldung von load() / read().

---

​

Templates

Externe Daten können in jedes Template geladen werden, je nach Anwendungsfall beispielsweise auf Produktdetailseiten (Zusatzdaten), Kategorieseiten (Zusatzlisten) oder Content-Seiten.

---

​

Variablen

$wsExternalData stellt keine eigenen Variablen bereit. Die geladenen Daten sind in der Template-Variable gespeichert, der Sie das Ergebnis von load() zuweisen (siehe Grundkonzept).

---

​

Methoden

​

$wsExternalData.load()

Lädt den Inhalt einer Datei aus der externen Datenschnittstelle und gibt ihn, je nach JSON-Struktur, als Map (bei einem Objekt) oder Liste (bei einem Array) zurück, um ihn im Template auszugeben (z. B. PDFs, Zusatzattribute, CMS-Inhalte).

Signatur
$wsExternalData.load(file, options)

Rückgabe
map | list – abhängig von der JSON-Struktur, im Fehlerfall leer/null.

Parameter

Name	Typ	Pflicht	Beschreibung
file	string	ja	Pfad zur Datei innerhalb der Quelle (z. B. products/product_123.json).
options	map	ja	Format- und Quell-Optionen (siehe Tabelle).

Optionen (options)

Key	Typ	Pflicht	Default	Beschreibung
type	string	ja	–	Dateiformat. Aktuell erlaubt: json.
source	string	nein	user	Datenquelle: user (Bucket external-data) oder system (Bucket system).
maxDepth	int	nein	7	Begrenzt die Auslese-Tiefe verschachtelter JSON-Strukturen; tiefere Ebenen werden gekürzt.

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

​

$wsExternalData.read()

Listet alle Dateien eines Verzeichnisses der externen Datenschnittstelle auf (optional inkl. Unterordnern) und gibt deren Pfade als Liste zurück. Der Dateiinhalt wird nicht geladen, nutzen Sie dafür anschließend load(). Hilfreich, wenn dynamisch ermittelt werden soll, welche Dateien in einem Verzeichnis vorhanden sind.

Signatur
$wsExternalData.read(path, options)

Rückgabe
list – Pfade der gefundenen Dateien.

Parameter

Name	Typ	Pflicht	Beschreibung
path	string	ja	Verzeichnis-Pfad innerhalb der Quelle (z. B. json/Deutsch/).
options	map	nein	Quell- und Filter-Optionen (siehe Tabelle).

Optionen (options)

Key	Typ	Pflicht	Default	Beschreibung
source	string	nein	user	Datenquelle: user oder system.
recursive	bool	nein	false	true: auch Unterordner durchsuchen.
glob	bool	nein	–	Schaltet die Muster-Interpretation ein/aus. Erwartet einen Boolean, kein Muster-String (siehe Hinweis).

{{ var $files = $wsExternalData.read("json/Deutsch/", { source: "system" }) }}
{{ if $files }}
  <ul>
    {{ foreach $file in $files }}
      <li>{{= $file }}</li>
    {{ /foreach }}
  </ul>
{{ /if }}

​

$wsExternalData.getLastError()

Gibt die letzte Fehlermeldung als String zurück, wenn bei load() oder read() ein Fehler aufgetreten ist (z. B. Datei nicht vorhanden, Zugriff nicht möglich). Die Meldung ist für die Fehlersuche gedacht und sollte nicht im Frontend für Kunden ausgegeben werden.

Signatur
$wsExternalData.getLastError()

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

{{ var $error = $wsExternalData.getLastError() }}
{{ if $error }}
  <script>
    {{ autoescape "js" }}
      console.error("$wsExternalData Error: {{= $error }}");
    {{ /autoescape }}
  </script>
{{ /if }}

Geben Sie die Fehlermeldung nur in der Konsole (Entwicklung) aus, nie sichtbar ins Frontend. Der autoescape "js"-Block stellt sicher, dass Sonderzeichen in der Meldung das umgebende Skript nicht zerstören.

---

​

Aktionen

Für $wsExternalData stehen keine Aktionen zur Verfügung.

---

​

Beispiele

​

Produkt-Zusatzdaten (PDF-Liste) laden und ausgeben

Ein häufiger Fall: Zu einem Produkt werden über eine JSON-Datei PDF-Verlinkungen gepflegt. Für Produkt 137497 liegt unter products/137497.json:

{
  "pdf": [
    { "link": "https://medienserver.example/faq.pdf", "name": "Häufige Fragen und Antworten" },
    { "link": "https://medienserver.example/anleitung.pdf", "name": "Bedienungsanleitung" }
  ]
}

Die Datei laden, auf Erfolg prüfen und die PDFs als Liste ausgeben:

{{ var $data = $wsExternalData.load("products/137497.json", { type: "json" }) }}
{{ if $data and $data.pdf }}
  <ul>
    {{ foreach $doc in $data.pdf }}
      <li>
        <a href="{{= $doc.link }}" target="_blank" rel="noopener">{{= $doc.name }}</a>
      </li>
    {{ /foreach }}
  </ul>
{{ /if }}

Ergebnis
Eine Liste verlinkter PDFs. Aber nur, wenn die Datei geladen wurde und ein pdf-Array enthält.

​

CMS-/Strapi-Inhalte aus der Quelle system laden

Aus dem system-Bucket lädt man typischerweise Strapi-Exporte. In Content mischt Strapi verschiedene Block-Typen. Jeder Block trägt ein __component-Feld, über das Sie gezielt filtern.

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

Ein Block in der JSON-Datei sieht z. B. so aus:

{
  "id": 1,
  "__component": "elemente.categories",
  "CategoryIDs": "10-04418,2-06719,3-82749",
  "ClassList": "row mb-3"
}

Ergebnis
Nur Blöcke vom Typ elemente.categories werden über die passende Komponente gerendert. Andere Block-Typen werden übersprungen.

​

Dateien eines Verzeichnisses auflisten

Mit read() ermitteln Sie, welche Dateien vorhanden sind, ohne deren Inhalt zu laden. Den Inhalt laden Sie anschließend gezielt mit load().

{{ var $files = $wsExternalData.read("json/Deutsch/", { source: "system" }) }}
{{ if $files }}
  {{ foreach $file in $files }}
    {{ var $data = $wsExternalData.load($file, { source: "system", type: "json" }) }}
    {{ if $data }}
      <!-- $data weiterverarbeiten -->
    {{ /if }}
  {{ /foreach }}
{{ /if }}

Ergebnis
Alle passenden Dateien werden gefunden und einzeln geladen.

​

Laden mit Fehlerbehandlung

Nur bei Erfolg ausgeben, andernfalls die Fehlermeldung in die Konsole schreiben.

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

Ergebnis
Bei Erfolg erscheinen die Daten, sonst landet die Fehlerursache in der Browser-Konsole.

Wenn Sie einen Pfad aus mehreren Bestandteilen zusammensetzen, können Sie ein Array mit | join zu einem String verbinden, bevor Sie es an load() / read() übergeben. Für einen festen Pfad genügt der String direkt (wie in den Beispielen oben).

---

​

Weiterführende Links

• Externe Datenschnittstelle (Datei-/Bucket-basiert) – legt fest, welche Buckets/Quellen es gibt und wie Dateien abgelegt werden.
• join-Funktion – verbindet ein Array zu einem String (für zusammengesetzte Pfade).