# Theme-System – ITSWEBER CMS

## Konzept
Themes sind eigenständige Ordner unter `/themes/`. Jedes Theme enthält Templates, Assets und eine Konfigurationsdatei. Das aktive Theme wird in den Settings gespeichert.

## Theme-Struktur
```
themes/{name}/
  theme.json          Metadaten
  templates/
    layout.php         Haupt-Layout (Header + Footer)
    home.php           Startseite
    page.php           Standard-Unterseite
    blog-list.php      Blog-Übersicht
    blog-single.php    Blog-Einzelansicht
    gallery.php        Galerie-Übersicht
    gallery-album.php  Galerie-Albumansicht
    contact.php        Kontaktseite
    404.php            Fehlerseite
  assets/
    css/style.css      Theme-CSS
    js/theme.js        Theme-JS
    images/            Theme-spezifische Bilder
```

## theme.json Format
```json
{
  "name": "Default",
  "slug": "default",
  "version": "1.0.0",
  "author": "ITSWEBER",
  "description": "Neutrales Standard-Theme",
  "thumbnail": "assets/images/thumbnail.png"
}
```

## Template-Fallback
1. Aktives Theme (`themes/{active}/templates/{template}.php`)
2. Default-Theme (`themes/default/templates/{template}.php`)
3. Fehler wenn nicht gefunden

## Mitgelieferte Themes

### Default
- Neutral, clean, minimalistisch
- Geeignet als Basis für Anpassungen
- Farben: Weiß, Graustufen, dezenter Akzent

### Business
- Corporate-Look
- Seriös, strukturiert
- Farben: Dunkelblau, Weiß, dezentes Gold

### Creative
- Modern, dynamisch
- Portfolio/Agentur-Stil
- Farben: Dunkle Basis, leuchtende Akzentfarben

### ITSWEBER (Phase 6a/6b/6c – v2.0.0)
- Offizielles ITSWEBER-Markenbild-Theme (eigenständig, kein Fallback nötig)
- Farben: `#15779b` Primärblau, `#2ea3f2` Akzentblau, `#f4f4f4` Alt-Hintergrund
- Schrift: Open Sans (Google Fonts), System-Font-Fallback
- Phase 6c Neuerungen:
  - **Header**: Dunkel-Teal-Gradient (`#0d2d3a → #15779b`), weiße Navigationstexte
  - **Hero v2**: Unterstützt optionales Portrait-/Personenbild (Split-Layout links/rechts), Eyebrow-Text, 2. CTA-Button
  - **topic_cards**: Neue Homepage-Section – Themenkarten mit Icon, Titel, Text, optionalem Link
  - **highlight_grid**: Neue Homepage-Section – Highlight-Kacheln auf Teal-Gradient-Hintergrund
  - **Kontaktformular**: Zweispaltiges Layout (Info links, Formular rechts), CSRF-Schutz, Honeypot, Validierung, Flash-Feedback
  - **Logo im Header**: `filter: brightness(0) invert(1)` für weiße Darstellung auf dunklem Header
  - Alle 9 Homepage-Section-Typen implementiert (hero, intro, features, topic_cards, highlight_grid, blog_preview, gallery_preview, events_preview, cta)

## Homepage-Section-Typen (vollständige Liste)

| section_key      | Beschreibung                                      | Admin-Felder                                             |
|------------------|---------------------------------------------------|----------------------------------------------------------|
| hero             | Hero-Banner (v2: Portrait, Eyebrow, 2. CTA)       | Headline, Eyebrow, Subtitle, Bild, Portrait, 2x CTA     |
| intro            | Einleitungstext                                    | Titel, Text                                              |
| features         | Feature-Cards (Icon, Titel, Text)                  | Titel, Items (Titel/Text)                                |
| topic_cards      | Themenkarten mit Icon/Titel/Text/Link              | Titel, Items (Icon/Titel/Text/URL)                       |
| highlight_grid   | Highlight-Kacheln auf dunklem Hintergrund          | Titel, Items (Icon/Titel/Text/Quelle/URL)                |
| blog_preview     | Letzte Blog-Beiträge dynamisch                     | Titel, Anzahl, CTA                                       |
| gallery_preview  | Galerie-Alben-Vorschau                             | Titel, Anzahl, CTA                                       |
| events_preview   | Kommende Events dynamisch                          | Titel, Anzahl, CTA                                       |
| cta              | Call-to-Action-Sektion                             | Titel, Text, CTA                                         |

