Page Builder Content Types selbst entwickeln: Master Format, Formular und Renderer

1. Wann ein eigener Content Type wirklich nötig ist

Ein Page Builder Content Type ist die technische Definition eines Bausteins, den Redakteure per Drag and Drop in eine Seite ziehen können, zum Beispiel Text, Bild, Banner oder Slider. Magento liefert eine solide Grundausstattung mit, doch sobald ein Fachbereich einen Baustein mit ganz eigener Datenstruktur braucht, etwa eine Produktvergleichs-Kachel mit drei fest definierten Attributen oder ein Countdown-Element mit Zieldatum, reicht die Kombination aus vorhandenen Content Types und CSS-Tricks nicht mehr aus. Genau hier setzt die Entwicklung eines eigenen Page Builder Content Type an.

Der Vorteil gegenüber einer Ad-hoc-Lösung über HTML-Content Type oder Widget ist die native Integration in den Page Builder Editor. Ein eigener Content Type erscheint im Drag-and-Drop-Panel, hat eine eigene Konfigurationsmaske im Backend, eine Live-Vorschau im Editor und einen klar definierten Renderer im Frontend. Redakteure arbeiten damit genauso intuitiv wie mit den Standard-Bausteinen, ohne dass sie HTML oder Platzhalter-Syntax verstehen müssen. Für Agenturen und interne Entwicklungsteams ist das der entscheidende Grund, warum sich der Aufwand für einen eigenen Page Builder Content Type mittelfristig auszahlt.

2. Anatomie eines Content Types: content_type.xml und Modul-Setup

Jeder Page Builder Content Type beginnt mit einer Deklaration in etc/pagebuilder/content_type.xml. Diese Datei definiert die Grundeigenschaften: einen eindeutigen Namen, das Label im Editor, das Icon, die Sortierposition in der Palette und Verweise auf die weiteren Konfigurationsdateien für Formular und Master Format. Ohne diese Deklaration erkennt Page Builder den neuen Baustein überhaupt nicht, unabhängig davon, wie viel Code sonst schon vorhanden ist.

Struktur und Namenskonvention orientieren sich eng an den nativen Content Types wie Magento_PageBuilder. Ein eigenes Modul, zum Beispiel Mironsoft_PageBuilderComparisonTile, deklariert Abhängigkeiten zu Magento_PageBuilder in der module.xml, damit die Ladereihenfolge stimmt und der Page Builder Kern vor dem eigenen Content Type initialisiert wird. Wichtig ist außerdem, den name-Attributwert konsistent über alle vier Dateien hinweg zu verwenden: content_type.xml, form_config.xml, das Master-Format-Template und den Renderer-Block.

<!-- app/code/Mironsoft/PageBuilderComparisonTile/etc/pagebuilder/content_type.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/content_type.xsd">
    <type name="comparison_tile" label="Vergleichskachel" component="Magento_PageBuilder/js/content-type"
          preview_component="Mironsoft_PageBuilderComparisonTile/js/content-type/comparison-tile/preview"
          master_component="Mironsoft_PageBuilderComparisonTile/js/content-type/comparison-tile/master"
          form="comparison_tile_form" icon="icon-pagebuilder-tile" sortOrder="130">
        <children>
            <container name="attribute" />
        </children>
    </type>
</config>

3. Master Format: Knockout-Template und Datenbindung

Das Master Format definiert, wie der Content Type innerhalb des Page Builder Editors dargestellt wird, während der Redakteur arbeitet. Technisch ist das ein Knockout.js-Template, gebunden über einen JavaScript-Komponenten-Namen aus der content_type.xml. Wichtig ist die Trennung zwischen Master Format, das nur im Backend-Editor gerendert wird, und dem eigentlichen Frontend-Renderer, der später im Shop ausgeliefert wird. Beide müssen optisch möglichst identisch aussehen, damit die Vorschau im Editor nicht vom tatsächlichen Ergebnis abweicht.

Die Datenbindung läuft über Observable-Felder, die im DataStore von Page Builder gehalten werden. Jede Änderung, die ein Redakteur im Formular vornimmt, schreibt in diesen Store, das Master-Format-Template reagiert per Knockout-Binding sofort darauf. Diese reaktive Kopplung ist der Kern dessen, was einen Page Builder Content Type von einem simplen CMS-Block unterscheidet: Änderungen sind sofort sichtbar, ganz ohne Speichern und Neuladen.

