</>
<layout>
Frontend-Architektur & Magento Internals

Magento Layout XML
vollständig erklärt

Handles, Blöcke, Container, Direktiven – alle Layout-Konzepte in Magento 2 mit konkreten XML-Beispielen, Schritt-für-Schritt erklärt für Entwickler und Frontend-Architekten.

⏱ 20 Min. Lesezeit Frontend-Architektur ⚙️ Magento 2 Tutorial

Was ist das Magento Layout-System?

Das Layout-System ist das Herzstück der Magento 2 Frontend-Architektur. Anstatt Seitenstrukturen hart in PHP-Templates zu kodieren, beschreibt Magento den Aufbau jeder Seite deklarativ in XML-Dateien – den sogenannten Layout XML Files. Dieses System trennt Präsentation von Logik und ermöglicht eine nie dagewesene Flexibilität: Module können bestehende Layouts erweitern, überschreiben oder ergänzen, ohne den Kern-Code anzutasten.

In diesem Tutorial lernen Sie alle Konzepte, Direktiven und Muster des Magento Layout-Systems kennen – von einfachen Block-Definitionen bis hin zu komplexen Layout-Updates für individuelle Seiten.

Inhaltsverzeichnis
  1. 1. Grundkonzepte des Layout-Systems
  2. 2. Dateistruktur & Naming Conventions
  3. 3. Layout Handles
  4. 4. Container
  5. 5. Blöcke (Blocks)
  6. 6. Alle Layout-Direktiven
  7. 7. Layouts erweitern
  8. 8. UI Components in Layouts
  9. 9. Praxisbeispiele
  10. 10. Vergleich mit anderen Ansätzen
  11. 11. Zusammenfassung
  12. 12. FAQ

1. Grundkonzepte des Magento Layout-Systems

Das Magento Layout-System basiert auf einem dreischichtigen Prinzip: Handles definieren den Kontext (welche Seite), Container strukturieren den Seitenaufbau (wo etwas erscheint), und Blöcke liefern den eigentlichen Inhalt (was erscheint). Alle drei Ebenen werden in XML-Dateien beschrieben und zur Laufzeit zu einem Rendering Tree zusammengeführt.

Magento 2 Layout-System – Architekturübersicht HANDLES (Kontext / Seite) default catalog_product_view checkout_cart_index cms_page_view customer_account_index CONTAINER (Struktur / Wo) root header content sidebar.main footer BLOCKS (Inhalt / Was) Magento\Theme\Block\Html\Header Catalog\Block\Product\View Checkout\Block\Cart Cms\Block\Page Custom\Block\Widget Rendering Pipeline: Handle → Container → Block → Template (.phtml)

Der Rendering-Prozess funktioniert wie folgt: Magento lädt alle XML-Dateien, die dem aktuellen Request-Kontext entsprechen, fusioniert sie zu einem einzigen XML-Baum und erzeugt daraus den Render-Tree. Jeder Knoten in diesem Baum ist entweder ein Container (rein strukturell) oder ein Block (mit PHP-Klasse und Template). Die Templates sind .phtml-Dateien, die HTML mit PHP-Aufrufen mischen.

2. Dateistruktur & Naming Conventions

Layout-XML-Dateien werden nach festen Konventionen benannt und in vordefinierten Verzeichnissen abgelegt. Der Dateiname entspricht dabei direkt dem Layout Handle, den er konfiguriert.

Verzeichnisstruktur eines Moduls

Naming Convention für Layout-Dateien

Der Dateiname setzt sich aus dem Route-Name, dem Controller-Namen und dem Action-Namen zusammen – jeweils mit Unterstrich verbunden und in Kleinbuchstaben:

Layout-Datei Naming Convention Dateiname Route Controller Action catalog_product_view.xml catalog product view checkout_cart_index.xml checkout cart index customer_account_login.xml customer account login cms_page_view.xml cms page view default.xml — (alle Seiten) — —

3. Layout Handles – Der Kontext-Mechanismus

Ein Layout Handle ist ein Bezeichner, der bestimmt, welche Layout-Anweisungen für eine bestimmte Seite oder einen bestimmten Zustand geladen werden. Magento aktiviert für jeden Request mehrere Handles gleichzeitig – alle passenden Layout-XML-Dateien werden zusammengeführt und übereinander gelegt.

