Prüfe Altseiten im echten Altformat und zeige Speicherfehler am Abschnitt.
- Der Altseiten-Test schreibt die Seederdaten vor dem Vergleich im flachen Format zurück, wie sie auf Test und Produktion liegen (die Migration speichert sie inzwischen über die Registry); zusätzlich ein Rundlauf Editor -> Speichern -> Veröffentlichen. - Fehler, die erst die Registry erkennt, erscheinen als Meldung mit Abschnittsnummer und Art (Felder liegen im Dialog). - Seite anlegen übernimmt die gewählten Säulen (wurden bisher verworfen). - Nach dem Speichern wird der Editor neu befüllt, damit duplizierte Abschnitte ihre Kennung behalten. - Entwicklerdokumentation der Registry inkl. Rollback-Hinweis. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
9d936bfa4a
commit
2dc479a8a4
6 files changed
+274
-8
No files matched your search
@@ -0,0 +1,117 @@
|
||||
# CMS: Widget-Registry, Seiteneditor und Basislayout
|
||||
|
||||
Stand: 17.11.2026, Branch `feature/cms-widget-registry`. Bezug: ADR-22, ADR-28, ADR-29, ADR-30, ADR-36 (`12_Entscheidungsprotokoll_ADR.md`), Website-CMS-Zielarchitektur §§5.3–5.4, 6.2.
|
||||
|
||||
Dieses Dokument beschreibt den **umgesetzten** Stand für Entwickler. Es ist keine fachliche Freigabe der ADRs.
|
||||
|
||||
## 1. Überblick
|
||||
|
||||
```
|
||||
config/cms.php ──► WidgetRegistry ──► WidgetRenderer ──► widgets/<typ>.blade.php
|
||||
│ ▲
|
||||
│ ├── öffentliche Seite (PageController::show)
|
||||
│ ├── Vorschau einer Revision (PageController::preview)
|
||||
│ └── Blockvorschau im Editor (WidgetBlock::renderPreview)
|
||||
└──► WidgetEditor (Filament-Builder: Auswahl, Felder, Varianten, Zusammenfassung)
|
||||
```
|
||||
|
||||
| Baustein | Datei | Aufgabe |
|
||||
|---|---|---|
|
||||
| Vertrag | `app/Domain/Cms/Widgets/WidgetType.php` | abstrakte Basisklasse jeder Widget-Art |
|
||||
| Register | `app/Domain/Cms/Widgets/WidgetRegistry.php` | Registrierung, Lesen (Anheben älterer Fassungen), Prüfen und Bereinigen beim Speichern |
|
||||
| Darstellung | `app/Domain/Cms/Widgets/WidgetRenderer.php` | einziger Renderweg für alle drei Darstellungsorte |
|
||||
| Editor-Adapter | `app/Filament/Support/WidgetEditor.php`, `WidgetBlock.php` | baut den Filament-Builder vollständig aus dem Register |
|
||||
| Katalog-Lesesicht | `app/Domain/Cms/Catalog/PublicCatalogReader.php` | einzige Stelle, die entscheidet, welche Programme/Module öffentlich erscheinen |
|
||||
| Hilfen | `app/Domain/Cms/Widgets/Support/*` | sichere Links, bereinigter formatierter Text, öffentlicher Medienbereich, Bildauswahl |
|
||||
| Seitenvorlagen | `app/Domain/Cms/PageTemplates.php`, `resources/views/site/templates/` | derzeit nur `standard` |
|
||||
| Layout | `resources/views/layouts/site.blade.php`, `resources/views/components/site/*` | Kopf, Marke, Navigation, Inhaltsbereich, Fuß |
|
||||
|
||||
## 2. Widget-Vertrag
|
||||
|
||||
Jede Instanz in `page_revisions.blocks` hat dieselbe Hülle:
|
||||
|
||||
| Feld | Inhalt |
|
||||
|---|---|
|
||||
| `id` | stabile Kennung (UUID), bleibt beim Bearbeiten erhalten; Duplikate erhalten beim Speichern eine neue |
|
||||
| `type` | Typkennung aus dem Register; ändert sich nie |
|
||||
| `v` | Schemaversion der Art |
|
||||
| `variant` | eine der für die Art registrierten Varianten |
|
||||
| `settings` | nur registrierte Aufzählungswerte (derzeit nutzt keine Art Einstellungen; freie Werte werden abgewiesen) |
|
||||
| `data` | redaktionelle Inhalte |
|
||||
| `refs` | Verweise auf Fachobjekte oder Medien, nur Kennungen bzw. Pfade im öffentlichen Bereich `cms/` |
|
||||
|
||||
Gespeichert werden nur Schlüssel, für die die Art Prüfregeln deklariert. Felder mit führendem `_` (zum Beispiel `_upload`) sind Editorhilfen und werden nie gespeichert.
|
||||
|
||||
## 3. Versionierung und Altbestand
|
||||
|
||||
- **Altformat** (vor der Registry: `{type, heading, intro, …}` ohne `v`) wird beim Lesen als Version 1 interpretiert (`WidgetType::fromLegacy`).
|
||||
- Liegt `v` unter der aktuellen Version, hebt `WidgetType::upgrade($widget, $from)` schrittweise an.
|
||||
- Gespeicherte Revisionen werden **nicht** umgeschrieben. Erst eine neue Revision aus dem Editor speichert die aktuelle Hülle.
|
||||
- „Wiederherstellen“ kopiert die Bausteine einer Revision unverändert.
|
||||
- Unbekannte Arten werden öffentlich ausgelassen und in der Vorschau als Hinweis gezeigt. Eine Hülle mit höherer Version als im Code (zum Beispiel nach einem Code-Rollback) wird bestmöglich dargestellt, aber nicht gespeichert.
|
||||
- Regel: Optionale neue Felder brauchen keine neue Version. Umbenennen, Umdeuten oder Verschieben von Feldern braucht eine neue Version mit `upgrade()` und einen Test.
|
||||
|
||||
Beispiel: `image_text` Version 1 `{image, alt, body (Klartext)}` → Version 2 `data {title, body (bereinigtes HTML), alt}`, `refs {image}`, Variante `image_left`.
|
||||
|
||||
## 4. Registrierte Widget-Arten
|
||||
|
||||
| Kennung | Name | Version | Varianten | Verweise |
|
||||
|---|---|---|---|---|
|
||||
| `hero` | Einstieg (Hero) | 1 | `standard` (Bild neben dem Text), `highlight` (Markenfläche) | `refs.image` |
|
||||
| `heading` | Überschrift und Einleitung | 1 | `standard` | – |
|
||||
| `prose` | Fließtext | 1 | `standard` | – |
|
||||
| `image_text` | Bild und Text | 2 | `image_left`, `image_right` | `refs.image` |
|
||||
| `cards` | Redaktionelle Karten | 1 | `standard` (Raster), `compact` (kompakte Liste) | Bild je Karte in `data.items[].image` |
|
||||
| `catalog_cards` | Programm- und Modulkarten | 1 | `standard` (Karten mit Kurzbeschreibung), `compact` (Liste) | `refs.items[] = {type: composition, id}` |
|
||||
| `call_to_action` | Handlungsaufruf | 1 | `standard` | – |
|
||||
| `faq` | FAQ | 1 | `standard` | – |
|
||||
|
||||
Darstellungsklassen: `widget widget-<typ> widget-variant-<variante>` an der Abschnittshülle; je Ansicht eigene Klassen (`hero-highlight`, `image-text-right`, `cards-compact`, `catalog-cards-compact`). Ein späterer Design-Schritt verändert nur `resources/views/widgets/*` und `resources/css/app.css`, nicht Daten oder Editor.
|
||||
|
||||
## 5. Neues Widget hinzufügen
|
||||
|
||||
1. Klasse unter `app/Domain/Cms/Widgets/Types/` anlegen, von `WidgetType` ableiten. Pflicht: `key()`, `label()`, `description()`, `dataRules()`, `dataFields()`. Je nach Bedarf: `variants()`, `refRules()`, `refFields()`, `clean()` (Links mit `SafeUrl`, Text mit `RichText::sanitize`, Bilder mit `ImageRefFields::clean`), `resolve()` (Verweise zur Laufzeit auflösen), `mediaPaths()`, `summary()`, `schematic()`, `icon()`.
|
||||
2. Ansicht `resources/views/widgets/<kennung>.blade.php` anlegen. Verfügbar: `$data`, `$refs`, `$variant`, `$settings`, `$first`, `$context` (Vorschau ja/nein) und die Rückgabe von `resolve()`. Kein `{!! !!}` außer für mit `RichText::sanitize` bereinigten Text.
|
||||
3. Klasse in `config/cms.php` unter `widgets` eintragen.
|
||||
4. Tests ergänzen (Registrierung und Prüfregeln in `tests/Unit/WidgetRegistryTest.php`, Darstellung in `tests/Feature/CmsWidgetRenderingTest.php`).
|
||||
|
||||
Editor, Vorschau, Speicherung und öffentliche Darstellung brauchen keine Änderung. `WidgetRegistryTest::test_a_new_widget_type_works_through_the_contract_alone` belegt das mit einer nur im Test definierten Art.
|
||||
|
||||
**Fachobjekt-Widgets** (künftig Angebote, Lizenzartikel, Kampagnen) speichern ausschließlich Kennungen in `refs` und lesen Anzeigeinhalte über eine Lesesicht wie `PublicCatalogReader`. Preise, Rechte und Angebotsbedingungen werden nie in `data` kopiert.
|
||||
|
||||
## 6. Öffentliche Freigabe von Programmen und Modulen (Übergangsregel)
|
||||
|
||||
ADR-29 (öffentliche Fachobjektprofile) ist nicht umgesetzt. Deshalb gilt in `PublicCatalogReader`:
|
||||
|
||||
| Objekt | Im Editor wählbar | Öffentlich sichtbar | Redaktionsvorschau |
|
||||
|---|---|---|---|
|
||||
| Programm mit Anzeigefreigabe, nicht archiviert | ja | ja, mit Link auf `/programme/{id}` (dieselbe Regel wie die bestehende Programmliste) | ja |
|
||||
| Modul mit Anzeigefreigabe, nicht archiviert | ja | **nein** | ja, mit Hinweis „Nur in der Redaktionsvorschau sichtbar“ |
|
||||
| Fassung ohne Anzeigefreigabe, Entwurf, archiviert, ohne Inhaltsart | nein (Speichern wird abgewiesen) | nein | nein |
|
||||
|
||||
Die Prüfung erfolgt bei jeder Darstellung, nicht nur beim Speichern: Wird eine Anzeigefreigabe zurückgenommen, verschwindet die Karte ohne Seitenänderung. Vorschaubilder der Bibliothek sind geschützt (Paket 6) und werden nicht gezeigt; die Karte zeigt eine Inhaltsart-Fläche.
|
||||
|
||||
**Offener Integrationsschritt:** Mit ADR-29 ersetzt die Profilprüfung (Status „gelistet“, gezeigte Fassung, freigegebenes Bild) die Übergangsregel in `PublicCatalogReader::isPublic()`/`entries()`. Daten der Widgets ändern sich dadurch nicht.
|
||||
|
||||
## 7. Medien
|
||||
|
||||
- Wählbar sind nur Bilder im öffentlichen Website-Bereich `cms/` (`media_public` bzw. noch nicht übertragene Uploads in `cms_incoming`). Bibliotheksmedien erscheinen nicht.
|
||||
- Neue Uploads landen im Webprozess in `cms_incoming` (privater Speicher); `PublishPublicMedia` überträgt sie in der Hintergrundverarbeitung nach `media_public`. Der Web-Prozess schreibt nicht in den Medienbestand.
|
||||
- Bilder sind in jedem Widget an einen Alternativtext gebunden (Ausnahme: Kartenbilder gelten als dekorativ, `alt=""`).
|
||||
|
||||
## 8. Editor und Vorschau
|
||||
|
||||
- Seiteneditor: Abschnitte als kompakte Vorschau (dieselbe Ansicht wie öffentlich, in einem isolierten `iframe` mit dem Website-Stylesheet), Kopfzeile mit Art · Variante – Zusammenfassung, Aktionen Sortieren (Pfeile und Ziehen), Bearbeiten (Dialog), Duplizieren, Löschen.
|
||||
- „Entwurf speichern“ erzeugt eine Revision; „Veröffentlichen“ setzt die zuletzt gespeicherte Revision live.
|
||||
- Ganzseitige Vorschau: `/redaktion/vorschau/{revision}/geraete` mit Umschaltern 390/768/1440 px; nur für Personal (`auth:staff` + Seitenrecht).
|
||||
- Revisionen: Vorschau, Veröffentlichen, Wiederherstellen (legt eine neue Revision an).
|
||||
|
||||
Fehler, die erst die Registry beim Speichern erkennt (zum Beispiel Bild ohne Alternativtext, nicht mehr freigegebenes Programm), erscheinen zusätzlich als Meldung mit Abschnittsnummer und Art, weil die Felder im Dialog liegen. Pflichtfelder prüft schon der Dialog beim Übernehmen.
|
||||
|
||||
## 9. Rollback und Datenformat (wichtig vor dem Merge nach `main`)
|
||||
|
||||
Die Migration (`is_visible`) ist ergänzend. Das **Datenformat der Revisionen** ist es nicht in Rückrichtung: Jede Seite, die nach dem Deploy im neuen Editor gespeichert wird, liegt im Hüllenformat vor. Der Code-Rollback von `scripts/deploy.sh` setzt nur den Code zurück; der alte Code kann Hüllen und die neuen Arten `hero`/`catalog_cards` nicht darstellen (Fehler 500 auf genau diesen Seiten, sofern deren veröffentlichte Revision im neuen Format ist). Abhilfe nach einem Rollback: In der Revisionsliste eine Revision aus der Zeit vor dem Deploy veröffentlichen (sie liegt unverändert im Altformat vor) oder den Code wieder vorwärts deployen.
|
||||
|
||||
## 10. Navigation
|
||||
|
||||
`NavigationItemResource`: Einträge bearbeiten, aus-/einblenden (`is_visible`), löschen, Reihenfolge per Ziehen („Reihenfolge ändern“), gruppiert nach Kopf-/Fußzeile, interne Seite oder geprüfte Adresse. Keine zweite Navigationsstruktur im Seiteneditor, keine Mehrstufigkeit.
|
||||
Reference in new issue
Block a user