Skip to main content

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.

In diesem Abschnitt finden sich Möglichkeiten, um dateibasierte externe Daten aus dem shop-eigenen S3 in Templates zu laden und zu verarbeiten. Typische Anwendungsfälle sind Zusatzinformationen, die nicht aus den Standard-Shopdaten stammen (z.B. Inhalte aus WEBSALE-Komponenten wie einer Strapi-Instanz).

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

​
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
NameTypPflichtBeschreibung
filestringjaPfad 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.
optionsmapjaOptionen für Format und Quelle der zu ladenden Datei:
- type
- source
- maxDepth
Optionen (options)
KeyTypPflichtDefaultBeschreibung
typestringja–Dateiformat. Aktuell erlaubt: json.
sourcestringneinuserDatenquelle: Verfügbare Werte sind user (Bucket external-data) oder system (Bucket system).
Eine Übersicht der verfügbaren Quellen gibt es hier.
maxDepthintnein7Begrenzt, 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, 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 weiterzuverarbeiten. Signatur
list $wsExternalData.read(<path>, <options>) Rückgabe
list - Liste aller gefundenen Dateien/Pfade im Verzeichnis unter Berücksichtigung der Optionen. Parameter
NameTypPflichtBeschreibung
pathstringjaVerzeichnis-Pfad innerhalb der gewählten Quelle (z. B. json/Deutsch/).
optionsmapneinOptionen zur Auswahl der Quelle und zur Einschränkung der Treffer:
- source
- recursive
- glob
Optionen (options)
KeyTypPflichtDefaultBeschreibung
sourcestringneinuserDatenquelle: Verfügbare Werte sind user (Bucket external-data) oder system (Bucket system).
Eine Übersicht der verfügbaren Quellen gibt es hier.
recursiveboolneinfalsetrue: Verzeichnisbaum rekursiv durchsuchen (es werden auch Unterordner durchsucht).
false: nur aktuelles Verzeichnis durchsuchen.
globstringnein—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 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.

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