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

# Template Theme

> Aufbau des Template Themes verstehen: HTML-Templates, CSS- und JavaScript-Dateien für die Storefront direkt bearbeiten und individuell gestalten.

Die Gestaltung der Storefront bei WEBSALE ist flexibel und ermöglicht individuelle Anpassungen, erfordert jedoch fortgeschrittenes Know-how in **HTML**, **CSS** und **JavaScript**. Anders als bei anderen Shopsystemen gibt es bei WEBSALE keine vorgefertigten Designs oder Drag-and-Drop-Builder. Stattdessen arbeiten Webdesigner und Frontend-Entwickler direkt mit den HTML-Templates, CSS- und JavaScript-Dateien, um das gewünschte Design zu realisieren.

Ein wesentlicher Vorteil dieses Ansatzes ist, dass die Software von WEBSALE strikt vom Design resp. der Storefront getrennt ist. Änderungen oder Updates an der Software betreffen nicht die Templates. Die Storefront bleibt somit immer unverändert. Neue Funktionen aus Software-Updates können bei Bedarf manuell in die Templates integriert werden.

***

## Verzeichnisstruktur

Die WEBSALE Storefront ist logisch in verschiedene Verzeichnisse unterteilt, die die Templates und zugehörigen Ressourcen wie CSS, JavaScript und Bilder strukturieren.

### Template-Verzeichnis

Das Verzeichnis `templates/` enthält alle HTML-Templates der Storefront. Diese sind in Unterverzeichnisse organisiert, die nach den entsprechenden Controllern benannt sind. Diese Struktur trennt die Vorlagendateien nach den spezifischen Frontend-Bereichen, auf die sie sich beziehen.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
templates
 ├── components
 │   └── inline-scripts
 │   └── spc
 ├── layouts
 ├── mails
 │   └── comment
 ├── pdfs
 ├── views
 │   └── account
 │   └── checkout
 │   └── newsletter
 │   └── other
```

**Bedeutung der Unterverzeichnisse:**

* `templates/components/`: Wiederverwendbare Template-Elemente (Includes), z.B. Produktboxen.
* `templates/layouts/`: Basis-Templates (Layout-Templates), die das allgemeine Grundgerüst aller Shopseiten definieren (z.B. Header, Footer, Navigation).
* `templates/mails/`: Templates für automatisch versendete E-Mails, z.B. Bestellbestätigungen oder Versandbenachrichtigungen. Das Verzeichnis `mails` ist fest vorgegeben und kann nicht umbenannt oder verschoben werden. E-Mail-Templates müssen direkt in diesem Verzeichnis liegen. In den E-Mail-Konfigurationen wird beim `template`-Parameter nur der Dateiname ohne das Präfix `mails/` angegeben (siehe [E-Mails & E-Mail Einstellungen](/konfiguration/e-mails-e-mail-einstellungen)).
* `templates/pdfs/`: Templates für PDF-Ausgaben, z.B. Rechnungen oder Lieferscheine.
* `templates/views/`: Seiten-Templates (View-Templates) für die einzelnen Shopseiten, z.B. Startseite, Kategorieseiten.

<Warning>
  Von diesen Unterverzeichnissen sind nur zwei fest vorgegeben, da das System sie direkt auswertet. Sie dürfen nicht umbenannt werden!

  * `templates/mails/` – enthält alle Mail-Templates.
  * `templates/views/` – enthält alle renderbaren Shop-Seiten (die einzigen von außen per Link adressierbaren Templates).

  Alle übrigen Verzeichnisse (z. B. `components/`, `layouts/`, `pdfs/`) sind eine empfohlene Organisationsstruktur und können frei benannt bzw. angelegt werden.
</Warning>

### Medien-Verzeichnis

Das Verzeichnis `media/themes/default/` enthält die Ressourcen für die Gestaltung der Storefront, wie Schriftarten, SCSS-Dateien, Bilder und Icons. Dieses Verzeichnis befindet sich auf der gleichen Ebene wie `templates/`.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
media
 ├── themes
 │   └── default
 │       └── favicon
 │       └── fonts
 │       └── images
 │       └── scripts
 │       └── scss
 │       └── styles
```

Die Templates im Verzeichnis `templates/` greifen auf die Ressourcen im Verzeichnis `media/themes/default/` zu, um das Layout, die Farben, Schriftarten und Bilder der Storefront zu definieren. Dies ermöglicht eine saubere Trennung von Struktur (HTML) und Design (CSS und Medien).

**Beispiel für die Einbindung von Ressourcen:**

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<link rel="stylesheet" type="text/css" href="{{= static('styles/wsTemplateGlobal.css') }}">


<script src="{{= static('scripts/bootstrap.bundle.js') }}"></script>
<script src="{{= static('scripts/jquery-3.6.4.js') }}"></script>