## Theme-Brand-Assets
```
themes/itsweber/assets/images/brand/
  itsweber-logo.png     Logo Header/Footer (658×164 RGBA)
  itsweber-icon.png     Icon/Symbol (1024×1024 RGBA)

public/themes/itsweber/assets/images/brand/
  (Mirror der obigen Dateien – Webserver liefert von hier aus)

public/admin/assets/images/brand/
  itsweber-logo.png     Admin Login + Sidebar
  itsweber-icon.png
```
Hinweis: Brand-Bilder sind nicht in `sync-assets.sh` erfasst. Bei Änderung manuell spiegeln.

## Theme-Assets im Frontend
Theme-Assets werden über einen Helper eingebunden:
```php
<?= theme_asset('css/style.css') ?>
// → /themes/{active}/assets/css/style.css
```

## Theme-Wechsel
Über Admin → Theme-Verwaltung. Setzt `active_theme` in `iw_settings`.

---

## Globales Branding-System (Phase 6d)

Logos und deren Darstellungsmodus werden zentral in `iw_settings` verwaltet, nicht im Theme:

### Settings
- `logo_header` (Dateipfad): Logo für Header
- `logo_footer` (Dateipfad): Logo für Footer
- `logo_alt` (Text): Alt-Text für Barrierefreiheit
- `logo_header_mode` ('original' | 'filtered'): CSS-Filter für Header-Logo
- `logo_footer_mode` ('original' | 'filtered'): CSS-Filter für Footer-Logo

### Fallback-Kette
1. **Header-Logo:** `logo_header` → `logo` (legacy) → null
2. **Footer-Logo:** `logo_footer` → `logo_header` → `logo` (legacy) → null

### Helper-Funktionen
```php
// Gibt Logo-URL für Placement (header|footer) zurück
$url = branding_logo_url('header');

// Gibt CSS-Modus zurück ('original' | 'filtered')
$mode = branding_logo_mode('footer');

// Gibt komplettes <img>-Tag mit Fallback zurück
echo branding_logo_img('header', ['class' => 'my-logo']);
```

### CSS-Darstellungsmodi
- `.logo-mode-original`: Standard-Logo-Farben (kein Filter)
- `.logo-mode-filtered`: `filter: brightness(0) invert(1)` – weißes Logo auf dunklem Hintergrund

Beispiel im Template:
```php
$logo_url = branding_logo_url('header');
$logo_mode = branding_logo_mode('header');
if ($logo_url):
    ?><img src="<?= e($logo_url) ?>" alt="<?= e(setting('logo_alt', 'Logo')) ?>" class="logo-image <?= e('logo-mode-' . $logo_mode) ?>" /><?php
endif;
```

### Logo-Upload (Phase 6e)
Logos werden über **Admin → Einstellungen → Branding** hochgeladen:
- Upload via Multipart-Formular (direkter Datei-Upload) oder Mediathek-Picker
- Gespeichert unter `public/uploads/brand/` via `UploadService`
- SVG und ICO werden als Upload-Typen akzeptiert (ADR-054)
- Pfad wird in der entsprechenden Setting gespeichert (z.B. `logo_header`)
- Kein Thumbnail / kein WebP für Branding-Assets (Logo/Favicon werden unverändert gespeichert)
- Legacy-Fallback bleibt: Textfeld-Eingabe eines manuellen Pfads weiterhin möglich

---

## Consent-/Cookie-Management (Phase 6d)

Das CMS hat ein zentrales Consent-Modul zur Verwaltung von Cookie-/Tracking-Einwilligungen. Dieses ist **standardmäßig deaktiviert** und muss explizit aktiviert werden.

### Aktivierung
Admin → Cookie-Einstellungen (`/admin/consent`): Consent-Modul ein-/ausschalten.

### Frontend-Integration
```php
// In layout.php, vor </body>:
<?= consent_banner() ?>

// Optional im Footer:
<?= consent_reopen_link() ?>

// In JavaScript: Prüfung von Nutzer-Einwilligungen
if (consentGiven('functional')) {
    // optionale Cookies/Tracker laden
}
```

### Helper-Funktionen
- `consent_enabled()`: Gibt true zurück wenn Consent aktiviert
- `consent_banner()`: Rendert Banner-HTML + JavaScript
- `consent_reopen_link()`: Optionaler Footer-Link zum Wiederöffnen

### Cookie-Format
Nutzer-Präferenzen werden in `iw_consent` JSON-Cookie gespeichert:
```json
{
    "necessary": true,
    "functional": false,
    "accepted_at": "2026-03-15T12:00:00Z"
}
```

### Kategorien
- **necessary** (immer aktiv): essenzielle Cookies (Session, CSRF, etc.)
- **functional** (optional): Tracker, Analytics, externe Integrationen
