Blocktyp-Verträge

Dieses Dokument begann als das Phase-1-Inventar der aktuell ausgelieferten, veröffentlichten Kern-Blocktypen in WebBlocks CMS, dokumentiert nun auch die schreibgeschützte Admin-Vertragsansicht aus Phase 2 und hält die bisher abgeschlossenen Phase-3-Korrekturen zur Lücken-Standardisierung fest, darunter die Layout-+-Card-Bereinigung für section, container, grid, cluster, card und content_header, die Marketing-/Structured-Content-Bereinigung für hero, columns, column_item, cta, feature-grid und feature-item sowie die Legacy-/Übergangs-Bereinigung, die alte Kompatibilitäts-Slugs ehrlich dokumentiert hält, ohne sie in den veröffentlichten Kernkatalog zu befördern.

Phase 1 ist ausschließlich schreibgeschützte Dokumentation.

• Sie gestaltet keine Blockformulare neu.
• Sie fügt keinen DB-gesteuerten Formular-Builder hinzu.
• Sie migriert keine Blockinhalte.
• Sie ändert das öffentliche Rendering nicht.
• Sie ändert nicht, wie Bearbeitungen unter Admin -> System -> Block Types heute funktionieren.

Der aktuelle Blocktypen-Admin-Bildschirm bleibt ein Katalog- und Metadaten-Bildschirm. In Phase 2 kann er nun für jede aufgeführte Zeile ein schreibgeschütztes Vertrags-Modal öffnen, ist aber weiterhin kein dynamischer Formular-Builder oder Schema-Editor.

Plugin-Phase 3 fügt über PluginBlockTypeDefinition, PluginBlockPackDefinition und PluginBlockRegistry rein deklarative Plugin-Block-Hooks hinzu. Aktivierte Plugins können plugin-eigene Handles wie analytics-tools::score-card für die Discovery bereitstellen, aber diese Deklarationen ersetzen nicht die ausgelieferten Kern-Blockverträge, Kern-Block-Views, Kern-Seeder oder die Blockbearbeitungs-Services. Unqualifizierte Handles im Kern-Stil wie hero bleiben kerneigen und werden für Plugin-Deklarationen abgelehnt.

Ein Blocktyp-Vertrag ist die aktuelle technische Vereinbarung darüber, wie sich ein Blocktyp über die CMS-Schichten hinweg verhält:

• Katalogidentität: Slug, Label, Kategorie, Status sowie System- oder Container-Metadaten
• Quelle des Admin-Formulars: welches Blade-Partial den Block aktuell bearbeitet und welche Felder es bereitstellt
• Validierung und Request-Verarbeitung: wie App\Http\Requests\Admin\BlockRequest Block-Payloads aktuell normalisiert und validiert
• Speicher-Eigentum: welche Werte in blocks, dedizierten Übersetzungszeilen, block_media oder verknüpften Datensätzen liegen
• Übersetzungs-Eigentum: welche nutzerseitigen Felder der Sprache (Locale) gehören
• geteiltes Eigentum: welche Einstellungen oder Beziehungen über Sprachen hinweg geteilt bleiben
• Medien- oder Beziehungs-Eigentum: direktes media_id, geordnetes block_media, Navigations-Lookups oder Beziehungen innerhalb derselben Seite
• Kind-Unterstützung: ob der Block ein Container ist und ob Kindtypen eingeschränkt sind
• Quelle des öffentlichen Renderers: welches öffentliche Blade-Partial den Block heute rendert
• Renderer-Root-Vertrag: ob der Block sein öffentliches Root-Markup besitzt oder sich auf den generischen Wrapper-Pfad verlässt
• Portabilität und Revisionen: ob die aktuelle Speicherform weiterhin durch Revisionen, Klonen, Export/Import und Beförderung wandern soll
• Tests und Lücken: bekannte gezielte Abdeckung, unklares Verhalten oder Kompatibilitätsschulden

Nachfolgend verwendete Statusbegriffe:

• clear: Admin-Formular, Request-Verarbeitung, Speicherung und Renderer stimmen weitgehend überein
• mostly clear: der aktuelle Vertrag ist verständlich, hat aber einen nennenswerten Vorbehalt
• transitional: der aktuelle Vertrag trägt bewusst einen Kompatibilitätspfad oder ein gemischtes Eigentumsmuster
• needs review: aktuelle Codepfade widersprechen sich oder das Verhalten ist so unzureichend dokumentiert, dass Phase 2 es deutlicher sichtbar machen sollte
• legacy/fallback: das veröffentlichte Verhalten hängt von einem Fallback- oder Kompatibilitätspfad ab

