Hyvä Layout-XML: Unterschiede zu Luma

1. Grundprinzip: reguläres Schema, schlankere Konventionen

Die wichtigste Erkenntnis vorweg: Hyvä Layout-XML ist kein eigenes Layout-Format. Hyvä-Themes nutzen exakt dasselbe Layout-XML-Schema wie jedes andere Magento-2-Theme: page_layout-Definitionen, container-Knoten, block-Deklarationen und referenceBlock/referenceContainer-Direktiven funktionieren technisch identisch zu Luma. Die XSD-Validierung, die Handle-Vererbung über default.xml, produktspezifische Handles wie catalog_product_view und die Verarbeitung durch den LayoutMerge-Prozess bleiben unverändert. Wer Magento-Layout-XML aus Luma-Projekten kennt, kennt bereits die Grundmechanik von Hyvä Layout-XML.

Der Unterschied liegt in den Konventionen, die auf diesem gemeinsamen Fundament aufgesetzt werden. Luma-Layout-XML ist historisch stark mit Knockout.js, UI-Komponenten und RequireJS-Modulverweisen verwoben, weil das Luma-Frontend clientseitige Interaktivität über diese Schichten abbildet. Hyvä Layout-XML verzichtet auf all das, weil Hyvä-Templates Interaktivität direkt über Alpine.js im Template selbst lösen, ohne dass das Layout-XML JavaScript-Komponentenbäume beschreiben muss. Das Ergebnis: kürzere, leichter lesbare Layout-Dateien, die sich fast ausschließlich auf Struktur, Blockzuordnung und Template-Referenzen konzentrieren.

Für Entwickler, die von Luma-Projekten zu Hyvä wechseln, bedeutet das vor allem ein Umlernen von Gewohnheiten, nicht von Syntax. Die folgenden acht Abschnitte gehen die konkreten Unterschiede systematisch durch, von wegfallenden XML-Knoten bis zu neuen Argumentkonventionen, die in jedem Hyvä Layout-XML-Snippet konsequent auftauchen sollten.

2. Wegfall von jsLayout und UI-Component-Blöcken

In Luma-Layout-XML taucht bei interaktiven Bereichen regelmäßig das Argument jsLayout auf. Es beschreibt einen Baum aus UI-Komponenten, die von Magento_Ui/js/core/app zur Laufzeit im Browser instanziiert werden, inklusive Konfiguration, Kind-Komponenten und Datenbindungen über Knockout.js. Diese Struktur ist mächtig, aber auch schwer zu debuggen: Fehler tauchen erst im Browser auf, die Konfiguration ist tief verschachtelt und jede Änderung erfordert Kenntnis der jeweiligen UI-Component-Klasse. In Hyvä Layout-XML kommt dieses Argument praktisch nie vor, weil Hyvä-Themes keine Magento-UI-Components und kein Knockout.js laden.

Stattdessen verwendet Hyvä Layout-XML eine einfache <block>-Deklaration mit template-Attribut und einem ViewModel-Argument. Die gesamte Logik, die in Luma über verschachtelte jsLayout-Arrays und separate JavaScript-Dateien verteilt war, wandert in PHP-ViewModels und das zugehörige PHTML-Template. Die folgende Gegenüberstellung zeigt ein typisches Luma-Muster: ein Block, der eine UI-Komponente für einen Slider konfiguriert.

<!-- Luma: catalog_product_view.xml - Block mit jsLayout und UI-Component-Konfiguration -->
<referenceBlock name="product.info.details">
    <block class="Magento\Catalog\Block\Product\View"
           name="product.info.additional"
           template="Magento_Catalog::product/view/additional.phtml">
        <arguments>
            <argument name="jsLayout" xsi:type="array">
                <item name="components" xsi:type="array">
                    <item name="additionalInfoSlider" xsi:type="array">
                        <item name="component" xsi:type="string">Magento_Catalog/js/view/product-additional-slider</item>
                        <item name="config" xsi:type="array">
                            <item name="autoplay" xsi:type="boolean">false</item>
                            <item name="slidesPerView" xsi:type="number">3</item>
                        </item>
                    </item>
                </item>
            </argument>
        </arguments>
    </block>
</referenceBlock>

Dieses jsLayout-Konstrukt zwingt jeden, der den Block versteht will, gleichzeitig Layout-XML, ein RequireJS-Modul und Knockout-Bindings im Template zu lesen. Ein sauberes Hyvä Layout-XML-Äquivalent ersetzt das komplett durch ein ViewModel-Argument, siehe Abschnitt 4 und das vollständige Vorher/Nachher-Beispiel in Abschnitt 8. Wichtig für die Migration: Wer jsLayout-Reste in einem Hyvä-Theme findet, etwa aus einer Drittanbieter-Extension mit Luma-Fokus, sollte diese konsequent durch Block+Template+ViewModel ersetzen, statt sie mitzuschleppen.

