- 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>
9.9 KiB
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, …}ohnev) wird beim Lesen als Version 1 interpretiert (WidgetType::fromLegacy). - Liegt
vunter der aktuellen Version, hebtWidgetType::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
- Klasse unter
app/Domain/Cms/Widgets/Types/anlegen, vonWidgetTypeableiten. Pflicht:key(),label(),description(),dataRules(),dataFields(). Je nach Bedarf:variants(),refRules(),refFields(),clean()(Links mitSafeUrl, Text mitRichText::sanitize, Bilder mitImageRefFields::clean),resolve()(Verweise zur Laufzeit auflösen),mediaPaths(),summary(),schematic(),icon(). - Ansicht
resources/views/widgets/<kennung>.blade.phpanlegen. Verfügbar:$data,$refs,$variant,$settings,$first,$context(Vorschau ja/nein) und die Rückgabe vonresolve(). Kein{!! !!}außer für mitRichText::sanitizebereinigten Text. - Klasse in
config/cms.phpunterwidgetseintragen. - Tests ergänzen (Registrierung und Prüfregeln in
tests/Unit/WidgetRegistryTest.php, Darstellung intests/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_publicbzw. noch nicht übertragene Uploads incms_incoming). Bibliotheksmedien erscheinen nicht. - Neue Uploads landen im Webprozess in
cms_incoming(privater Speicher);PublishPublicMediaüberträgt sie in der Hintergrundverarbeitung nachmedia_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
iframemit 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}/geraetemit 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.