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

# Blöcke

> Blöcke als Grundstruktur von Templates: Header, Footer und Navigation in benannte Bereiche teilen und unabhängig erweitern oder überschreiben.

Blöcke bilden die grundlegende Struktur eines [Templates](/frontend/die-basics/template-theme) und ermöglichen eine flexible Anpassung der Storefront. Sie unterteilen das Layout in klar benannte, isolierte Bereiche wie Header, Footer oder Navigation, die unabhängig voneinander angepasst werden können.

Diese Seite behandelt alles, was es über Blöcke im Detail zu wissen gibt: was sie können, was sie nicht können und wie man sie sinnvoll einsetzt.

## Grundprinzip

Blöcke bauen auf dem Zusammenspiel von Basis- und View-Templates auf. Das [Basis-Template](/frontend/die-basics/template-theme#2-basis-template-layout-template) definiert das übergeordnete Seitenlayout mit allem, was auf jeder Seite gleich bleibt - wie Header, Footer, Navigation oder eingebundene Skripte. Das [View-Template](/frontend/die-basics/template-theme#4-view-templates-seiten-templates) ist das Template einer konkreten Seite - es bindet das Basis Template per `{{ extends }}` ein und befüllt einzelne Bereiche mit seitenspezifischem Inhalt.

Ein Block ist ein benannter Bereich innerhalb eines Templates, der durch `{{ block “name” }}` geöffnet und durch `{{ /block }}` geschlossen wird. Er ist sowohl ein Struktur- als auch ein Inhaltsbaustein. Im Basis-Template legt er fest, welche Bereiche eine Seite hat und wo sie sich befinden, inklusive eines Standardinhalts, der angezeigt wird, solange ein View-Template diesen Block nicht explizit überschreibt. Im View-Template füllt er genau diese Bereiche mit seitenspezifischem Inhalt.

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

***

## Blöcke überschreiben

Ein View-Template greift einen Block auf, indem es ihn mit demselben Namen erneut definiert. Dabei gibt es drei Möglichkeiten:

1. Der Standardinhalt wird vollständig ersetzt:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ extends "layouts/default.htm" }}
{{ block "header" }}
  <header>
    <h1>Willkommen im Shop!</h1>
  </header>
{{ /block }}
```

2. Mit `append` - der neue Inhalt wird hinter dem Standardinhalt eingefügt:

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

3. Mit `prepend` - der neue Inhalt wird vor dem Standardinhalt eingefügt:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ block "header" prepend }}
  <p>Kostenloser Versand heute!</p>
{{ /block }}
```

Der Basis-Block bleibt in allen Fällen unverändert. `append` und `prepend`sind praktisch, wenn der Standardinhalt eines Blocks grundsätzlich passt, aber auf einzelnen Seiten um zusätzliche Inhalte ergänzt werden soll.

***

## Verwendung von Blöcken in Templates

Blöcke können nicht in jedem Template-Typ definiert oder überschrieben werden. Es kommt darauf an, welche Rolle ein Template im System übernimmt:

* **Basis-Templates** (Layout-Templates) sind der einzige Ort, an dem Blöcke definiert werden. Sie legen fest, welche Bereiche einer Seite existieren und welche Standardinhalte diese haben.
* **View-Templates** (Seiten-Templates) und **E-Mail-Templates** können Blöcke eines Basis-Templates überschreiben oder erweitern. Beide binden ein Basis-Template per `{{ extends }}` ein. Dabei gilt eine wichtige Einschränkung: Ein Template mit `{{ extends }}` darf ausschließlich aus Blockanweisungen bestehen. Kein HTML, kein Code, kein Include darf außerhalb eines Blocks stehen.

Typische Blöcke, die das Standard-Layout bereitstellt:

| **Block**      | **Typischer Inhalt**     |
| -------------- | ------------------------ |
| `header`       | Kopfbereich der Seite    |
| `content_main` | Hauptinhalt der Seite    |
| `footer`       | Fußbereich der Seite     |
| `scripts`      | JavaScript am Seitenende |

***

## Blöcke und andere Konstrukte

Im Template-System gibt es mehrere Möglichkeiten, Code zu strukturieren und wiederzuverwenden. Blöcke sind dabei nur eines von mehreren Werkzeugen.