3. RequireJS-Mixins und requirejs-config.js entfallen

Ein zweites, eng verwandtes Merkmal von Luma-Layout-XML sind Referenzen auf RequireJS-Module und Mixins. Häufig findet man in Luma-Themes Layout-Handles, die zusätzliche <script>-Knoten im <head> einfügen, um sicherzustellen, dass ein bestimmtes RequireJS-Modul geladen wird, oder Verweise, die im Zusammenspiel mit requirejs-config.js Mixins auf Kernmodule wie Magento_Catalog/js/product/list registrieren. Diese Kombination aus Layout-XML und JavaScript-Modulkonfiguration ist die technische Grundlage für nahezu jede interaktive Komponente in Luma.

Hyvä Layout-XML enthält solche Verweise so gut wie nie. Es gibt keine requirejs-config.js-Datei, die in Hyvä-Themes eine vergleichbare Rolle spielt, weil Hyvä bewusst ohne RequireJS als Modul-Loader für Frontend-Interaktivität auskommt. Alpine.js-Komponenten werden direkt im Template über x-data deklariert und benötigen keine Modulregistrierung, keinen Mixin-Mechanismus und keinen zusätzlichen Layout-Knoten, der ein Skript nachlädt. Das bedeutet konkret: Ein Layout-XML-Snippet, das in Luma zwingend zusammen mit einer requirejs-config.js-Änderung ausgeliefert wurde, hat in Hyvä oft gar keine Entsprechung mehr, weil die Funktionalität direkt im PHTML-Template landet.

Wichtig bei der Bewertung bestehender Layout-Dateien: Findet sich in einem vermeintlichen Hyvä Layout-XML noch ein <script src="...">-Knoten, der auf ein RequireJS-Modul zeigt, ist das fast immer ein Hinweis auf unvollständig portierten Luma-Code. Ausnahmen bestätigen die Regel nur bei sehr spezifischen Drittanbieter-Bibliotheken, die selbst kein Alpine.js-Äquivalent anbieten, etwa manche Zahlungs-SDKs, die zwingend über einen globalen Script-Tag eingebunden werden müssen.

4. Block-Argument-Konvention: view_model als Standard

Die zentrale Namenskonvention in Hyvä Layout-XML ist das Argument view_model. Jede Klasse, die Magento\Framework\View\Element\Block\ArgumentInterface implementiert, wird im Block über genau dieses Argument referenziert, unabhängig davon, ob es sich um Produktdaten, Kategorie-Informationen oder eine reine Utility-Klasse handelt. Diese Konvention ist in der Hyvä-Community fest etabliert: Templates greifen im PHTML-Code konsistent über $block->getViewModel() auf die Instanz zu, weil Hyvä_Theme die Template-Blockklasse um genau diese Zugriffsmethode erweitert.

In Luma-Layout-XML gibt es keine vergleichbar konsequente Namenskonvention für ArgumentInterface-Implementierungen. Argumentnamen variieren dort stark von Modul zu Modul, weil ViewModels in Luma eine untergeordnete Rolle spielen und die meiste Logik ohnehin in Block-Klassen oder UI-Components wandert. Hyvä Layout-XML macht view_model zum Standardnamen, was Konsistenz über das gesamte Theme herstellt: Jeder Entwickler, der ein neues Layout-XML-Fragment liest, weiß sofort, dass argument name="view_model" auf die zentrale PHP-Logik dieses Blocks verweist.

<!-- Hyvä: catalog_product_view.xml - Standardkonvention "view_model" -->
<referenceBlock name="product.info.details">
    <block class="Magento\Framework\View\Element\Template"
           name="product.info.additional"
           template="Mironsoft_Catalog::product/view/additional.phtml">
        <arguments>
            <argument name="view_model" xsi:type="object">Mironsoft\Catalog\ViewModel\Product\AdditionalInfo</argument>
        </arguments>
    </block>
</referenceBlock>

