Templates für strapi Inhalte anpassen

Auf dieser Seite wird beschrieben, wie die Shop-Templates bei veränderten oder neuen strapi Komponenten oder Inhalte angepasst werden müssen.

Diese Dokumentation richtet sich vorranging an Template-Manager und setzt Kenntnisse in HTML, CSS, JSON und der WEBSALE Template Engine voraus.

---

Zugriff auf die Shop-Templates

strapi definiert Struktur und Inhalte (Content-Types, Komponenten, Felder). Die Shop-Templates definieren, wie diese Inhalte im Shop dargestellt werden.

Wenn sich in strapi etwas ändert (neue Komponente, neues Feld, Feld umbenannt), muss das entsprechende Shop-Template angepasst werden, da sonst ansonsten im Shop nichts, nicht vollständig oder falsch angezeigt wird.

Um Templates anpassen zu können, benötigen Sie Zugriff auf das entsprechende Shop-Template-Repository in GitLab. Mehr Informationen dazu finden Sie hier.

In der Regel gibt es zwei Anwendungsfälle für die Anpassung von Templates:

• Bestehende Komponenten verändern (Feld hinzugefügt/umbenannt/entfernt)
• Neue Komponenten hinzufügen (Komponente existierte vorher nicht im Template)

---

Bestehende Komponente wurde geändert

Eine bestehende strapi-Komponente gilt als geändert, wenn z. B. ein Feld hinzugefügt, umbenannt oder entfernt wurde. Damit die Anpassung im Shop sichtbar wird, muss das Rendering im entsprechenden Template erweitert oder angepasst werden.

Template ermitteln

Wir empfehlen, pragmatisch über die Suche in GitLab vorzugehen, um das Template zu ermitteln, in dem die Anpassung vorgenommen werden muss.

Suchen Sie zum Beispiel nach:

• Komponentenname (z. B. slider, imageLink, promoBanner)
• Feldname (z. B. autoplayDelay, linkUrl, headline)
• Komponentenkennung aus den JSON-Daten, falls vorhanden (häufig z. B. __component oder eine Typ-/Slug-Angabe)

Die Treffer führen Sie in der Regel zu einer Datei, in der die Komponente gerendert (Partial/Komponenten-Template), eingebunden (View-Template) oder zugeordnet (Mapping/Dispatcher) wird.

Öffnen Sie die Datei anschließend in Ihrem Bearbeitungsprogramm, um mit der Anpassung fortzufahren.

JSON-Datei ermitteln

Damit Sie die Komponente später gezielt laden oder herunterladen können, müssen Sie die konkrete JSON-Datei identifizieren, in der die Komponentendaten gespeichert sind.

Da die Komponente bereits im Shop verwendet wird, wird die dazugehörige JSON-Datei im Template in der Regel bereits an einer Stelle im Template geladen.

Empfohlenes Vorgehen:

• Über das Template (schnellster Weg): Suchen Sie im relevanten Template nach Stellen, an denen Daten geladen werden – typischerweise über $wsExternalData.load(...) (eine Datei) oder $wsExternalData.read(...) (Verzeichnis). Der dort verwendete path ist der Hinweis darauf, welche JSON-Datei(en) im Rendering verwendet werden.
• Über S3/Objektspeicher: Laden Sie die Datei(en) aus dem relevanten Verzeichnis herunter und suchen Sie darin nach der Komponentenkennung (z. B. content.imageLink bzw. __component). So finden Sie heraus, in welcher Datei die Komponente tatsächlich enthalten ist.

Publizierung im Testmodus

Wenn Inhalte aus strapi zunächst nur im Testmodus sichtbar sein sollen, kann die JSON in einem separaten Unterordner (z.B. /test) abgelegt werden. Im Template wird dann abhängig vom Testmodus der Pfad zur JSON-Datei umgestellt.