<img src="{{= static('images/logo.png')}}" alt="">
```

***

## Basis-Template (Layout-Template)

Das Basis-Template, auch als **Layout-Template** bezeichnet, legt das allgemeine Grundgerüst für alle Seiten der Storefront fest. Es definiert zentrale Inhalte und Bereiche, die auf den meisten Shopseiten wiederverwendet werden, und sorgt so für eine einheitliche Struktur und Benutzerführung.

Das Layout-Template ist keine eigenständige Shopseite und kann nicht direkt von außen per Link aufgerufen werden. Es wird stattdessen von den spezifischen [Seiten-Templates (Views) ](#4-view-templates-seiten-templates)erweitert oder eingebunden.

Das Basis-Template befindet sich im Verzeichnis

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
templates
 ├── layouts
```

Hier können ein oder mehrere Layout-Templates abgelegt werden, je nach Anwendungsfall (z. B. allgemeines Layout, Kundekonto, Checkout-spezifisches Layout, Mails etc.)

Das Layout-Template enthält üblicherweise die folgenden zentralen Elemente:

* **Technischer** `<head>`**-Bereich:**
  * Meta-Angaben für Suchmaschinenoptimierung (z. B. Title, Description, Keywords).
  * Verweise auf die CSS- und JavaScript-Dateien der Storefront.
  * Integration von externen Ressourcen wie Schriftarten oder Tracking-Codes.
* **Sichtbarer Headerbereich:**
  * Logo: Darstellung des Shop-Logos.
  * Suche: Eingabefeld für die Produktsuche.
  * Login-Bereich: Zugriff auf das Kundenkonto.
  * Warenkorb und Merkliste: Übersicht über gespeicherte Produkte.
  * Navigation: Primäre Navigation des Shops (z. B. Kategorien).
* **Breadcrumb:**
  * Anzeige des aktuellen Navigationspfads zur besseren Orientierung der Benutzer.
* **Footer:**
  * Weiterführende Verlinkungen wie Impressum, Datenschutz, AGB.
  * Kontaktinformationen oder andere zusätzliche Inhalte.

Ein Layout-Template wird in den [Seiten-Templates (Views)](#4-view-templates-seiten-templates) über den `extends`**-Befehl** eingebunden:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ extends "layouts/default.htm" }}
```

***

## Template-Blöcke

Template-Blöcke bilden die grundlegende Struktur eines Basis-Templates und ermöglichen eine einfache und flexible Anpassung der Storefront. Sie gruppieren die Storefront-Komponenten in kleine, isolierte Blöcke, die unabhängig voneinander bearbeitet oder überschrieben werden können. Dieses Block-System sorgt für eine saubere Struktur und Wiederverwendbarkeit von Inhalten.

Template-Blöcke sind klar definierte Bereiche innerhalb eines Templates, die durch das `block`-Element gekennzeichnet sind. Sie dienen dazu, einzelne Komponenten der Storefront (z. B. Header, Footer, Navigation) voneinander zu trennen, sodass jede Komponente unabhängig angepasst werden kann.

**Beispiel eines Blocks:**

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ block header }}
  <header class="header">
     <h1>Standard-Header</h1>
  </header>
{{ /block }}
```

## Template-Blöcke überschreiben

Ein Template-Block kann in einem [View-Template](#4-view-templates-seiten-templates) überschrieben werden, um spezifische Anpassungen für einzelne Seiten vorzunehmen. Dazu wird das `block`-Element einfach mit dem gewünschten Quellcode in das View-Template integriert. Das Basis-Template bleibt dabei unverändert.

**Beispiel:** Überschreiben des Headers für die Startseite

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ block "header" }}
    <header>
        <h1>Willkommen im Shop!</h1>
        <p>Das ist unser spezieller Header für die Startseite.</p>
    </header>
{{ /block }}
```

### Template-Blöcke erweitern

Es ist auch möglich, bestehende Blöcke zu erweitern, ohne deren ursprünglichen Inhalt zu entfernen. Dafür gibt es die Schlüsselwörter `prepend` (Inhalt voranstellen) und `append` (Inhalt anhängen).

**Beispiel:** Versandkostenfrei-Banner im Header hinzufügen:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ block "header" append }}
    <p>Versandkostenfreiheit ab 50.00 € Einkaufswert</p>
{{ /block }}
```

Mehr Informationen zu den Template-Blöcken sowie deren Verwendung und Anpassung finden sich in der [Referenzdokumentation zu Template-Blöcken](/frontend/referenz/blocke).

***

## View-Templates (Seiten-Templates)

View-Templates definieren die individuellen Inhalte für spezifische Shopseiten und sind die einzigen Templates, die von außen per Link adressierbar sind. Sie basieren in der Regel auf einem Basis-Template und verwenden dessen Blöcke, um eine konsistente Struktur und Gestaltung beizubehalten.

View-Templates befinden sich im Verzeichnis

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
templates
 ├── views
```

View-Templates können direkt verlinkt werden, indem ihre URL über den folgenden Befehl generiert wird:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<a href="{{= $wsViews.viewUrl('impressum.htm')}}">Impressum</a>
```

In diesem Beispiel wird auf das View-Template `impressum.htm` verlinkt.

#### Direkter URL-Aufruf eines View-Templates