Bemerkenswert an diesem Muster ist die generische Blockklasse: In sehr vielen Hyvä Layout-XML-Deklarationen genügt Magento\Framework\View\Element\Template als Blockklasse, weil sämtliche fachliche Logik im ViewModel steckt und nicht im Block selbst. Das reduziert die Zahl eigener Blockklassen im Theme drastisch. Mehrere view_model-Argumente lassen sich zudem über einen zusammengesetzten ViewModel kombinieren, der selbst wiederum mehrere Einzel-ViewModels im Konstruktor injiziert bekommt, sodass ein Template mehrere fachliche Zuständigkeiten über ein einziges Argument bündeln kann.

5. Template-Overrides via Layout-XML

Auch beim Überschreiben von Templates zeigt sich ein Unterschied in der Schreibweise, wenn auch ein kleinerer als bei jsLayout. Klassisches Luma-Layout-XML nutzt fast durchgängig die <action method="setTemplate">-Syntax innerhalb eines referenceBlock-Knotens, um einem bestehenden Block ein anderes Template zuzuweisen. Diese Schreibweise funktioniert technisch weiterhin, auch in Hyvä Layout-XML, weil sie Teil des allgemeinen Layout-XML-Schemas ist und nicht Hyvä-spezifisch abgeschafft wurde.

In modernem Hyvä Layout-XML wird jedoch überwiegend die kompaktere Kurzschreibweise bevorzugt: das template-Attribut direkt am referenceBlock-Knoten. Diese Schreibweise steht seit einigen Magento-Versionen zur Verfügung, wird in Luma-Projekten aber selten konsequent genutzt, während Hyvä-Themes und die Hyvä-Community-Dokumentation sie als bevorzugte Form etablieren, weil sie weniger verschachtelten XML-Code erzeugt und auf einen Blick erkennbar ist. Wie das gewählte Template anschließend über die Fallback-Kette der Theme-Vererbung aufgelöst wird, ist ein eigenständiges Thema und wird hier bewusst nicht vertieft.

<!-- Ältere Schreibweise: expliziter action-Knoten -->
<referenceBlock name="product.info.overview">
    <action method="setTemplate">
        <argument name="template" xsi:type="string">Magento_Catalog::product/view/description.phtml</argument>
    </action>
</referenceBlock>

<!-- Hyvä-übliche Kurzschreibweise: template als Attribut -->
<referenceBlock name="product.info.overview" template="Mironsoft_Catalog::product/view/description.phtml"/>

Beide Varianten sind in Hyvä Layout-XML gültig und produzieren dasselbe Ergebnis. Die Kurzschreibweise wird bevorzugt, weil sie weniger Zeilen benötigt und sich bei mehreren Template-Overrides in derselben Datei deutlich übersichtlicher liest, insbesondere wenn ein Theme viele referenceBlock-Anpassungen in einer einzigen catalog_product_view.xml bündelt.

6. Container-Struktur bleibt kompatibel zu Luma

Ein wichtiger, oft unterschätzter Punkt: Die Container-Struktur in Hyvä Layout-XML bleibt zu einem großen Teil identisch mit der von Luma. Container-Namen wie page.main.title, content, sidebar.main, sidebar.additional, header.container oder columns existieren in Hyvä-Themes unter denselben Bezeichnern wie in Luma. Das ist kein Zufall, sondern eine bewusste Design-Entscheidung des Hyvä-Themes-Teams, um die Kompatibilität mit Drittanbieter-Modulen zu maximieren.

Viele Magento-Extensions liefern eigene Layout-XML-Updates aus, die sich auf diese Container-Namen beziehen, etwa um einen zusätzlichen Block in sidebar.additional einzuhängen oder einen Banner in content.top zu platzieren. Weil Hyvä Layout-XML dieselben Containernamen verwendet, funktionieren viele solcher Drittanbieter-Layout-Updates ohne Anpassung, selbst wenn die Extension ursprünglich nur für Luma entwickelt wurde. Das reduziert den Migrationsaufwand erheblich, weil nicht jede einzelne Extension ein eigenes Hyvä-Layout-Update benötigt, nur um an der richtigen Stelle im Seitengerüst zu erscheinen.

Die eigentlichen Unterschiede liegen also nicht in der Struktur des Seitengerüsts, sondern in dem, was innerhalb dieser Container an Blöcken deklariert wird: statt UI-Component-lastiger Blöcke mit jsLayout stehen in Hyvä Layout-XML schlanke Template-plus-ViewModel-Kombinationen. Ein Entwickler, der die Container-Namen aus einem Luma-Projekt kennt, kann sie in einem Hyvä-Layout-Update fast unverändert weiterverwenden.

7. CSS/JS-Asset-Referenzen im Layout

