Markdown (Eisvogel)

itk-ajax-modal-twig-funktion.md

---
title: "ITK CMS-AJAX-Modal"
subtitle: "Anwender- & Entwicklerdokumentation"
author: ["André Fischer"]
date: "02-04-2026"
lang: de
titlepage: true
titlepage-color: "1E3A5F"
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "4A90D9"
titlepage-rule-height: 4
toc: true
toc-own-page: true
numbersections: true
header-left: "ITK CMS-AJAX-Modal"
header-right: "Anwender & Entwickler"
footer-left: "ITK Computer GmbH"
---

# Überblick

Die Twig-Funktion `itk_cms_ajax_modal` (intern: CMS-AJAX-Modal) rendert ein `Bootstrap-5-Modal`, das den Inhalt einer **Shopware-CMS-Seite** erst beim Öffnen per **AJAX** von der Standard-Route `frontend.cms.page` lädt – vergleichbar mit der Widget-URL `/widgets/cms/{id}`.

Sie ist Teil des Themes **Itk25nowTheme** und steht in allen Twig-Templates zur Verfügung.

## Diagramm: CMS-Inhalt nachladen (Überblick)

```mermaid
flowchart LR
  T[Twig itk_cms_ajax_modal] --> H[Modal HTML im Browser]
  H --> O[Modal oeffnet]
  O --> F[AJAX frontend.cms.page]
  F --> C[CMS Inhalt im Modal]
```

---

# Teil 1: Für Anwender (Content, Theme, Marketing)

## Wofür du die Funktion nutzt

- **Hinweise, Aktionen oder rechtliche Texte** als Overlay, ohne die aktuelle Seite zu verlassen.
- Inhalt pflegst du **normal im CMS** (Erlebniswelten → CMS-Seite); das Modal holt genau diese Seite nach.
- **Automatisches Öffnen** beim Seitenbesuch ist möglich (z. B. Hinweisbanner), inkl. „nur einmal pro Tab-Session“.

## Was du brauchst

1. Eine **CMS-Seite** in Shopware mit bekannter **UUID** (ID der Seite, steht wenn du im Erlebniswelten-Editor bist oben in der URL).
2. Im Storefront muss **Bootstrap 5** inkl. **Modal-JavaScript** verfügbar sein (Standard im 25now Theme).

## CMS-Seiten-ID finden

Im Admin unter **Inhalte → Erlebniswelten** die gewünschte **CMS-Seite** öffnen oder über eine Zuordnung (z. B. Layout) die Seite identifizieren. Die **technische ID** ist eine UUID (32 Hex-Zeichen, ggf. mit Bindestrichen in der Anzeige – im Twig-String ohne Leerzeichen übergeben).

## Einfachstes Twig-Beispiel

```twig
{{ itk_cms_ajax_modal('DEINE-CMS-PAGE-UUID') }}
```

Damit erscheint ein Modal, das sich **standardmäßig automatisch öffnet** und den CMS-Inhalt nachlädt.

## Optional: Kategorie-Kontext (**navigationId**)

Zweiter Parameter: **Kategorie-ID** (UUID). Sie wird an die CMS-URL als **navigationId** angehängt. Das ist sinnvoll, wenn die CMS-Seite **Listing- oder Navigationskontext** braucht (z. B. gleiche Seite, aber andere Breadcrumbs oder kanalabhängige Inhalte).

```twig
{{ itk_cms_ajax_modal('DEINE-CMS-PAGE-UUID', category.id) }}
```

Ohne Bedarf **null** setzen, da der Zweitparameter optional ist.

## Optionen (dritter Parameter)

Alle Optionen sind optional und werden als **assoziatives Array** übergeben.

| Option | Typ | Standard | Wirkung für dich |
|--------|-----|----------|------------------|
| **title** | Text | leer | Überschrift im Modal-Header. |
| **closable** | ja/nein | ja | Wenn nein: kein X, kein Schließen per ESC, Klick außerhalb blockiert (**statischer Backdrop**). |
| **autoOpen** | ja/nein | ja | Wenn nein: Modal wird nur gebaut, **öffnet nicht** von selbst – du musst es per JavaScript/Button mit Bootstrap `Modal.getOrCreateInstance(...).show()` öffnen. |
| **openInTimer** | Zahl (Sekunden) | 0 | Verzögerung **bis** zum automatischen Öffnen (nur wenn **autoOpen** an ist). |
| **timer** | Zahl (Sekunden) | 0 | Nach dem Öffnen: **so lange** kann der Besucher das Modal **nicht** schließen (nur wenn **closable** an ist). Anzeige mit Countdown-Hinweis. |
| **onlyOncePerSession** | ja/nein | nein | Auto-Open nur **einmal pro Browser-Tab** (technisch: **sessionStorage**, Schlüssel abhängig von der CMS-Seiten-ID). |
| **id** | Text | zufällig | Feste **HTML-ID** des Modals (für eigene Buttons / JS). Nur erlaubte Zeichen: beginnt mit Buchstabe, dann Buchstaben, Ziffern, `_`, `-`, `:`, `.` |

