Template Theme

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.

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

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.

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

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:

<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) erweitert oder eingebunden. Das Basis-Template befindet sich im Verzeichnis

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) über den extends-Befehl eingebunden:

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

{{ block header }}
  <header class="header">
     <h1>Standard-Header</h1>
  </header>
{{ /block }}

Template-Blöcke überschreiben

Ein Template-Block kann in einem View-Template ü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

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

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

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

templates
 ├── views

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

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

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:

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

start.htm: Definiert die Startseite des Shops.
category.htm: Template für die Kategorieseiten.
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:

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

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

{{ 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 und Components zu finden.

Storefront API

Als Alternative zu den Templates kann auch die Storefront-API genutzt werden, um den Shop aufzubauen.

Frontend

Die Basics

Getting Started

Referenz – Aktionen

Referenz – Sprache

Referenz – Module

Integrationsanleitung

Praxisbeispiele

Verzeichnisstruktur

Template-Verzeichnis

Medien-Verzeichnis

Basis-Template (Layout-Template)

Template-Blöcke

Template-Blöcke überschreiben

Template-Blöcke erweitern

View-Templates (Seiten-Templates)

Direkter URL-Aufruf eines View-Templates

System-Templates

Benutzerdefinierte Templates

Components (Includes)

Storefront API

​Verzeichnisstruktur

​Template-Verzeichnis

​Medien-Verzeichnis

​Basis-Template (Layout-Template)

​Template-Blöcke

​Template-Blöcke überschreiben

​Template-Blöcke erweitern

​View-Templates (Seiten-Templates)

​Direkter URL-Aufruf eines View-Templates

​System-Templates

​Benutzerdefinierte Templates

​Components (Includes)

​Storefront API

Verzeichnisstruktur

Template-Verzeichnis

Medien-Verzeichnis

Basis-Template (Layout-Template)

Template-Blöcke

Template-Blöcke überschreiben

Template-Blöcke erweitern

View-Templates (Seiten-Templates)

Direkter URL-Aufruf eines View-Templates

System-Templates

Benutzerdefinierte Templates

Components (Includes)

Storefront API