Blöcke reservieren benannte Platzhalter im Layout, die ein View-Template später mit seitenspezifischem Inhalt füllen kann. Sie funktionieren von oben nach unten - das Basis-Template gibt den Rahmen vor, das View-Template füllt ihn. Blöcke sind das Bindeglied zwischen Layout und Seiteninhalt.

[Includes](/frontend/die-basics/template-theme#5-components-includes) binden eine separate Template-Datei an einer bestimmten Stelle ein - ähnlich wie ein Baustein, der an mehreren Stellen eingesetzt werden kann. Ein Breadcrumb oder eine Fehlermeldung sind typische Beispiele - der Code wird einmal geschrieben und überall dort eingebunden, wo er gebraucht wird. Anders als Blöcke können Includes Variablen entgegennehmen und sind damit flexibel in ihren Parametern.

[Module](/frontend/referenz/module) wie `$wsBasket` oder `$wsProducts` stellen Daten bereit. Sie sind keine Template-Bausteine sondern serverseitige Datenquellen, auf die man im Template zugreift.

In der Praxis greifen alle drei ineinander. Ein Block definiert den Bereich der Seite, innerhalb des Blocks werden Includes eingebunden - diese greifen über Module auf die benötigten Daten zu.

***

## Erlaubter Inhalt

### HTML und Template-Syntax

Innerhalb eines Blocks sind erlaubt:

* Beliebiges HTML
* Variablendeklarationen (`{{ var ... }}`) und Ausgaben (`{{= ... }}`)
* Kontrollstrukturen wie `{{ if }}`, `{{ foreach }}`, `{{ switch }}`
* Includes (`{{ include ... }}`)
* Modulzugriffe (`$wsBasket.items`, `$wsCheckout.sum.total` etc.)

### JavaScript und CSS

Blöcke wie `head` oder `scripts` können ohne Einschränkungen `<style>`-Tags, `<link>`-Elemente und `<script>`-Blöcke enthalten, inklusive inline JavaScript. Auch Template-Logik innerhalb von `<script>`-Tags ist möglich, etwa um serverseitig ermittelte Werte in JavaScript zu übergeben:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ block "scripts" }}
  <script src="{{= static('scripts/splide.js') }}" defer></script>
{{ /block }}
```

### Formulare

Formulare sind innerhalb von Blöcken vollständig erlaubt. Das schließt alle üblichen Formularelemente ein (Eingabefelder, Buttons, versteckte Felder, Sicherheitsmechanismen).

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ block "content_main" }}
  {{ var $cAction = $wsActions.create("BasketItemAdd") }}

  <form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wscsrf" value="{{= $cAction.csrf }}">
    <input type="hidden" name="wsact" value="{{= $cAction.id }}">
    <input type="hidden" name="productId" value="{{= $cProduct.id }}">
    <button type="submit">In den Warenkorb</button>
  </form>
{{ /block }}
```

***

## Verschachtelung