### Beispiele für typische Szenarien

**Modal mit Titel, nicht sofort öffnen (z. B. nur per Button):**

```twig
{{ itk_cms_ajax_modal('UUID', null, {
    title: 'Aktuelle Aktion',
    autoOpen: false,
    id: 'modal-aktion'
}) }}
```

**Hinweis nach 5 Sekunden, nur einmal pro Tab:**

```twig
{{ itk_cms_ajax_modal('UUID', null, {
    title: 'Hinweis',
    openInTimer: 5,
    onlyOncePerSession: true
}) }}
```

**Pflicht-Hinweis 10 Sekunden lang nicht schließbar:**

```twig
{{ itk_cms_ajax_modal('UUID', null, {
    title: 'Wichtige Information',
    timer: 10,
    closable: true
}) }}
```

## Fehlerbilder aus Nutzersicht

- **Leerer Bereich / nichts passiert:** CMS-ID falsch oder Route nicht erreichbar; im Modal-Body erscheint bei Ladefehler ein kurzer Hinweis („Inhalt konnte nicht geladen werden.“).
- **Modal öffnet nicht:** `autoOpen: false` gesetzt und kein eigener Öffnen-Button; oder **onlyOncePerSession** und der Tab hat die Einblendung schon „verbraucht“.
- **Inhalt wirkt ohne Kategorie falsch:** zweiten Parameter `category.id` (oder passende Navigations-Kategorie) setzen.

---

# Teil 2: Für Entwickler

## Einordnung

| Aspekt | Wert |
|--------|------|
| Twig-Funktion | `itk_cms_ajax_modal` |
| PHP | **`ItkComputerGmbh\Itk25NowTheme\Twig\ItkTwigExtension::itkCmsAjaxModal()`** |
| Registrierung | **TwigFunction** in **`getFunctions()`** |
| CMS-Route | `frontend.cms.page` mit Parameter **id** = `$cmsPageId` |
| Query | optional **navigationId** = `$categoryId` (nur wenn nicht leer) |

## Signatur

```php
itkCmsAjaxModal(string $cmsPageId, ?string $categoryId = null, array $options = []): string
```

Rückgabe ist **HTML** (Modal-Markup + eingebettetes `<script>`). Bei **fehlgeschlagener URL-Generierung** (z. B. ungültige Route) liefert die Funktion einen **leeren String** `''`.

## Optionen (technisch)

| Key | Verarbeitung |
|-----|----------------|
| **id** | getrimmt; wenn leer → Modal-ID `itk-cms-modal-` + `randomHex`. Ungültiges Muster → wieder zufällige ID. Erlaubtes Muster: **`^[a-zA-Z][\w\-:.]*$`** |
| **closable** | Default **true**. Bei **false**: `data-bs-backdrop="static"`, `data-bs-keyboard="false"`, kein Close-Button |
| **title** | **htmlspecialchars** (UTF-8, `ENT_QUOTES|ENT_SUBSTITUTE`) |
| **autoOpen** | Default **true** |
| **timer** | Integer; **Schließ-Verzögerung** nur wenn **closable** und **timer > 0** |
| **openInTimer** | Integer **> 0** → verzögertes Öffnen per **setInterval** (1 s Ticks) |
| **onlyOncePerSession** | truthy → **sessionStorage**, Key `itk_cms_ajax_modal_once_` + alphanumerisch bereinigte **cmsPageId** |

## Generierte Struktur

- Root: `<div class="modal fade itk-cms-ajax-modal" … data-itk-cms-url="…">`
- Dialog: `modal-dialog-centered modal-lg modal-dialog-scrollable`
- Body-Container: `.itk-cms-ajax-modal-body` mit initial **Spinner** („Laden …“)
- URL liegt zusätzlich im Attribut **data-itk-cms-url** (escaped)