Wie Handles aktiviert werden

Handles werden vom Action Controller oder von PHP-Code dynamisch hinzugefügt. Der default-Handle ist immer aktiv. Route-basierte Handles werden automatisch aus dem Request-Pfad abgeleitet.

Wichtige System-Handles in Magento 2

Custom Handles für Bedingungen

4. Container – Die strukturellen Bausteine

Container sind reine Strukturelemente im Layout-Tree. Sie erzeugen kein HTML von sich aus (außer dem optionalen htmlTag-Attribut), sondern dienen als Ankerpunkte zum Einsetzen von Blöcken. Container können HTML-Wrapper-Tags wie <div>, <ul> oder <section> rendern.

Container-Definition

Container-Attribute im Überblick

Container-Attribute Attribut Typ Beschreibung name string (required) Eindeutiger Bezeichner im Layout-Tree label string Admin-Label für UI-Verwaltung htmlTag div, aside, ul … HTML-Wrapper-Tag (optional) htmlClass string CSS-Klassen für den HTML-Wrapper htmlId string HTML id-Attribut für den Wrapper before / after name oder "-" Positionierung vor/nach einem anderen Element

5. Blöcke (Blocks) – Die Inhalts-Einheiten

Blöcke sind die Arbeitspferde des Magento Layout-Systems. Jeder Block verbindet eine PHP-Klasse (für Logik und Datenzugriff) mit einem Template (für die HTML-Ausgabe). Blöcke können ineinander verschachtelt werden – ein Block kann Kindblöcke haben, die in seinem Template per $block->getChildHtml('name') eingebettet werden.

Block-Definition

Argument-Typen im Überblick

Block-Klassen und Vererbung

Eigene Block-Klassen erben typischerweise von \Magento\Framework\View\Element\Template (für einfache Template-Blöcke) oder von spezialisierten Basisklassen wie \Magento\Catalog\Block\Product\View. Seit Magento 2.2 empfiehlt sich das ViewModel-Pattern als saubere Alternative zur Logik in Block-Klassen.

6. Alle Layout-Direktiven im Detail

Magento Layout XML kennt eine klar definierte Menge an Direktiven – XML-Elemente mit spezieller Bedeutung. Das Verständnis dieser Direktiven ist der Schlüssel zu einem professionellen Layout-Management.

6.1 <page> – Root Element

6.2 <referenceContainer> – Bestehenden Container referenzieren

6.3 <referenceBlock> – Bestehenden Block referenzieren

6.4 <move> – Elemente verschieben

6.5 <update> – Anderen Handle einbinden

6.6 <head> – Ressourcen und Meta-Daten

7. Layouts erweitern – Best Practices

Das Erweitern von Layouts ist das tägliche Handwerk der Magento-Entwicklung. Das Prinzip: Man erstellt keine Kopien bestehender Layout-Dateien, sondern legt eigene XML-Dateien an, die gezielt Änderungen definieren. Magento führt alle passenden XML-Dateien automatisch zusammen.

Schritt-für-Schritt: Block auf Produktseite hinzufügen

Template in einem Theme überschreiben

Neues Layout für eine eigene Route erstellen

Seitenweites Layout ändern (layout.xml)

Die layout.xml Dateien (ohne Handle-Suffix) definieren den generischen Seitenrahmen – die grundlegende Struktur aus Header, Content-Bereich und Footer, die alle Seiten-Layouts teilen.

8. UI Components in Layout-Dateien

Magento 2 kennt neben einfachen Blöcken auch das Konzept der UI Components – wiederverwendbare JavaScript-getriebene Komponenten, die über eigene XML-Dateien konfiguriert werden. Im Layout werden sie über einen speziellen Block-Typ eingebunden.

9. Praxisbeispiele aus dem Magento-Alltag

9.1 Produkt-Badge für Sonderangebote

9.2 Checkout – Schritt-spezifisches Layout

9.3 Kategorie-Seite mit Custom Toolbar

9.4 Layout für mobile Geräte anpassen