Beispiel:
Die JSON-Datei wird für Testinhalte zusätzlich in einem Unterordner /test abgelegt. Wenn der Testmodus aktiv ist ($wsTestMode.active), lädt das Template automatisch die Test-JSON aus diesem Unterordner. Dadurch können Anpassungen im Template oder neue / angepasste strapi-Komponenten getestet werden, ohne die Live-Ausgabe zu beeinflussen.

{{ var $cCMSLoadOptions = {"source": "system", "type": "json", "maxDepth": 20} }}
{{ var $cCMSFile = ["json/Deutsch/ws_start.json"] | join }}

{{ if $wsTestMode.active }}
  {{ $cCMSFile = ["json/Deutsch/test/ws_start.json"] | join }}
{{ /if }}

{{ var $cCMSData = $wsExternalData.load($cCMSFile, $cCMSLoadOptions) }}

JSON prüfen

Bevor Sie den Template-Code ändern, sollten Sie prüfen, wie die Komponente tatsächlich als Daten geliefert wird. Das hilft vor allem dabei, Tippfehler und falsche Annahmen über Feldnamen zu vermeiden.

Je nach Setup gibt es dafür zwei übliche Wege:

• Ausgabe/Debug im Template, z. B. an der Stelle, an der die Daten über $wsExternalData.load(...) verarbeitet werden.
• Download aus dem Objekt-/Dateispeicher (z. B. S3), sofern die generierten Dateien dort abgelegt werden und Sie Zugriff haben.

Ziel ist, dass der Komponentenname und die Feldnamen eindeutig feststehen, bevor Sie das Rendering im Template erweitern.

Weiterführende Informationen:

• $wsExternalData - Externe Daten
• Externe Datenschnittstelle

Beispiel: Komponente „Bild mit Link“ bekommt ein neues Feld

In strapi existiert eine Komponente mit dem Namen imageLink. Diese Komponente besitzt zunächst die Felder image und linkUrl.

Datenübergabe JSON vor der Komponenten-Änderung

{
  "__component": "content.imageLink",
  "image": { "url": "/media/banner.jpg", "alt": "Banner" },
  "linkUrl": "https://example.tld"
}

Im Template wird die Komponente entsprechend gerendert, indem Bild und Link ausgegeben werden:

Template-Ausgabe vor der Komponenten-Änderung

{{ var $myVariable = $wsExternalData.load(["my-component.json"] | join, {"source":"system","type":"json","maxDepth":20}) }}

<a href="{{ $myVariable.linkUrl }}">
  <img src="{{ $myVariable.image.url }}" alt="$myVariable.image.alt">
</a>

Nun wird die strapi-Komponente imageLink um ein weiteres Eingabefeld erweitert, z. B. text. Dadurch enthält die Datenstruktur zusätzlich den neuen Wert:

Datenübergabe JSON nach der Komponenten-Änderung

{
  "__component": "content.imageLink",
  "image": { "url": "/media/banner.jpg", "alt": "Banner" },
  "linkUrl": "https://example.tld",
  "text": "Jetzt entdecken"
}

Damit der Text im Shop angezeigt wird, muss das Template um die Ausgabe dieses Feldes ergänzt werden:

Template-Ausgabe nach der Komponenten-Änderung

{{ var $myVariable = $wsExternalData.load(["my-component.json"] | join, {"source":"system","type":"json","maxDepth":20}) }}

<a href="{{ $myVariable.linkUrl }}">
  <img src="{{ $myVariable.image.url }}" alt="$myVariable.image.alt">
  <span>{{ $myVariable.text }}</span>
</a>

Wenn bereits Inhalte existieren, die noch ohne das neue Feld gespeichert wurden, sollte das Template so angepasst werden, dass die Inhalte und das Feld nur ausgeben werden, wenn es vorhanden ist. So vermeiden Sie, dass ältere Inhalte beim Rendering unerwartet Probleme verursachen.

Wenn Sie die Anpassung nicht direkt in der Live-Ansicht integrieren möchten, führen Sie die Anpassung zunächst im Testmodus durch.

---

Neue Komponente wurde angelegt

Template auswählen oder Template anlegen