// Mironsoft_PageBuilderComparisonTile/view/adminhtml/web/js/content-type/comparison-tile/master.js
define([
  'Magento_PageBuilder/js/content-type',
], function (ContentType) {
  'use strict';

  return ContentType.extend({
    // Additional model logic for the comparison tile master format
    initObservable: function () {
      this._super();
      this.title = this.dataStore.get('title');
      this.priceLeft = this.dataStore.get('price_left');
      this.priceRight = this.dataStore.get('price_right');
      return this;
    },
  });
});

4. Formular-Konfiguration: form_config.xml und Field-Types

Die Formular-Konfiguration in etc/pagebuilder/form_config.xml bestimmt, welche Eingabefelder im Backend-Panel erscheinen, wenn ein Redakteur den eigenen Content Type auswählt. Jedes Feld wird einem UI-Component-Feld-Typ zugeordnet, zum Beispiel Text, Select, Farbwähler, Bild-Uploader oder Rich-Text-Editor. Diese Konfiguration nutzt dieselbe UI-Component-Engine, die auch in Magento-Admin-Grids zum Einsatz kommt, was den Wiedererkennungswert für Redakteure erhöht.

Für den eigenen Page Builder Content Type lohnt sich eine bewusste Feldreduktion. Jedes zusätzliche Formularfeld erhöht die Komplexität für Redakteure und die Wartungslast im Code. Ein Vergleichskachel-Content-Type mit drei Pflichtfeldern, einer optionalen Beschreibung und einem Style-Feld ist deutlich robuster als eine Variante mit fünfzehn optionalen Einstellungen, die kaum jemand konsistent ausfüllt.

<!-- app/code/Mironsoft/PageBuilderComparisonTile/etc/pagebuilder/form_config.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/form_config.xsd">
    <form name="comparison_tile_form">
        <appearances>
            <appearance name="default" default="true">
                <elements>
                    <element name="title">
                        <settings>
                            <element-type>text</element-type>
                            <label translate="true">Titel</label>
                            <required>true</required>
                        </settings>
                    </element>
                    <element name="price_left">
                        <settings>
                            <element-type>text</element-type>
                            <label translate="true">Preis links</label>
                            <required>true</required>
                        </settings>
                    </element>
                    <element name="price_right">
                        <settings>
                            <element-type>text</element-type>
                            <label translate="true">Preis rechts</label>
                            <required>true</required>
                        </settings>
                    </element>
                </elements>
            </appearance>
        </appearances>
    </form>
</config>

5. Rendering im Frontend: Block, ViewModel und Preview

Sobald ein Redakteur die Seite speichert, serialisiert Page Builder den Inhalt als HTML mit speziellen data-content-type-Attributen. Beim Aufruf der Seite im Shop übernimmt ein regulärer Magento-Block, der auf diese Attribute reagiert, das eigentliche Rendering. Für Hyvä-Themes bedeutet das: der Renderer-Block liefert ein ViewModel, das Template greift ausschließlich über das ViewModel auf die Daten zu, es gibt keine Knockout-Bindings mehr im Frontend, sondern reines serverseitig gerendertes HTML.

Diese Trennung zwischen Editor-Rendering (Knockout, Master Format) und Frontend-Rendering (PHP-Block, phtml-Template) ist absichtlich so gestaltet. Sie erlaubt es, dass der Editor performant und interaktiv bleibt, während das Frontend keinerlei zusätzliches JavaScript für die Darstellung des Content Type laden muss. Für die Live-Vorschau im Backend-Editor gibt es zusätzlich eine preview.js-Komponente, die optische Details wie Hover-Zustände oder Platzhalter für leere Felder abbildet, ohne dass diese Logik jemals im Frontend ausgeliefert wird.

6. Eigene Appearances und Style-Attribute

Appearances sind alternative Darstellungsvarianten desselben Content Type, zum Beispiel eine kompakte und eine ausführliche Variante der Vergleichskachel. Jede Appearance kann eigene Formularfelder, ein eigenes Master Format und einen eigenen Renderer-Pfad definieren, teilt sich aber den zugrunde liegenden Datentyp. Für Redakteure erscheint die Auswahl der Appearance als einfacher Umschalter im Backend-Panel, technisch steckt dahinter eine komplett andere Rendering-Pipeline.

Style-Attribute wie Innenabstand, Rahmenradius oder Hintergrundfarbe werden idealerweise über das generische Advanced-Panel von Page Builder abgedeckt, statt für jeden Content Type eigene Style-Formularfelder zu bauen. Das reduziert Code-Duplikation erheblich, weil Magento diese generischen Style-Optionen bereits als wiederverwendbare Mixins bereitstellt, die sich per Konfiguration in den eigenen Content Type einhängen lassen.

