> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# $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](/strapi-cms)-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](/schnittstellen/externe-datenschnittstelle-datei-bucket-basiert), nicht über dieses Modul.

***

## Grundkonzept

`$wsExternalData` hat keine eigenen Variablen. Stattdessen laden Sie Daten über eine Methode in eine eigene [Template-Variable](/frontend/referenz/variablen) 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()`](#wsexternaldata-getlasterror) eine Diagnosemeldung (nur für die Entwicklung, nicht fürs Frontend).

### Die drei Methoden im Zusammenspiel

* [`load()`](#wsexternaldata-load) lädt den Inhalt einer Datei (Map oder Liste, je nach JSON).
* [`read()`](#wsexternaldata-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()`](#wsexternaldata-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`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsExternalData | json }}
```

**JSON-Ausgabe**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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](/frontend/referenz/variablen) 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()`](#wsexternaldata-getlasterror) eine Diagnosemeldung (nur für die Entwicklung, nicht fürs Frontend).

### Die drei Methoden im Zusammenspiel

* [`load()`](#wsexternaldata-load) lädt den Inhalt einer Datei (Map oder Liste, je nach JSON).
* [`read()`](#wsexternaldata-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()`](#wsexternaldata-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`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsExternalData | json }}
```

**JSON-Ausgabe**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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](#grundkonzept)).

***

## Methoden

### \$wsExternalData.load()

Lädt den Inhalt einer Datei aus der [externen Datenschnittstelle](/schnittstellen/externe-datenschnittstelle-datei-bucket-basiert#2-datenablage-im-s3) 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. |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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). |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $error = $wsExternalData.getLastError() }}
{{ if $error }}
  <script>
    {{ autoescape "js" }}
      console.error("$wsExternalData Error: {{= $error }}");
    {{ /autoescape }}
  </script>
{{ /if }}
```

<Note>
  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.
</Note>

***

## 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`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.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:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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()`.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ 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.

<Note>
  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).
</Note>

***

## Weiterführende Links

* [Externe Datenschnittstelle (Datei-/Bucket-basiert)](/schnittstellen/externe-datenschnittstelle-datei-bucket-basiert) – legt fest, welche Buckets/Quellen es gibt und wie Dateien abgelegt werden.
* [join-Funktion](/frontend/referenz/funktionen#join) – verbindet ein Array zu einem String (für zusammengesetzte Pfade).


## Related topics

- [FAQ - Häufig gestellte Fragen](/faq-haufig-gestellte-fragen.md)
- [Templates für strapi Inhalte anpassen](/strapi-cms/templates-fur-strapi-inhalte-anpassen.md)
- [Glossar: Fachbegriffe der WEBSALE-Dokumentation](/glossar.md)
- [Externe Datenschnittstelle (Datei-/Bucket-basiert)](/schnittstellen/externe-datenschnittstelle-datei-bucket-basiert.md)
- [Daten-Migration](/migration/daten-migration.md)