Intern erzeugt `$wsViews.viewUrl()` eine URL mit den Query-Parametern `wsvc=View` und `view=<dateiname>`. Ein View-Template lässt sich damit auch direkt über die Browser-URL aufrufen:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.beispielshop.de/?wsvc=View&view=impressum.htm
```

| **Parameter** | **Beschreibung**                                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `wsvc`        | Fest auf `View` gesetzt. Weist den Shop an, den View-Controller aufzurufen.                                                 |
| `view`        | Pfad und Dateiname des View-Templates relativ zu `templates/views/`, z. B. `impressum.htm` oder `account/orderHistory.htm`. |

Zusätzliche Query-Parameter (z. B. `?wsvc=View&view=account/orderHistory.htm&orderHistorySelect=<ID>`) werden an das Template durchgereicht und können dort über `$wsViews.params.<name>` gelesen werden. Verwenden Sie im Template-Code bevorzugt `$wsViews.viewUrl()`, damit URLs korrekt generiert und Änderungen am URL-Schema zentral berücksichtigt werden.

Ein View-Template sollte immer ein Basis-Template verwenden. Dadurch wird sichergestellt, dass alle grundlegenden Strukturen wie Header, Footer oder der technische `<head>`-Bereich aus dem Basis-Template übernommen werden. Die Zuweisung erfolgt immer mit dem Befehl `extends`:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ extends "layouts/default.htm" }}
```

Wird mit dem Befehl `extends` ein Basis-Template zugewiesen darf auf dem View-Template ausschließlich mit Blöcken gearbeitet werden. Bei jedem View-Templates kann dann entschieden werden, welche Blöcke des Basis-Templates übernommen, überschrieben oder erweitert werden. Außerhalb von Blöcken darf kein Code stehen.

### System-Templates

Es gibt drei vordefinierte System-Templates, die nicht umbenannt oder verschoben werden dürfen:

1. `start.htm`: Definiert die Startseite des Shops.
2. `category.htm`: Template für die Kategorieseiten.
3. `product.htm`: Template für die Produktseiten.

Diese Templates sind fester Bestandteil des Systems und dienen als Grundlage für die zentralen Shopseiten.

### Benutzerdefinierte Templates

Für alle anderen Shopseiten gibt es keine System-Vorgaben. Alle anderen Shopseiten sind frei definierbare View-Templates, die erstellt werden können. Diese können frei benannt werden, z. B.:

* `account.htm`: Für das Kundenkonto
* `search.htm`: Für die Suche
* `impressum.htm`: Für die Impressumsseite
* etc.

***

## Components (Includes)

Components, auch bekannt als Includes, sind wiederverwendbare Template-Elemente, die flexibel in verschiedenen Bereichen des Shops eingesetzt werden können. Sie dienen dazu, HTML-Code oder andere Anweisungen (z. B. CSS, JavaScript) zu bündeln und an mehreren Stellen im Shop zu nutzen. Im Gegensatz zu Basis-Templates oder View-Templates enthalten Components keine vollständigen HTML-Seitenstrukturen mit `doctype`, `<html>` oder `<body>`, sondern nur ausgewählte Code-Schnipsel.

Components befinden sich im Verzeichnis:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
templates
 ├── components
```

Ein typisches Beispiel für eine Component ist die Produktbox (Vorschauansicht eines Produkts). Diese wird an verschiedenen Stellen im Shop benötigt:

* In der **Kategorieübersicht**, um Produkte in einer Liste darzustellen.
* In den **Suchergebnissen**, um die Treffer anzuzeigen.
* Auf der **Merkliste**, um gespeicherte Produkte darzustellen.
* Im **Cross-Selling-Bereich** auf der Produktdetailseite, um verwandte oder empfohlene Produkte anzuzeigen.

Anstatt den Code für die Produktbox mehrfach in verschiedenen Templates zu schreiben, wird dieser einmal als Component erstellt, z.B. Components productBox.htm

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<div class="product-box">
    <h3>{{= $myProduct.name }}</h3>
    <p>Preis: {{= $myProduct.price }} €</p>
    <a href="{{= $myProduct.link }}">Details</a>
</div>
```

Anschließend kann die Produktbox überall im Shop eingebunden werden, wo sie benötigt wird – einfach und flexibel über den Include-Befehl:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ include "components/productBox.htm" }}
```

Mehr Details zur Nutzung von Components, zur Übergabe von Produkt- und/oder Kategorieinformationen in die Komponenten sowie weitere Informationen zum Include-Befehl sind in der Referenzdokumentation zu [Template-Blöcken](/frontend/referenz/blocke) und [Components](/frontend/referenz/components) zu finden.

***

## Storefront API

Als Alternative zu den Templates kann auch die [Storefront-API](/schnittstellen/storefront-api) genutzt werden, um den Shop aufzubauen.


## Related topics

- [PDF-Ansichten](/frontend/funktionsubersicht/pdf-ansichten.md)
- [Übersicht - Die Basics](/frontend/die-basics.md)
- [Übersicht - strapi CMS](/strapi-cms.md)
- [Storefront API Session-Handling](/schnittstellen/storefront-api/storefront-api-session-handling.md)
- [E-Mails & E-Mail Einstellungen](/konfiguration/e-mails-e-mail-einstellungen.md)