## AJAX- und Inject-Logik (Kurz)

```mermaid
sequenceDiagram
  participant M as Bootstrap Modal
  participant JS as eingebettetes Script
  participant CMS as CMS Seitenroute
  M->>JS: show.bs.modal
  JS->>CMS: fetch HTML
  CMS->>JS: CMS Seitenfragment
  JS->>M: Inhalt injiziert data-itk-cms-loaded
```

1. Beim Event `show.bs.modal` (Bootstrap): wenn noch nicht geladen (**data-itk-cms-loaded**), `fetch(cmsUrl)` mit Header `X-Requested-With: XMLHttpRequest`, `credentials: 'same-origin'`.
2. Antwort als HTML parsen; Inhalt aus `.cms-page` bevorzugt, sonst **main**, sonst **body**, sonst Rohtext.
3. `bodyWrap.innerHTML = …`
4. Wenn `window.PluginManager.initializePlugins` existiert → Aufruf mit **bodyWrap**, damit Storefront-Plugins im nachgeladenen Fragment initialisieren.
5. Nach erfolgreichem Laden: `data-itk-cms-loaded="1"`

## Schließen sperren (**timer**)

- Bei `shown.bs.modal`: wenn `closeDelaySec > 0`, wird `data-itk-cms-close-blocked="1"` gesetzt, Close-Button **disabled**, Hinweiszeile eingeblendet, Countdown per **setInterval**.
- Bei `hide.bs.modal`: wenn Block aktiv → **`preventDefault()`**.
- Bei `hidden.bs.modal`: Timer aufräumen.

## Auto-Open und Doppel-Initialisierung

- Wenn **autoOpen** und nicht durch **onlyOncePerSession** übersprungen: Öffnen nach **DOMContentLoaded** (oder sofort, wenn Document schon ready).
- Falls Bootstrap noch nicht da: Fallback `window.load`, dann erneuter Öffnen-Versuch.
- Pro DOM-Element: `data-itk-cms-ajax-wired="1"` verhindert, dass dasselbe Modal-Skript mehrfach am gleichen Element läuft (wichtig bei wiederholtem Twig-Output auf derselben Seite).

## Loyalty-Cards-Hydration (Spezialfall)

Eingebettetes Skript enthält `itkCmsModalHydrateLoyaltyRoots(container)`: Sucht `[data-itk-loyalty-root]`, ruft **data-itk-loyalty-endpoint** per **fetch** auf (JSON), formatiert Zahlen **de-DE**, blendet Blöcke bei Fehler oder nicht eingeloggt aus. Das ist eine **theme-spezifische Ergänzung** für CMS-Inhalte mit Loyalty-Markup **innerhalb** des Modals.

## Abhängigkeiten und Symfony-Kontext

- **UrlGeneratorInterface** für `frontend.cms.page`
- **`Doctrine\DBAL\Connection`** und weitere Services sind in der Extension für **andere** Twig-Funktionen injiziert; für `itk_cms_ajax_modal` relevant sind praktisch **Router**, **Uuid** und die Optionen-Verarbeitung.

## Erweiterung und Wartung

- Wenn du **zusätzliche Storefront-Plugins** im Modal brauchst, sicherstellen, dass sie über `PluginManager.initializePlugins` korrekt starten (bereits aufgerufen).

## Debugging-Checkliste

1. `frontend.cms.page` mit der UUID im Browser bzw. mit **X-Requested-With** testen.
2. **navigationId** prüfen, wenn kontextabhängige CMS-Daten fehlen.
3. Browser-Konsole: Bootstrap **Modal** vorhanden?
4. **onlyOncePerSession**: sessionStorage leeren zum Retest.
5. Mehrfaches Einbinden: gleiche **id** und doppeltes Markup können zu Konflikten führen – eindeutige **id** oder nur ein Aufruf pro Seite.

---

# Kurzreferenz (Twig)

```twig
{{ itk_cms_ajax_modal(cmsPageId, categoryId, {
    id: 'optional-html-id',
    title: 'Optional',
    closable: true,
    autoOpen: true,
    openInTimer: 0,
    timer: 0,
    onlyOncePerSession: false
}) }}
```

**Parameter 2** (**categoryId**) kann **null** oder weggelassen werden (in Twig: **null** oder **omit** je nach Aufruf).