Die Verträge — Variablen, Hooks, Skripte

Was hier steht, ist fest. Markup, Klassen, Farben und Anordnung sind frei — Namen, Hooks und Helfer nicht. Fast jeder Verstoß bleibt ohne Fehlermeldung: Die Seite liefert Status 200 und ist einfach leer.

Die häufigsten stillen Fehler

Fehler	Folge
`$content` statt `$templateHtml`	Produkt- und Kategorieseiten sind leer
`$products` statt `$productItems`	Listen sind immer leer
`<script>` ohne `nonce`	JavaScript läuft überhaupt nicht
`onclick="…"` im Markup	wird nicht ausgeführt
Block-Option erfunden	wird stillschweigend ignoriert
`@if` direkt hinter einem Buchstaben	ganze Seite leer
Preis von Hand formatiert	Pflichtangaben nach PAngV fehlen
Hintergrund/Rahmen/Schatten im CSS um eine Builder-Fläche	Block-Optionen wie Hintergrund und Schatten wirken nicht
eigenes Sticky-Skript	kämpft mit dem Kleben des Blocks, Kopfzeile springt
Seiteninhalt in `theme.json`	zweiter Bedienweg, den im Builder niemand findet
`<i class="fa-…">`	bleibt leer — `block_icon()` benutzen

Variablen je View

View	Variablen
`builder-template`	`$templateHtml` (fertig gerenderte Vorlage), `$options`
`category`	`$category` (Objekt: `$category->name`), `$productItems`, `$facets`, `$total`, `$limit`, `$options`
`search`	`$productItems`, `$q`, `$total`, `$correctedFrom` („Meintest du …?“), `$facets`, `$limit`, `$options`
`product`	`$product` (Array), `$vm` (für `priceHtml()` & Co.), `$crossSells`, `$upSells`, `$shipping`, `$options`
`home`	`$categories`, `$categoryIndex`, `$options`
`cms-page`	`$page`, `$options`
`wishlist`	`$productItems`, `$options`

Produkt-Methoden (ProductViewModel): name() url() image() secondaryImage() priceHtml() unitPriceHtml() deliveryTimeHtml() isOnSale() salePercent() badges() rating() reviewCount().

Die vollständige, aus dem System gelesene Liste: php artisan theme:kit.

Hooks

Über Hooks hängen Plugins Inhalte ein — Rechtslinks, Preisangaben, Widerruf, Tracking. Wer eine View überschreibt, übernimmt ihre Hooks. Die Namen sind eingefroren und ändern sich nie.

Pflicht — fehlt einer, ist die Aktivierung blockiert:

View	Hook
`layout.blade.php`	`footer_bottom`
`product.blade.php`	`single_product_summary`
`checkout/step4.blade.php`	`checkout_confirm_before`

Empfohlen:

View	Hooks
`layout.blade.php`	`before_header`, `after_header`, `before_footer`, `after_footer`, `body_end`, `storefront_before_content`, `storefront_after_content`
`product.blade.php`	`before_single_product`, `after_single_product`, `product_price_before`, `product_price_after`, `before_add_to_cart`, `after_add_to_cart`
`category.blade.php`, `search.blade.php`	`before_shop_loop`, `after_shop_loop`

Aufruf: {!! hook('footer_bottom') !!}.

Skripte und die Sicherheitsrichtlinie

Der Shop sendet eine strenge Content-Security-Policy. Folgen:

Jedes <script> braucht nonce="{{ csp_nonce() }}".
onclick, onmouseover & Co. werden nicht ausgeführt. Stattdessen Alpine (@click="…") oder ein delegierter Listener in einem Skript mit Nonce.
Die Schnellansicht (partials/quickview.blade.php) kommt per fetch — dort kein <script>.

Häufige Helfer

Helfer	Wofür
`theme_asset('css/app.css')`	Adresse einer Theme-Datei
`theme_setting('key', $default)`	Wert aus „Anpassen”
`design_token('color-accent')`	Token-Wert in PHP
`theme_blocks_render('home')`	eine Builder-Fläche ausgeben
`theme_menu($id)`	Menübaum
`block_icon('fa-truck', 20)`	Symbol als Inline-SVG
`media_picture($src, [...])`	Bild mit AVIF/WebP
`csp_nonce()`	Nonce für Skripte
`im_baukasten()`	läuft der Block gerade in der Builder-Vorschau?