Wenn eine neue Komponente in strapi angelegt wurde, gibt es zwei typische Ziel-Szenarien:

• Die neue Komponente soll auf einer bestehenden Seite angezeigt werden
  Das Template dieser Seite öffnen und die Stelle auswählen, an der Inhalte/Komponenten gerendert werden (z. B. der Bereich, in dem Content-Blöcke ausgegeben werden).
• Die neue Komponente soll auf einer neuen Seite angezeigt werden
  Ein neues View-Template anlegen und dort das Laden und Rendern der Daten implementieren.

JSON-Datei ermitteln

Um die Inhalte der Komponente im Template ausgeben zu können, müssen Sie die JSON-Datei laden, in der die Komponentendaten gespeichert sind. Dazu muss der Dateiname bekannt sein.

Empfohlene Wege, um den Dateinamen zu ermitteln:

• Über $wsExternalData.read(...):
  Wenn das Theme ein Verzeichnis per read einliest, kann darüber eine Dateiliste ausgegeben werden. So lässt sich der relevante Dateiname finden und anschließend gezielt per load laden.
• Über S3/Objektspeicher:
  Wenn Zugriff auf S3 besteht, kann das relevante Verzeichnis geöffnet und die Datei(en) anhand Name/Struktur oder durch Suche nach der Komponentenkennung (z. B. __component) identifiziert werden.

JSON-Daten prüfen

Bevor das Rendering implementiert wird, sollte die JSON geprüft werden, damit eindeutig ist:

• wie die Komponente heißt (z. B. content.promoBanner)
• welche Felder geliefert werden (z. B. image, linkUrl, text)
• wie verschachtelte Strukturen aussehen (z. B. Bildobjekt, Listen)

Das verhindert Tippfehler und falsche Annahmen im Template.

Beispiel neue Komponente integrieren

Sie haben die JSON-Datei identifiziert, die die Daten Ihrer neuen Komponente enthält (z. B. my-new-component.json), und sich die Struktur bereits angesehen:

Datenübergabe JSON vor der Komponenten-Änderung

{
  "__component": "content.promoBanner",
  "image": { "url": "/media/banner.jpg", "alt": "Banner" },
  "linkUrl": "https://example.tld"
}

Um auf die Daten aus my-new-component.json zugreifen zu können, müssen Sie die Datei zuerst laden:

{{ var $myVariable = $wsExternalData.load(["my-new-component.json"] | join, {"source":"system","type":"json","maxDepth":20}) }}

An der Stelle im Template, an der die Daten angezeigt werden sollen, geben Sie die Inhalte aus (vereinfacht):

<a href="{{ $myVariable.linkUrl }}">
  <img src="{{ $myVariable.image.url }}" alt="{{ $myVariable.image.alt }}">
</a>

Wenn Sie die Ausgabe nicht direkt in der Live-Ansicht integrieren möchten, führen Sie die Anpassung zunächst im Testmodus durch.

---

Bildformate definieren

Wenn das Layout genau eingehalten werden soll, sollten Bilder vor dem Upload in strapi in einem Bildbearbeitungsprogramm (z.B. Photoshop) gezielt zugeschnitten und auf die gewünschten Maße optimiert werden. Der Bildkonverter im Admin-Interface des Shops (unter Templates & Inhalte → Bildkonverter) sorgt anschließend dafür, dass das Bild komprimiert und optimiert wird.

Für die Komprimierung und Optimierung im Bildkonverter können unter Bildkonverter → Bildformate entsprechende Profile angelegt werden, damit die Bilder nach den individuellen Wünschen des Anwenders bearbeitet werden.

Um sicherzustellen, dass ein Bild auch korrekt angezeigt wird, wenn die Optimierung nicht das gewünschte Ergebnis ausliefert, kann man über feste Angaben im Template-Code einen Fallback einrichten. Zur Anpassung des Quellcodes verweisen wir hier auf Gitlab.

---

Weiterführende Informationen

• $wsExternalData - Externe Daten
• Komponenten & Sammlungen in strapi