# Storefront-Theming (Twig)

## Namespaces

| Namespace | Verzeichnis | Konfiguration |
|-----------|-------------|----------------|
| `@TerraFlowCMS` | `templates/default/` | `config/packages/twig.yaml` (`twig.paths`) |
| `@administration` | `templates/administration/` | `twig.paths` |
| `@{PluginOrdnername}` | `var/plugin_views/{Name}/` **zuerst**, danach `plugin/{Name}/Resources/views/` | `PluginTwigListener` bei Request |

**Priorität:** Unter demselben Namespace sucht Twig die Pfade in der Registrierungsreihenfolge; der **erste** Fund gewinnt. Deshalb wird `var/plugin_views/{Plugin}/` **vor** dem Plugin-Bundle eingetragen, damit Anpassungen updatesicher bleiben und nicht von Dateien unter `plugin/.../Resources/views` verdeckt werden.

Es gibt **keinen** Namespace `@TerraFlowCmsCore`. Alles Storefront-Default läuft über `@TerraFlowCMS`.

## Auflösung wie bei einem festen Theme-Stack

Welches Template gerendert wird, entscheidet [`StorefrontThemeTemplateResolver`](../src/Service/StorefrontThemeTemplateResolver.php):

- Ist in den Einstellungen ein Plugin-Theme aktiv, die Twig-Datei existiert und das Plugin ist aktiv → `@PluginName/pfad/zur/datei.twig`
- Sonst → `@TerraFlowCMS/pfad/zur/datei.twig`

Dasselbe gilt für `get_theme_base_template()` (intern `resolveBaseTemplate()`): Plugin-`base.html.twig` oder `@TerraFlowCMS/base.html.twig`. Ungültige Plugin-Themen in der DB werden auf `TerraFlowCMS` zurückgesetzt; der System-Cache-Tag `settings` wird invalidiert.

## Block `base_content` und `{{ parent() }}`

Die Seiten-Templates (`page.html.twig`, `login.html.twig`, …) erweitern `get_theme_base_template()` (dein Plugin-`base.html.twig` oder `@TerraFlowCMS/base.html.twig`). **Twig verwendet immer die Block-Definition des untersten Templates:** Überschreibst du `base_content` nur dort ohne `{{ parent() }}`, wird der gleiche Block in deinem Zwischen-`base.html.twig` **nie** ausgeführt.

Die Default-Templates rufen deshalb zu Beginn von `base_content` **`{{ parent() }}`** auf, damit dein Theme z. B. Wrapper, Hinweise oder Skripte **vor** dem Seiteninhalt einfügen kann. Soll etwas **nach** dem Inhalt kommen, kannst du im eigenen `base.html.twig` z. B. `{% block base_content %}{{ parent() }}…{% endblock %}` nutzen und im Leaf-Template `{{ parent() }}` **ans Ende** der Block-Definition setzen (dafür müsstest du ein betreffendes Template im Plugin kopieren und anpassen – oder einen eigenen Block in deinem `base` definieren, den die Seiten füllen).

## Shopware-näheres Plugin-Theme

1. Lege unter `plugin/MeinPlugin/Resources/views/` deine Overrides ab (z. B. `page.html.twig`).
2. **`base.html.twig`** des Plugins sollte explizit vom Default erben:

```twig
{% extends '@TerraFlowCMS/base.html.twig' %}

{# Nur Blöcke überschreiben, die du anpassen willst #}
```

3. Der Twig-Namespace des Plugins ist exakt der **Ordnername** unter `plugin/` (Groß-/Kleinschreibung beachten), z. B. `@MeinPlugin/…`. Die Theme-Auswahl in den Einstellungen nutzt denselben Namen (`SettingsService::getAvailableThemes()`).

Nach einem Update von älteren Builds: Falls das gespeicherte Theme mit abweichender Schreibweise (früher `@` + `ucfirst`) in der DB steht, Theme in den Einstellungen einmal neu wählen und speichern.

## Kurzcodes / Shortcodes

Der Kontaktformular-Shortcode rendert `shortcodes/contact_form.html.twig` über denselben Resolver wie der Storefront (Theme-Override im Plugin möglich).