Files
laraundfelix/docs/architektur/cms-widget-registry.md
T
LarsandClaude Opus 5.5 2dc479a8a4
CI Feature / test (push) Successful in 29s
Deploy Test / test (push) Successful in 26s
Deploy Test / deploy (push) Successful in 31s
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>
2026-11-17 18:01:55 +01:00

9.9 KiB
Raw Blame History

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.