Luma-Layout-XML referenziert einzelne CSS- und JS-Assets sehr häufig direkt im Layout, meist über <css src="Magento_Catalog::css/styles.css"/> oder <script src="Magento_Catalog::js/product-gallery.js"/> innerhalb der Head-Handles. Jedes Modul kann so eigene Bundle-Assets nachladen, was in Summe zu vielen einzelnen HTTP-Requests und einer schwer überschaubaren Menge an CSS-Regeln aus unterschiedlichen Quellen führt.

Hyvä Layout-XML vermeidet diese Praxis fast vollständig. Der zentrale Tailwind-Build erzeugt eine einzige, gepurgte CSS-Datei für das komplette Theme, sodass es in aller Regel keinen Grund gibt, im Layout-XML einen zusätzlichen <css src="...">-Knoten für ein einzelnes Modul einzufügen. Neue Utility-Klassen werden stattdessen einfach im Template verwendet und erscheinen automatisch im nächsten Tailwind-Build, weil der Build-Prozess die Templates nach verwendeten Klassen durchsucht.

Auch bei JavaScript gilt dasselbe Prinzip: Statt zusätzlicher <script src="...">-Referenzen im Layout-XML für jede kleine Interaktion nutzt Hyvä Layout-XML die bereits im Theme geladene Alpine.js-Instanz. Ein neues interaktives Element bekommt sein Verhalten über x-data direkt im Template, ohne dass eine zusätzliche Layout-Zeile ein weiteres Skript einbindet. Das hält die Anzahl der Assets klein und macht das Laden der Seite vorhersehbarer, weil nicht jedes Modul sein eigenes Mini-Bundle beisteuert.

8. Vorher/Nachher: jsLayout wird zu view_model

Um die bisher beschriebenen Unterschiede an einem durchgängigen Beispiel zu zeigen, folgt eine vollständige Transformation eines realistischen Layout-Handles. Das Szenario: ein Karussell mit verwandten Produkten, das in Luma über eine UI-Komponente mit jsLayout realisiert wird und in Hyvä Layout-XML zu einer einfachen Block-Template-ViewModel-Kombination wird.

<!-- VORHER: Luma - catalog_product_view.xml -->
<?xml version="1.0"?>
<page layout="1column" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="Magento\Catalog\Block\Product\ProductList\Related"
                   name="catalog.product.related"
                   template="Magento_Catalog::product/list/related.phtml">
                <arguments>
                    <argument name="jsLayout" xsi:type="array">
                        <item name="components" xsi:type="array">
                            <item name="relatedCarousel" xsi:type="array">
                                <item name="component" xsi:type="string">Magento_Catalog/js/view/related-carousel</item>
                                <item name="config" xsi:type="array">
                                    <item name="itemsPerRow" xsi:type="number">4</item>
                                    <item name="enableAutoplay" xsi:type="boolean">true</item>
                                </item>
                            </item>
                        </item>
                    </argument>
                </arguments>
            </block>
        </referenceContainer>
    </body>
</page>

<!-- NACHHER: Hyvä Layout-XML - catalog_product_view.xml -->
<?xml version="1.0"?>
<page layout="1column" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="Magento\Catalog\Block\Product\ProductList\Related"
                   name="catalog.product.related"
                   template="Mironsoft_Catalog::product/list/related.phtml">
                <arguments>
                    <argument name="view_model" xsi:type="object">Mironsoft\Catalog\ViewModel\Product\RelatedCarousel</argument>
                </arguments>
            </block>
        </referenceContainer>
    </body>
</page>

Die Blockklasse Magento\Catalog\Block\Product\ProductList\Related bleibt in diesem Beispiel bewusst erhalten, weil sie die Produktkollektion lädt, die das ViewModel anschließend konsumiert. Entscheidend ist der Wegfall des kompletten jsLayout-Arrays zugunsten des einzeiligen view_model-Arguments. Das zugehörige PHTML-Template zeigt, wie Hyvä Layout-XML und Template zusammenspielen: Das Template ruft getViewModel() auf dem Block auf und rendert die Karussell-Logik direkt mit Alpine.js, ohne ein separates RequireJS-Modul zu benötigen.

<?php
/**
 * @var \Magento\Framework\View\Element\Template $block
 * @var \Mironsoft\Catalog\ViewModel\Product\RelatedCarousel $viewModel
 */