Blöcke können beliebig tief ineinander verschachtelt werden. Das ist sinnvoll, wenn ein größerer Bereich des Layouts in mehrere unabhängig überschreibbare Teilbereiche aufgeteilt werden soll. Das Basis-Template definiert dabei die äußere Struktur und jeder innere Block kann im View-Template gezielt überschrieben werden:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ block "content" }}
  {{ block "sidebar" }}
    <aside>Standard-Sidebar</aside>
  {{ /block }}
  {{ block "main" }}
    <div>Standard-Inhalt</div>
  {{ /block }}
{{ /block }}
```

Ein View-Template kann dann gezielt nur `sidebar` oder nur `main` überschreiben, ohne den äußeren `content`-Block anfassen zu müssen.

***

## Best Practices

### Wann Blöcke sinnvoll sind

Blöcke sind das richtige Werkzeug, wenn ein Bereich auf mehreren Seiten vorkommt, aber je nach Seite unterschiedlich aussehen soll - beispielsweise der Footer, der auf normalen Seiten vollständig mit Navigation, Links und Kontaktinformationen erscheint, auf der Login- oder Checkout-Seite aber auf eine kompakte Variante reduziert wird.

### Wann ein anderes Konstrukt sinnvoll ist

Wenn ein Bereich auf mehreren Seiten identisch aussehen soll und nie überschrieben wird, ist ein Include die bessere Wahl. Die Produktvorschau in einer Kategorieliste, eine Breadcrumb-Leiste oder ein Alert-Banner werden nicht überschrieben, sie werden eingebunden. Blöcke wären hier also nicht die richtige Wahl.

### Der richtige Umfang für einen Block

Ein Block sollte einem klar abgrenzbaren Seitenbereich entsprechen. Groß genug, um sinnvoll überschreibbar zu sein, aber klein genug, um nicht zu viel auf einmal zu ändern. Ein einzelner Block für die gesamte Seite ist zu groß, ein Block pro HTML-Element zu wenig. Als Orientierung: Wenn man einen Block klar benennen und erklären kann, wofür er zuständig ist, ist er gut eingesetzt.

### Benennung der Blöcke

Der Name eines Blocks muss eindeutig sein. Kein Basis-Template darf zwei Blöcke mit demselben Namen haben. Der Name sollte den Zweck des Bereichs beschreiben (z.B. `header`, `content_main`, `scripts`) und selbsterklärend sein. Generische Namen wie z.B. `block1` oder `area` sagen nichts darüber aus, was darin steckt und erschweren die Wartung.

### Geschäftslogik in Blöcken

Ein Block gibt Inhalte aus, er trifft keine Entscheidungen. Preisberechnungen, Zugriffsrechte oder Datentransformationen gehören ins entsprechende Modul oder in ein spezialisiertes Include. Blöcke, die solche Logik enthalten, sind schwer zu lesen, kaum testbar und lassen sich nicht wiederverwenden.

### Schwer wartbare Strukturen vermeiden

Tiefe Verschachtelung von Blöcken sollte auf das Notwendigste beschränkt werden. Je tiefer die Verschachtelung, desto schwerer ist es nachzuvollziehen, welcher Block am Ende tatsächlich ausgegeben wird. Als Faustregel gilt: Wenn ein Block sehr lang wird, gehören Teile davon in Includes. Und wenn die Verschachtelung schwer zu überblicken wird, ist das ein Signal, die Struktur zu vereinfachen.

***

## Beispiele

### Einfacher Block

Ein leerer Block im Basis-Template. Er existiert nur als Erweiterungspunkt und hat keinen Standardinhalt. Ein View-Template kann ihn befüllen, muss es aber nicht.

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

### Block mit statischem Inhalt

Ein Block mit festem Inhalt, der auf allen Seiten gleich angezeigt wird, solange kein View-Template ihn überschreibt.

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

### Block mit Variablenzugriff

Auf alle Daten, die das System bereitstellt - etwa Produktname oder Beschreibung - kann direkt innerhalb eines Blocks zugegriffen werden. So lassen sich beispielsweise Seitentitel und Meta-Beschreibung dynamisch pro Produkt befüllen.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ block "headMeta" }}
  <title>{{= $wsViews.current.info.product.name }}</title>
  <meta name="description" content="{{= $wsViews.current.info.product.descr }}">
{{ /block }}
```

### Block mit bedingter Ausgabe

Blöcke können Template-Logik enthalten. Etwa um Inhalte nur unter bestimmten Bedingungen anzuzeigen.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ block "head" }}
  {{ if $cStep == "2" }}
    <style>
      /* Nur für Checkout-Schritt 2 benötigte Styles */
    </style>
  {{ /if }}
{{ /block }}
```

### Block, der einen anderen Block enthält

Im Basis-Template können Blöcke ineinander verschachtelt werden. Jeder innere Block (hier `sidebar` und `main`) ist dabei unabhängig überschreibbar.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{# Basis-Template #}}
{{ block "content" }}
  {{ block "sidebar" }}
    <aside>Standard-Sidebar</aside>
  {{ /block }}
  {{ block "main" }}
    <div>Standard-Inhalt</div>
  {{ /block }}
{{ /block }}
```

### Negativbeispiel

Ein View-Template, das `{{ extends }}` verwendet, darf ausschließlich aus Blockanweisungen bestehen. Code oder HTML außerhalb eines Blocks ist ungültig und führt zu Fehlern.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{# Ungültig – Code außerhalb eines Blocks #}}
{{ extends "layouts/default.htm" }}

<p>Dieser Text steht außerhalb eines Blocks – das funktioniert nicht.</p>

{{ block "content_main" }}
  <p>Das hier ist korrekt.</p>
{{ /block }}
```