Aktuelle und künftige Vertragsarbeit sollte diese Eigentumsregeln explizit halten:

• nutzerseitige Texte gehören in Übersetzungszeilen, wenn der Block der Sprache (Locale) gehört
• geteilte operative oder Einstellungsdaten gehören in geteilte Blockeinstellungen oder explizite Beziehungen
• Medien sollten, wo zutreffend, die Eigentumspfade media_id oder block_media verwenden
• vermeiden Sie es, nutzerseitige Inhalte in beliebiges Einstellungs-JSON zu verschieben
• halten Sie Kompatibilitäts-Speicherpfade dokumentiert, solange sie die öffentliche Ausgabe oder Importe noch beeinflussen

Dieses Phase-1-Inventar basiert auf dem ausgelieferten Quellcode, nicht auf Vermutungen.

• Katalogquelle: app/Support/Blocks/CoreBlockTypeCatalogSyncer.php
• Normalisierung der Blockbearbeitungs-Requests: app/Http/Requests/Admin/BlockRequest.php
• Persistenz-Helfer: app/Support/Blocks/BlockPayloadWriter.php, app/Support/Blocks/BlockTranslationWriter.php, app/Support/Blocks/BlockTranslationResolver.php
• Übersetzungs-Registry: app/Support/Blocks/BlockTranslationRegistry.php
• Admin-Formulare: resources/views/admin/blocks/types/*.blade.php
• öffentliche Renderer: resources/views/pages/partials/blocks/*.blade.php
• Abdeckungsreferenzen: Blockkatalog-, Rendering-, Übersetzungs- und Slug-spezifische Tests unter tests/Feature/

Aktuell hier dokumentierte veröffentlichte Kern-Blocktypen: 42.

Phase 1 fügt einen sicheren Entwickler-Audit-Befehl hinzu:

Der Befehl ist rein lesend.

• er verändert die Datenbank nicht
• er hängt nicht von installierten Site-Inhalten ab
• er liest die ausgelieferten Kern-Katalogdefinitionen
• er prüft das Vorhandensein der ausgelieferten Admin-Formular- und öffentlichen Renderer-Dateien
• er berichtet Übersetzungsfamilien-Metadaten und grundlegende Container-Unterstützung

Der Befehl ist eine Aktualitätshilfe für Katalog- und Dateipräsenz-Drift. Er ersetzt nicht die ausführlicheren Vertragsnotizen in diesem Dokument.

Phase 2 legt Vertragsdetails schreibgeschützt unter Admin -> System -> Block Types offen.

• jede Zeile kann ein Block Type Contract-Modal öffnen
• das Modal ist rein informativ und sendet keine Aktualisierungen
• es zeigt Katalog-, Admin-Formular-, Speicher-, Übersetzungs-, Medien- oder Beziehungs-, Kind-, Renderer- und Lücken-Details aus dem ausgelieferten Code
• es macht die Blocktypen-Verwaltung nicht zu einem Schema-Editor oder Formular-Builder
• eigene oder Entwurfs-Blocktypen können das Modal weiterhin öffnen, zeigen aber möglicherweise No shipped contract is documented for this block type yet., wenn kein Kernvertrag definiert ist

Veröffentlichte Blocktypen haben heute nicht jeweils eine eigene dedizierte Request-Klasse.

• App\Http\Requests\Admin\BlockRequest ist der gemeinsame Bearbeitungs-Request-Pfad
• slug-spezifische Zweige innerhalb dieses Requests normalisieren Felder in die aktuelle kanonische Speicherung
• App\Support\Blocks\BlockPayloadWriter persistiert die normalisierte Block-Payload
• App\Support\Blocks\BlockTranslationWriter verschiebt locale-eigene Felder für registrierte Familien in Übersetzungszeilen
• App\Support\Blocks\BlockTranslationResolver löst übersetzte oder Fallback-Werte zurück auf eine renderbare Blockinstanz auf

Dieser gemeinsame Request-Pfad ist einer der Gründe, warum Phase 1 zuerst die Verträge dokumentiert, bevor schemagesteuerte Bearbeitungsarbeiten beginnen.

Aktuell verbleibende wesentliche Lücken nach den aktuellen Phase-3-Korrekturen:

• gallery bewahrt weiterhin einen älteren, auf Einstellungen basierenden Fallback-Pfad für Einträge, wenn kanonische geordnete block_media-Zeilen fehlen
• der table-Renderer unterstützt weiterhin einen älteren Fallback-Pfad über settings.rows, obwohl das zentrale Admin-Formular übersetzten Zeilentext schreibt
• hero bewahrt weiterhin ältere Feld-Fallbacks, wenn die kanonischen übersetzten Einleitungsfelder leer sind
• feature-grid und feature-item sind jetzt veröffentlicht, weil sie quellgestützt sind, bleiben aber bewusst transitionale Delegate-Verträge über den gemeinsamen Präsentationspfaden von Columns bzw. Column Item
• tabs, slider, menu und faq-list existieren weiterhin als ältere Entwurfs-Katalogzeilen mit Kompatibilitätsformularen oder -Renderern, sind aber keine veröffentlichten Kernverträge und sollten im Vertragsmodal und in der Audit-Ausgabe weiterhin sicher fehlschlagen
• showcase-list und contact-info existieren weiterhin nur als Kompatibilitätspfade für das öffentliche Rendering und nicht als ausgelieferte veröffentlichte Kern-Katalogblöcke; ihre einstellungsgesteuerten Links folgen jetzt denselben sicheren öffentlichen URL-Regeln wie andere Block-Renderer
• veröffentlichte und Entwurfs-Kataloge existieren nebeneinander, daher muss die künftige Admin-Darstellung explizit zwischen veröffentlichten Kernverträgen und Entwurfs- oder installationsspezifischen Zeilen unterscheiden

Empfohlene spätere Standardisierungsarbeiten für Blockgruppen:

• stabile produktseitig verantwortete Blockgruppen wie Layout, Inhalt, Navigation, Muster und Erweitert in einer einzigen Quelle der Wahrheit definieren
• Picker-Gruppierungen, Doku-Gruppierungen und die Gruppierungen im Block-Types-Admin an derselben Quelle ausrichten
• entscheiden, welche derzeit als Entwurf oder transitional geführten Blöcke unterstützt, archiviert oder explizit als Legacy eingestuft werden sollen
• standardisieren, welche Verträge übersetzungsgestützt und welche bewusst rein gemeinsam (shared-only) sind, bevor schemagesteuerte Formulararbeiten beginnen

Phase 1 erstellt das aktuelle Inventar der veröffentlichten Verträge, ohne das Blockbearbeitungsverhalten, die Blockspeicherung oder das öffentliche Rendering zu verändern.

Das war der beabsichtigte Endpunkt für das Phase-1-Release.

Phase 2 macht den dokumentierten Vertrag im Block-Types-Admin als schreibgeschützte Information sichtbar, während Blockbearbeitungsverhalten, Speicherung, Renderer und Picker-Verhalten unverändert bleiben.

Phase 3 beginnt damit, dokumentierte risikoarme Vertragslücken zu schließen, ohne einen Schema-Editor, einen dynamischen Formular-Builder oder ein DB-gesteuertes Block-Formularsystem hinzuzufügen.

• code folgt jetzt dem bestehenden Textübersetzungspfad für Titel, Label und Snippet-Inhalt, während die Syntaxsprache gemeinsam bleibt
• table folgt jetzt dem bestehenden Textübersetzungspfad für Titel und Zeilentext, während der Tabellenstil gemeinsam bleibt
• breadcrumb bewahrt jetzt die offengelegten gemeinsamen Einstellungen beim Speichern
• stat-card nutzt jetzt die vorhandene optionale URL im öffentlichen Renderer mit einem einfachen sicheren Link
• link-list rendert jetzt die vorhandene übersetzte Einleitung oberhalb der Liste der untergeordneten Einträge
• sticky-navbar richtet jetzt die persistierte Navbar-Root-Eigentümerschaft an Block::ownsPublicRoot() aus, sodass die öffentliche Shell keinen zusätzlichen generischen Wrapper hinzufügt
• image folgt jetzt dem bestehenden Bildübersetzungspfad für Bildunterschrift und Alt-Text, während ausgewählte Medien und die optionale Link-URL gemeinsam bleiben
• gallery verwendet jetzt locale-eigene block_gallery_item_translations für Alt-Text, Bildunterschrift, Overlay-Titel und Overlay-Text je Eintrag, während geordnete Galerie-Medien und Präsentationseinstellungen gemeinsam bleiben; ältere Fallback-Einträge für alte Inhalte bleiben erhalten, und alte Galerietitel/-beschreibungen sind von der normalen Bearbeitung und der öffentlichen Ausgabe ausgeschlossen
• download folgt jetzt dem bestehenden Textübersetzungspfad für sichtbares Label und Hilfetext, während ausgewählte Medien und Button-Variante gemeinsam bleiben
• file, video und audio haben jetzt vollwertige Admin-Formulare und Request-Normalisierung, sodass übersetzter sichtbarer Text und gemeinsame Medien- oder URL-Quellen über denselben Vertrag laufen, den sie bereits öffentlich rendern
• image, gallery, download, file, video und audio akzeptieren keine neue beliebige Kindplatzierung mehr und rendern beliebige historische Kindbäume nicht mehr öffentlich, während vorhandene untergeordnete Zeilen in den Admin-Blockbäumen erhalten bleiben
• code, table, quote, toc und html akzeptieren keine neue normale Kindplatzierung mehr und rendern beliebige historische Kindbäume nicht mehr öffentlich, während vorhandene untergeordnete Zeilen in den Admin-Blockbäumen erhalten bleiben
• navbar-brand und sidebar-brand teilen sich jetzt einen konservativen Fallback-Vertrag aus gespeicherter URL oder Site-Startseite, und beide bewahren eine sichere zugängliche Benennung für reine Logo-Ausgabe, ohne sichtbaren Text zu erzwingen
• sidebar-nav-group verwendet jetzt für verschachtelte Kindlinks dieselbe manuelle Sidebar-Item-Ausgabesemantik wie sidebar-nav-item und bewahrt dabei den bestehenden WebBlocks-UI-Nav-Group-Wrapper-Vertrag
• section, container, grid, cluster, card und content_header verwenden jetzt dieselbe ausgelieferte Vertragsquelle über Registry, schreibgeschütztes Admin-Vertragsmodal, Audit-Ausgabe, Doku und fokussierte Regressionsabdeckung hinweg
• hero, columns, column_item, cta, feature-grid und feature-item sind jetzt im ausgelieferten Kernkatalog veröffentlicht, in der gemeinsamen Vertrags-Registry dokumentiert und als quellgestützte Marketing- oder strukturierte Inhaltsverträge abgedeckt, statt nur als Entwurf oder unterdokumentiert zu bleiben
• Nur-Locale-Bearbeitungen für verwaltete CTA-Buttons und strukturierte untergeordnete Einträge bewahren jetzt gemeinsame URLs, während übersetzte Labels oder Texte weiterhin aktualisiert werden
• Layout-Primitive halten gemeinsame Layout-Einstellungen und Kindstruktur in der kanonischen Blockspeicherung statt in Übersetzungszeilen oder beliebigen Textfeldern
• card verwendet jetzt einen komponierbaren Shell-Vertrag: die übergeordnete Card besitzt den wb-card-Root, Card-Regionen besitzen wb-card-header, wb-card-body und wb-card-footer, Regionsblöcke sind nur unterhalb von Card gültig, und alter gespeicherter Card-Text bleibt nur über einen minimalen Fallback-Renderer-Pfad ohne Regionen erhalten
• content_header behält übersetzten Titel-, Einleitungs- und Meta-Text, rendert seinen Titel immer als H1, ignoriert alte gespeicherte Werte für die Überschriftenebene sicher und hält seinen semantischen <header class="wb-content-header">-Root ohne generischen Wrapper in Renderer-Eigentum
• testimonial und stats bleiben ehrlich als reines Alias-Verhalten dokumentiert, das an bestehende Quote- oder Columns-Renderpfade delegiert, statt als eigenständige veröffentlichte Kernverträge
• tabs, slider, menu und faq-list bleiben Kompatibilitäts-Slugs aus der Entwurfs- oder Alias-Ära statt veröffentlichter Kernverträge, während showcase-list und contact-info rein öffentliche Kompatibilitäts-Renderer ohne ausgelieferten Kernvertragseintrag bleiben