$viewModel = $block->getViewModel();
$relatedProducts = $viewModel->getRelatedProducts();
?>
<?php if (!empty($relatedProducts)): ?>
<div class="mt-10" x-data="{ active: 0, itemsPerView: 4 }">
    <h3 class="text-xl font-bold text-gray-900 mb-4"><?= $block->escapeHtml(__('Related Products')) ?></h3>
    <div class="grid grid-cols-2 sm:grid-cols-4 gap-4">
        <?php foreach ($relatedProducts as $product): ?>
        <a href="<?= $block->escapeUrl($product->getProductUrl()) ?>"
           class="block rounded-lg border border-gray-200 p-3 hover:shadow-md transition-shadow">
            <span class="block text-sm font-semibold text-gray-800"><?= $block->escapeHtml($product->getName()) ?></span>
        </a>
        <?php endforeach; ?>
    </div>
</div>
<?php endif; ?>

Diese Gegenüberstellung zeigt das Grundmuster, das sich in praktisch jeder Migration von Luma-Layout-XML zu Hyvä Layout-XML wiederholt: jsLayout-Array raus, view_model-Argument rein, JavaScript-Logik wandert aus separaten RequireJS-Modulen direkt ins Template als Alpine.js-Ausdruck.

9. Häufige Fehler beim Schreiben von Hyvä Layout-XML

In der Praxis wiederholen sich beim Schreiben von Hyvä Layout-XML einige typische Fehler, meist weil Entwickler unbewusst Luma-Reflexe übernehmen. Der häufigste: kopierte jsLayout-Argumente aus einer Luma-Referenzimplementierung oder einer alten Drittanbieter-Extension, die niemand entfernt hat. Das Argument wird von Hyvä-Templates schlicht ignoriert, weil kein Code danach sucht, bleibt aber als toter, verwirrender Ballast in der Datei liegen und suggeriert Funktionalität, die nicht existiert.

Ein zweiter häufiger Fehler ist die falsche Wahl der Blockklasse. Statt der generischen Magento\Framework\View\Element\Template-Klasse mit ViewModel-Argument wird eine spezifische, oft aus Luma kopierte Blockklasse verwendet, obwohl die eigentliche Logik längst im ViewModel steckt. Das führt zu doppelter Verantwortlichkeit: Ein Teil der Logik liegt im Block, ein Teil im ViewModel, ohne klare Trennung. Sauberes Hyvä Layout-XML hält sich strikt an die Kombination aus generischem Block, Template und einem oder mehreren ViewModel-Argumenten.

Ein dritter Fehler betrifft die Argumentbenennung selbst: statt der Konvention view_model tauchen in migriertem Code manchmal Namen wie data_provider, helper oder modul-spezifische Bezeichner auf. Das funktioniert technisch, weil das Argument einfach einen anderen Namen trägt, bricht aber mit der Lesbarkeit, die Hyvä Layout-XML gerade durch Konsistenz gewinnt. Wer in einem Theme mehrere Namenskonventionen mischt, zwingt jeden neuen Entwickler dazu, für jeden Block erneut nachzuschlagen, wie der ViewModel-Zugriff im jeweiligen Template gelöst ist.

Diese Tabelle fasst die Kernunterschiede zusammen, die in nahezu jedem Hyvä Layout-XML-Review auftauchen. Wer diese fünf Muster konsequent anwendet, vermeidet die typischen Stolperfallen beim Umstieg von Luma und schreibt Layout-XML, das sich in jedem Hyvä-Projekt gleich liest.

10. Zusammenfassung

Hyvä Layout-XML ist im Kern dasselbe Magento-Layout-Schema wie in Luma, unterscheidet sich aber grundlegend in den Konventionen, die auf diesem Schema aufsetzen. Der Wegfall von jsLayout und UI-Component-Argumenten ist der auffälligste Unterschied, gefolgt vom kompletten Verzicht auf RequireJS-Mixins und requirejs-config.js-Referenzen im Layout. An deren Stelle tritt die view_model-Argumentkonvention, die jede ArgumentInterface-Implementierung unter demselben, vorhersehbaren Namen im Block verankert.

Template-Overrides funktionieren in Hyvä Layout-XML weiterhin über <action method="setTemplate">, werden aber überwiegend durch die kompaktere template-Attribut-Schreibweise ersetzt. Die Container-Struktur bleibt weitgehend identisch zu Luma, was die Kompatibilität mit Drittanbieter-Layout-Updates erhält, während einzelne CSS- und JS-Asset-Referenzen im Layout fast vollständig zugunsten des zentralen Tailwind-Builds und der bereits geladenen Alpine.js-Instanz entfallen. Das Vorher/Nachher-Beispiel mit dem Related-Products-Karussell zeigt, wie sich diese Prinzipien in einer echten Layout-Datei kombinieren lassen.

11. FAQ: Hyvä Layout-XML