10. Magento Layout XML vs. andere Ansätze

Das deklarative XML-Layout-System von Magento ist eine bewusste architektonische Entscheidung. Verglichen mit anderen Frontend-Frameworks und CMS-Lösungen hat es spezifische Stärken und Schwächen.

Vergleich: Layout-Ansätze Ansatz Flexibilität Lernkurve Wartbarkeit Magento Layout XML deklaratives XML-System ★★★★★ ★★☆☆☆ ★★★★☆ WordPress (PHP Templates) Template-Hierarchie ★★★☆☆ ★★★★★ ★★★☆☆ Shopify (Liquid) Template-Engine ★★★☆☆ ★★★★☆ ★★★☆☆ React / Next.js Komponentenbasiert ★★★★★ ★★★☆☆ ★★★★★ Hyvä Theme (Magento) Layout XML + Alpine.js ★★★★★ ★★★☆☆ ★★★★★

Vorteile des Magento Layout XML Systems

  • Modularer Aufbau ohne Core-Änderungen: Jedes Modul bringt seine eigenen Layout-Anpassungen mit, ohne andere Module zu beeinflussen. Upgrades bleiben sicher.
  • Kontextspezifische Layouts: Für jede Seite, jeden Produkttyp oder jeden Kundentyp kann ein eigenes Layout definiert werden – ohne Code-Duplikation.
  • Deklarative Konfiguration: Seitenstruktur ist in XML lesbar und nachvollziehbar – kein PHP-Parsing nötig, um zu verstehen, welche Blöcke wo erscheinen.
  • Caching-Integration: Der aus XML aufgebaute Render-Tree wird vollständig gecacht, was die Performance maximiert.
  • Theme-Vererbung: Themes erben Layouts von Eltern-Themes und überschreiben nur gezielt, was sich ändern soll.

Nachteile und Herausforderungen

  • Steile Lernkurve: Das System ist nicht intuitiv für Einsteiger – die Zusammenhänge zwischen Handles, Containern und Blöcken müssen erst verinnerlicht werden.
  • Debugging-Aufwand: Wenn ein Block nicht erscheint, kann die Ursache an mehreren Stellen liegen: Handle nicht aktiv, Block entfernt von einem anderen Modul, Cache nicht geleert.
  • XML-Merge-Konflikte: Wenn mehrere Module denselben Block manipulieren, können unvorhergesehene Wechselwirkungen entstehen.
  • Performance bei ungecachtem Zustand: Das XML-Parsing und der Tree-Aufbau sind ressourcenintensiv – funktioniert gut nur mit aktivem Cache.

Mironsoft

Magento-Entwicklung & Frontend-Architektur

Magento-Layout professionell umsetzen?

Wir strukturieren Ihre Magento-Frontend-Architektur, entwickeln saubere Layout-Module, optimieren bestehende Themes und schulen Ihr Team in Magento-Best-Practices.

Layout-Architektur

Saubere XML-Strukturen, modulares Design, Theme-Konzeption

Upgrade-Sicherheit

Konflikt-freie Modul-Layouts, Core-Override-Analyse, Code-Review

Hyvä-Entwicklung

Hyvä Theme Implementierung, Alpine.js-Komponenten, TailwindCSS

Kostenlose Erstberatung anfragen Projekt besprechen

11. Zusammenfassung

Das Magento Layout XML System ist ein mächtiges, deklaratives Werkzeug zur Steuerung der Frontend-Architektur. Wer die Grundprinzipien – Handles, Container, Blöcke und Direktiven – einmal verinnerlicht hat, kann Seiten präzise und upgradesicher gestalten. Die Stärke liegt in der Modularität: Jedes Modul bringt seine Layout-Anpassungen mit, ohne andere zu beeinflussen.

Magento Layout XML – Das Wichtigste auf einen Blick

Was sind Handles?

Kontext-Bezeichner, die bestimmen, welche Layout-Anweisungen für eine Seite aktiv sind. Mehrere Handles sind gleichzeitig aktiv und werden gemerged.

Container vs. Block

Container sind strukturell (kein Inhalt), Blöcke liefern Inhalt über PHP-Klasse + Template. Container können optional HTML-Tags rendern.