7. Datenpersistenz: wie Page Builder Content serialisiert wird

Page Builder speichert keinen separaten Datensatz für jeden Content Type, sondern serialisiert den gesamten Seiteninhalt als ein einziges HTML-Fragment in das reguläre content-Feld der CMS-Seite, des CMS-Blocks oder, im Fall dieses Blogs, des Magefan-Blogposts. Jeder Baustein wird dabei als div mit definierten data-content-type- und data-appearance-Attributen sowie base64-kodierten JSON-Daten im data-element-Attribut abgelegt.

Dieses Format hat einen wichtigen Nebeneffekt: Ein Page Builder Content Type, der einmal live geschaltet und in bestehenden Seiten verwendet wurde, kann nicht ohne Weiteres umbenannt oder strukturell verändert werden, ohne bestehenden Content zu brechen. Migrations-Skripte, die alte data-content-type-Werte auf neue Namen umschreiben, sind der einzig saubere Weg, wenn ein Content Type nachträglich umstrukturiert werden muss.

# Inspect stored Page Builder markup for a given CMS page or blog post
bin/magento cms:page:content:show 42 | grep -o 'data-content-type="[^"]*"' | sort -u

# Find all pages/blocks still using a legacy content type before renaming it
bin/mysql -e "SELECT page_id, identifier FROM cms_page
  WHERE content LIKE '%data-content-type=\"comparison_tile\"%'"

8. Validierung, Migration und Abwärtskompatibilität

Eigene Content Types sollten serverseitige Validierung nicht dem Formular allein überlassen. Ein Renderer-Block prüft beim Rendern zusätzlich, ob Pflichtfelder tatsächlich gefüllt sind, und liefert bei fehlenden Daten einen definierten Fallback statt einer kaputten Darstellung. Das ist besonders relevant, wenn Content über einen CSV-Import oder eine externe Migration eingespielt wird, wo die Backend-Formularvalidierung nie greift.

Bei strukturellen Änderungen an einem bestehenden Page Builder Content Type, etwa dem Hinzufügen eines neuen Pflichtfelds, hilft ein Data Patch, der bestehende Content-Datensätze durchsucht und die base64-kodierten Element-Daten um den neuen Feldwert mit sinnvollem Default ergänzt. Ohne diesen Schritt zeigen ältere Seiten den neuen Baustein-Teil einfach leer an, was in der Praxis oft erst durch eine Redakteur-Beschwerde auffällt.

9. Content Types im direkten Vergleich

Nicht jede Anforderung rechtfertigt einen komplett neuen Page Builder Content Type. Häufig lässt sich dieselbe Aufgabe auch mit einer neuen Appearance eines bestehenden Typs oder einem CMS-Block mit Widget lösen. Die folgende Übersicht hilft bei der Entscheidung, welcher Ansatz für welchen Anwendungsfall der richtige ist.

Wer regelmäßig neue Bausteine mit gleichem Datenmodell braucht, sollte in eine gemeinsame Basisklasse investieren, von der mehrere Content Types erben. So teilen sich etwa eine Vergleichskachel und eine Feature-Kachel dieselbe Validierungslogik und denselben Renderer-Unterbau, nur das Formular und das Template unterscheiden sich. Diese Governance über mehrere Content Types hinweg verhindert, dass jedes neue Modul das Rad komplett neu erfindet.

10. Zusammenfassung

Ein eigener Page Builder Content Type lohnt sich immer dann, wenn ein Redaktionsteam wiederholt dieselbe strukturierte Datenkombination benötigt, die mit den Standard-Bausteinen nicht abbildbar ist. Die vier Kernbestandteile, content_type.xml, Master Format, Formular-Konfiguration und Frontend-Renderer, greifen dabei sauber getrennt ineinander: die Deklaration meldet den Baustein an, das Master Format sorgt für die Live-Vorschau im Editor, das Formular sammelt die Redakteurs-Eingaben, und der Renderer liefert das performante Frontend-Markup aus.

Wer diese Trennung respektiert und Appearances sowie generische Style-Optionen konsequent wiederverwendet, baut Content Types, die über Jahre wartbar bleiben, auch wenn sich Anforderungen ändern. Migrations-Patches für strukturelle Änderungen und serverseitige Validierung im Renderer runden ein robustes Setup ab, das Redakteuren echte Gestaltungsfreiheit gibt, ohne die Entwicklung mit Sonderfällen zu überfordern.

11. FAQ: Page Builder Content Types entwickeln