Blöcke

Blöcke bilden die grundlegende Struktur eines Templates 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 definiert das übergeordnete Seitenlayout mit allem, was auf jeder Seite gleich bleibt - wie Header, Footer, Navigation oder eingebundene Skripte. Das View-Template 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.

{{ 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:

{{ 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:

{{ block "header" append }}
  <p>Versandkostenfreiheit ab 50 €</p>
{{ /block }}

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

{{ block "header" prepend }}
  <p>Kostenloser Versand heute!</p>
{{ /block }}

Der Basis-Block bleibt in allen Fällen unverändert. append und prependsind 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 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 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:

{{ 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).

{{ 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:

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

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

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

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

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

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

{{# 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 }}