Hauptdirektiven

referenceBlock, referenceContainer, move, remove, update – mit diesen fünf Direktiven lösen Sie 95% aller Layout-Aufgaben.

Best Practice

Niemals Core-Dateien editieren. Immer über eigene XML-Dateien im Modul oder Theme erweitern. Cache nach Änderungen leeren: bin/magento cache:flush.

12. FAQ: Magento Layout XML

1 Was ist eine Layout XML Datei in Magento 2?
Eine Layout XML Datei in Magento 2 ist eine deklarative Konfigurationsdatei, die beschreibt, welche Blöcke und Container auf einer bestimmten Seite erscheinen und wie sie strukturiert sind. Sie wird nach dem Layout Handle benannt (z.B. catalog_product_view.xml) und im Verzeichnis view/frontend/layout/ eines Moduls oder Themes abgelegt.
2 Was ist der Unterschied zwischen Block und Container?
Ein Container ist ein rein strukturelles Element ohne eigenen Inhalt. Er dient als Ankerpunkt und kann optional ein HTML-Wrapper-Tag rendern. Ein Block ist mit einer PHP-Klasse und einem .phtml-Template verknüpft und erzeugt den eigentlichen HTML-Inhalt der Seite.
3 Wie füge ich einen Block auf einer bestimmten Seite hinzu?
Erstellen Sie eine XML-Datei in view/frontend/layout/, benannt nach dem Handle der Zielseite. Nutzen Sie <referenceContainer name="content"> und definieren Sie darin Ihren Block. Nach Änderungen immer bin/magento cache:flush ausführen.
4 Was ist ein Layout Handle in Magento 2?
Ein Layout Handle ist ein Bezeichner, der den Kontext einer Seite beschreibt. Magento aktiviert für jeden Request mehrere Handles gleichzeitig – z.B. default (immer aktiv) plus seitenspezifische Handles wie catalog_product_view. Alle aktiven Handles werden gemerged. Handles können auch per PHP-Code dynamisch hinzugefügt werden.
5 Wie entferne ich einen Block aus dem Magento-Layout?
Verwenden Sie <referenceBlock name="block.name" remove="true"/>. Alternativ können Sie display="false" nutzen, wenn der Block im Tree erhalten aber nicht gerendert werden soll. Das remove-Attribut ist für dauerhafte Entfernung empfohlen.
6 Was bedeuten die Attribute "before" und "after"?
Diese Attribute steuern die Reihenfolge innerhalb des übergeordneten Containers. before="-" = an erster Stelle, after="-" = an letzter Stelle, before="block.name" = direkt vor dem genannten Block, after="block.name" = direkt danach.
7 Wie übergebe ich Argumente an einen Block?
Nutzen Sie das <arguments>-Element innerhalb des Block-Knotens. Jedes Argument hat einen name und einen xsi:type (string, boolean, number, array, url, object, null). Im Template abrufbar per $block->getData('name') oder dem magischen Getter.
8 Was ist der Unterschied zwischen page_configuration.xsd und generic.xsd?
page_configuration.xsd ist für vollständige Seitenlayouts mit HTML-Rahmen (head + body) – also die meisten Frontend-Layout-Dateien. generic.xsd ist für partielle Layouts ohne vollständigen HTML-Rahmen, z.B. für AJAX-Responses oder als Teil-Layouts, die per <update handle="..."/> eingebunden werden.
9 Wie überschreibe ich ein Template über das Layout?
Referenzieren Sie den Block und übergeben Sie das neue Template als Argument vom Typ string: <argument name="template" xsi:type="string">Vendor_Module::pfad/zum/template.phtml</argument>. Das Format ist ModuleName::relativer/Pfad/ab/templates/.
10 Warum wird mein neuer Block nicht angezeigt?
Häufige Ursachen: (1) Cache nicht geleert → bin/magento cache:flush. (2) Falscher Handle-Name in der Datei. (3) Modul nicht aktiviert. (4) Ein anderes Modul entfernt den Block per remove="true". (5) Der referenzierte Container existiert auf dieser Seite nicht. Zur Diagnose: bin/magento dev:template-hints:enable.