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, beispielsweise 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 }}

Der Blockname steht ohne Anführungszeichen, also {{ block header }} und nicht {{ block "header" }}. Ein Name in Anführungszeichen führt beim Kompilieren zum Fehler „Symbol expected“. Anführungszeichen gehören nur zu Dateipfaden, beispielsweise bei {{ extends "layouts/default.htm" }}.

Beim Schließen kann der Blockname wiederholt werden, beispielsweise {{ /block header }}. Das erleichtert bei langen Blöcken die Zuordnung. Der Name muss dann mit dem Namen des geöffneten Blocks übereinstimmen, sonst meldet der Compiler einen Fehler.

Blöcke überschreiben

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

Der Standardinhalt wird vollständig ersetzt:

{{ extends "layouts/default.htm" }}
{{ block header }}
  <header>
    <h1>Willkommen im Shop!</h1>
  </header>
{{ /block }}

Mit append wird der neue Inhalt hinter dem Standardinhalt eingefügt:

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

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

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

Statt ohne Zusatz kann der Standardinhalt auch ausdrücklich mit replace ersetzt werden, beispielsweise {{ block header replace }}. Andere Zusätze nach dem Blocknamen führen zu einem Fehler. 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) definieren die Blöcke. 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. Ein Beispiel ist 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, sonst meldet der Compiler einen Fehler. Der Name wird ohne Anführungszeichen geschrieben und sollte den Zweck des Bereichs beschreiben (beispielsweise header, content_main, scripts). Generische Namen wie 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, beispielsweise 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, beispielsweise 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 }}

WEBSALE

Frontend

Die Basics

Getting Started

Referenz – Aktionen

Referenz – Sprache

Referenz – Module

Integrationsanleitung

Praxisbeispiele

Grundprinzip

Blöcke überschreiben

Verwendung von Blöcken in Templates

Blöcke und andere Konstrukte

Erlaubter Inhalt

HTML und Template-Syntax

JavaScript und CSS

Formulare

Verschachtelung

Best Practices

Wann Blöcke sinnvoll sind

Wann ein anderes Konstrukt sinnvoll ist

Der richtige Umfang für einen Block

Benennung der Blöcke

Geschäftslogik in Blöcken

Schwer wartbare Strukturen vermeiden

Beispiele

Einfacher Block

Block mit statischem Inhalt

Block mit Variablenzugriff

Block mit bedingter Ausgabe

Block, der einen anderen Block enthält

Negativbeispiel

​Grundprinzip

​Blöcke überschreiben

​Verwendung von Blöcken in Templates

​Blöcke und andere Konstrukte

​Erlaubter Inhalt

​HTML und Template-Syntax

​JavaScript und CSS

​Formulare

​Verschachtelung

​Best Practices

​Wann Blöcke sinnvoll sind

​Wann ein anderes Konstrukt sinnvoll ist

​Der richtige Umfang für einen Block

​Benennung der Blöcke

​Geschäftslogik in Blöcken

​Schwer wartbare Strukturen vermeiden

​Beispiele

​Einfacher Block

​Block mit statischem Inhalt

​Block mit Variablenzugriff

​Block mit bedingter Ausgabe

​Block, der einen anderen Block enthält

​Negativbeispiel

Grundprinzip

Blöcke überschreiben

Verwendung von Blöcken in Templates

Blöcke und andere Konstrukte

Erlaubter Inhalt

HTML und Template-Syntax

JavaScript und CSS

Formulare

Verschachtelung

Best Practices

Wann Blöcke sinnvoll sind

Wann ein anderes Konstrukt sinnvoll ist

Der richtige Umfang für einen Block

Benennung der Blöcke

Geschäftslogik in Blöcken

Schwer wartbare Strukturen vermeiden

Beispiele

Einfacher Block

Block mit statischem Inhalt

Block mit Variablenzugriff

Block mit bedingter Ausgabe

Block, der einen anderen Block enthält

Negativbeispiel