Markdown (Eisvogel)

Ultraforce-theme-entwicklerdokumentation.md

---
title: "Itk25NowChildTheme"
subtitle: "Entwicklerdokumentation (UltraForce Theme)"
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: "Itk25NowChildTheme"
header-right: "Entwicklerdokumentation"
footer-left: "ITK Computer GmbH"
---

# Einordnung

- **Anzeige-Label (Shopware):** „ITK UltraForce Theme (Itk25NowChildTheme)“ (laut `composer.json` → `extra.label`).
- **Shopware-Plugin-Klasse:** `Itk25NowChildTheme\Itk25NowChildTheme`
- **PSR-4:** `Itk25NowChildTheme\` → `custom/plugins/Itk25NowChildTheme/src/`
- **PHP-Umfang:** Nur die leere Plugin-Klasse; **kein** `services.xml`, **keine** eigenen Controller/Services. Die gesamte Business-Logik liegt im **Parent-Theme-Plugin** [Itk25nowTheme](itk25nowtheme-entwicklerdokumentation.md).

---

# Plugin-Klasse

Datei: `custom/plugins/Itk25NowChildTheme/src/Itk25NowChildTheme.php`

```php
class Itk25NowChildTheme extends Plugin implements ThemeInterface
{
}
```

Install/Aktivierung führen **keine** zusätzlichen Schritte aus (keine Custom Fields, keine Migrationen in diesem Plugin).

---

# Theme-Vererbung (`theme.json`)

Pfad: `custom/plugins/Itk25NowChildTheme/src/Resources/theme.json`

| Schlüssel | Bedeutung |
|-----------|-----------|
| **parentTheme** | **`Itk25NowTheme`** – technischer Name des Parent-Theme-Plugins (muss installiert und als Theme verfügbar sein). |
| **name** | Anzeige: „UltraForce Theme (25now Child)“. |

## `views` (Auflösungsreihenfolge)

Reihenfolge im Array (von Shopware von links nach rechts interpretiert; spätere Einträge können frühere überschreiben):

1. `@Storefront`
2. `@Itk25NowTheme`
3. `@Itk25NowChildTheme`
4. `@Plugins`

Damit überschreibt das Child die Parent-/Storefront-Templates und liegt **vor** `@Plugins`, sodass Plugin-Templates noch darüber liegen können.

## `style` (SCSS-Kette)

1. `app/storefront/src/scss/overrides.scss` (Child)
2. `@Storefront`
3. `@Itk25NowTheme`
4. `app/storefront/src/scss/base.scss` (Child)

Overrides werden zuerst geladen, danach Storefront- und Parent-Styles, zuletzt die Child-`base.scss`.

## `asset`

- `@Storefront`
- `@Itk25NowTheme`
- `app/storefront/src/assets` (eigene statische Assets des Child)

```mermaid
flowchart LR
  ST[Storefront Theme]
  PT[Itk25NowTheme]
  CT[Itk25NowChildTheme]
  ST --> PT
  PT --> CT
```

---

# System-Konfiguration (`config.xml`)

Pfad: `custom/plugins/Itk25NowChildTheme/src/Resources/config/config.xml`  
Config-Präfix: **`Itk25NowChildTheme.config.*`**

## Feld `customCss`

- **Typ:** `text-editor`
- **Key:** `Itk25NowChildTheme.config.customCss`
- **Zweck:** Freies CSS, das **global** im Storefront ausgegeben werden soll (siehe Einbindung unten).

## Feld `excludedPages`

- **Typ:** `multi-select`
- **Key:** `Itk25NowChildTheme.config.excludedPages`
- **Zweck:** Liste von **Storefront-Routen-IDs**; auf diesen Routen wird das Custom CSS **nicht** injiziert.

### Optionen (IDs und Bezeichnungen aus der XML-Definition)

| Route-ID (`id`) | Bezeichnung (de-DE) |
|-----------------|---------------------|
| `frontend.checkout.confirm.page` | Checkout Bestätigung |
| `frontend.checkout.offcanvas` | Checkout Offcanvas |
| `frontend.checkout.cart.page` | Warenkorb |
| `frontend.checkout.address.page` | Checkout Adresse |
| `frontend.account.login.page` | Login |
| `frontend.account.register.page` | Registrierung |

---

# Laufzeitverhalten: Custom CSS

Die Ausgabe erfolgt **ohne PHP-Controller** direkt in einem Storefront-Layout-Template des Child-Themes:

- **Datei (technischer Einstieg):** `custom/plugins/Itk25NowChildTheme/src/Resources/views/storefront/layout/meta.html.twig`

**Logik:**

1. SystemConfig lesen: `customCss` und `excludedPages`.
2. Wenn `customCss` nicht leer ist **und** die aktuelle Route **nicht** in der Liste `excludedPages` vorkommt (bzw. die Liste leer ist), wird der konfigurierte CSS-String im Seitenkopf ausgegeben.
3. Andernfalls wird kein zusätzliches CSS aus dieser Konfiguration eingefügt.

Die genaue HTML-Struktur (z. B. `<style>`) steht ausschließlich in der genannten `.twig`-Datei.

Dieselbe Datei erweitert `@Itk25nowTheme/storefront/layout/meta.html.twig` und kann **weitere Blöcke** enthalten (z. B. Tracking-Skripte); diese werden hier nicht dokumentiert.

---

# Betrieb und Abhängigkeiten

1. Plugin **Itk25nowTheme** muss installiert und aktiv sein (Parent-Theme-Plugin mit Custom Fields, Services usw. – siehe [itk25nowtheme-entwicklerdokumentation.md](itk25nowtheme-entwicklerdokumentation.md)).
2. Plugin **Itk25NowChildTheme** installieren und aktivieren.
3. Im **Theme-Manager** dem Verkaufskanal das Child-Theme **„UltraForce …“** zuweisen und Theme kompilieren (`bin/console theme:compile` bzw. Admin).
4. Nach Änderungen an `customCss` ggf. HTTP-/Reverse-Proxy-Caches und Shopware-Cache beachten.

---

# Verzeichnisüberblick (relevant für Entwickler)

| Pfad | Inhalt |
|------|--------|
| `src/Itk25NowChildTheme.php` | Plugin-Bootstrap |
| `src/Resources/theme.json` | Vererbung, Assets, Scripts |
| `src/Resources/config/config.xml` | Plugin-Einstellungen |
| `src/Resources/views/` | Storefront-Overrides (inkl. `layout/meta.html.twig` für Custom CSS) |
| `src/Resources/app/storefront/…` | SCSS-Quellen, gebautes JS unter `dist/` laut `theme.json` |