Header und Footer per Hyvä-Layout-XML strukturell anpassen

1. Warum Layout-XML statt Hardcoding im phtml die richtige Wahl ist

Wer Header und Footer in einem Hyvä-Theme direkt im phtml-Template mit festem Markup ausstattet, baut sich eine Falle für das nächste Update: Jede zusätzliche Sektion, jeder neue Menüpunkt und jede Drittmodul-Integration erzwingt eine weitere manuelle Änderung an einer Datei, die eigentlich dem Parent-Theme gehört. Header und Footer per Layout-XML zu strukturieren verschiebt genau diese Entscheidungen aus dem Template in eine deklarative Konfigurationsebene, die Magento nativ versteht und die bei jedem Merge, jedem Update und jeder Erweiterung automatisch respektiert wird.

Der Vorteil zeigt sich vor allem bei der Theme-Vererbung: Ein Child-Theme, das seine Anpassungen über Hyvä-Layout-XML vornimmt, muss kein einziges Parent-Template kopieren. Container-Definitionen, Block-Referenzen und sortOrder-Attribute lassen sich gezielt überschreiben, ohne dass eine vollständige phtml-Kopie im Child-Theme veraltet und beim nächsten Hyvä-Release unbemerkt divergiert. Drittmodule profitieren ebenso: Sie können eigene Blöcke in Header oder Footer einhängen, ohne den Quellcode des Themes überhaupt anzufassen.

Der Unterschied zwischen Hardcoding und einem sauberen Layout-XML-Pattern für Header und Footer lässt sich an typischen Aufgaben direkt ablesen:

2. Die Hyvä-Blockstruktur verstehen: $block->getChildNames() im header.phtml und footer.phtml

Im Hyvä-Default-Theme rendert weder header.phtml noch footer.phtml ein starres HTML-Gerüst. Beide Templates iterieren stattdessen über $block->getChildNames() und rufen für jeden Kindblock $block->getChildBlock($name)->toHtml() auf. Diese Iteration ist der eigentliche Mechanismus, der Header und Footer über Layout-XML überhaupt erst konfigurierbar macht: Jeder Container im Layout-XML wird zu einer Named-Slot-Position, in die beliebig viele Blöcke eingehängt werden können, ohne dass die Template-Datei selbst geändert werden muss.

Wer diese Blockstruktur verstanden hat, erkennt sofort, warum Hardcoding im phtml so schädlich ist: Ein hart eingefügtes <div> mit fixem Markup umgeht die Container-Iteration komplett und wird bei der nächsten Umstrukturierung des Headers zum Fremdkörper. Die konsequente Nutzung von getChildNames() bedeutet umgekehrt: Jede neue Sektion, jeder neue Slot im Header oder Footer entsteht ausschließlich über zusätzliche Container- und Block-Definitionen in der Layout-XML, niemals durch eine Änderung an der Ausgabe-Logik selbst.

Dieses Muster erklärt auch, warum das Hyvä-Block-System bewusst nicht ersetzt werden sollte, selbst wenn eine eigene Iterationslogik verlockend wirkt. Sobald ein Theme getChildNames() umgeht und Kindblöcke stattdessen fest referenziert, bricht die Erweiterbarkeit für jedes Drittmodul, das sich künftig per Layout-XML in Header oder Footer einhängen will. Die Iteration bleibt der stabile Vertrag zwischen Template und Layout-Schicht.

3. Einen eigenen Block per Layout-XML im Header hinzufügen

Um einen eigenen Block im Header zu platzieren, wird in default.xml des eigenen Moduls oder Themes ein neuer <block> als Kind des Header-Containers referenziert. Der Container header.container aus dem Hyvä-Default-Theme nimmt beliebig viele Kindblöcke auf, solange diese per referenceContainer korrekt adressiert werden. Das folgende Beispiel zeigt, wie ein eigener Store-Switcher-Block per Layout-XML im Header ergänzt wird, ohne dass header.phtml auch nur eine Zeile ändern muss.

Wichtig ist die Namenskonvention: Der name-Wert des Blocks muss eindeutig sein, da er später für Positionierungs-Anweisungen, ACL-Sichtbarkeit oder gezielte Entfernung referenziert wird. Das template-Attribut verweist auf ein eigenes phtml, das nur für diesen einen Slot zuständig ist - ein klarer Vorteil gegenüber einem monolithischen header.phtml, das mit jeder neuen Anforderung wächst. Das Argument view_model koppelt den Block sofort an eine ArgumentInterface-Klasse, siehe Abschnitt 5.

<!-- app/design/frontend/Mironsoft/default/Magento_Theme/layout/default.xml -->
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="header.container">
            <!-- Custom block added declaratively, no phtml override needed -->
            <block class="Magento\Framework\View\Element\Template"
                   name="mironsoft.header.store-switcher"
                   template="Mironsoft_HeaderTools::header/store-switcher.phtml"
                   after="header.panel.wrapper">
                <arguments>
                    <argument name="view_model" xsi:type="object">Mironsoft\HeaderTools\ViewModel\StoreSwitcher</argument>
                </arguments>
            </block>
        </referenceContainer>
    </body>
</page>

4. Positionierung und Reihenfolge steuern

Sobald mehrere eigene Blöcke im Header oder Footer landen, entscheidet die richtige Kombination aus before, after und sortOrder darüber, ob das Ergebnis vorhersehbar bleibt. before und after referenzieren den Namen eines bestehenden Geschwisterblocks und ordnen den neuen Block relativ dazu ein, während sortOrder eine absolute Reihenfolge innerhalb desselben Containers vorgibt, wenn mehrere Blöcke gleichzeitig hinzugefügt werden. Diese Attribute sind der Kern jeder sauberen Layout-XML-Positionierung für Header und Footer, weil sie Reihenfolge deklarativ statt über die Template-Struktur selbst festlegen.

Container-Verschachtelung ist das zweite Werkzeug: Ein eigener <container> innerhalb von header.panel.wrapper gruppiert mehrere zusammengehörige Blöcke zu einer Einheit, die sich als Ganzes verschieben, entfernen oder per Bedingung ausblenden lässt. Wer Header und Footer per Layout-XML strukturiert, sollte gruppierte Container gegenüber vielen einzelnen, lose verstreuten Blöcken bevorzugen, weil sich so ganze Funktionsblöcke - etwa "Trust-Badges plus Store-Switcher" - als eine Einheit handhaben lassen.

<!-- app/design/frontend/Mironsoft/default/Magento_Theme/layout/default.xml -->
<referenceContainer name="header.container">
    <block class="Magento\Framework\View\Element\Template"
           name="mironsoft.header.trust-badges"
           template="Mironsoft_HeaderTools::header/trust-badges.phtml"
           before="header.panel.wrapper"
           sortOrder="5"/>
    <block class="Magento\Framework\View\Element\Template"
           name="mironsoft.header.store-switcher"
           template="Mironsoft_HeaderTools::header/store-switcher.phtml"
           after="mironsoft.header.trust-badges"
           sortOrder="10"/>
</referenceContainer>

<!-- Nested container groups related blocks as one movable, removable unit -->
<referenceContainer name="header.panel.wrapper">
    <container name="header.panel.custom"
               as="header_panel_custom"
               label="Custom Header Panel Group"
               htmlTag="div"
               htmlClass="header-panel-custom"/>
</referenceContainer>

5. ViewModels statt Block-Klassen für Header- und Footer-Logik nutzen

Für Header- und Footer-spezifische Logik, etwa Login-Status oder Store-Switcher-Daten, ist eine eigene Block-Klasse selten nötig. Stattdessen genügt in den meisten Fällen Magento\Framework\View\Element\Template als generische Blockklasse, während die fachliche Logik in einem ViewModel steckt, das ArgumentInterface implementiert und per view_model-Argument im Layout-XML injiziert wird. Dieses Muster ist bei Header und Footer per Layout-XML besonders wertvoll, weil ein ViewModel ohne Magento-Block-Overhead in Unit-Tests instanziiert und geprüft werden kann.

Constructor Property Promotion hält solche ViewModels kompakt: Abhängigkeiten wie CustomerSession oder StoreManagerInterface werden direkt im Konstruktor als private readonly-Eigenschaften deklariert, ohne redundante Zuweisungen im Methodenkörper. Jede öffentliche Methode braucht laut Projektkonvention einen vollständigen PHPDoc-Block mit Beschreibung, @param und @return. Das folgende Beispiel liest Login-Status und Store-Liste für den Header aus.

<?php

declare(strict_types=1);

namespace Mironsoft\HeaderTools\ViewModel;

use Magento\Customer\Model\Session as CustomerSession;
use Magento\Framework\View\Element\Block\ArgumentInterface;
use Magento\Store\Api\Data\StoreInterface;
use Magento\Store\Model\StoreManagerInterface;

/**
 * ViewModel providing header-specific data without a dedicated block class.
 * Exposes customer login state and store-switcher data to the header template.
 */
final class StoreSwitcher implements ArgumentInterface
{
    /**
     * @param CustomerSession $customerSession Reads the current customer login state.
     * @param StoreManagerInterface $storeManager Provides the list of active stores.
     */
    public function __construct(
        private readonly CustomerSession $customerSession,
        private readonly StoreManagerInterface $storeManager,
    ) {
    }

    /**
     * Checks whether a customer is currently logged in.
     *
     * @return bool True if a customer session is active.
     */
    public function isLoggedIn(): bool
    {
        return $this->customerSession->isLoggedIn();
    }

    /**
     * Returns the list of active stores for the store switcher.
     *
     * @return StoreInterface[] Active stores of the current website.
     */
    public function getStores(): array
    {
        // @phpstan-ignore-next-line StoreManagerInterface::getStores() missing in interface stub
        return $this->storeManager->getStores();
    }
}

6. Footer-Spalten dynamisch über Layout-XML und Container statt fest im footer.phtml kodieren

Ein häufiger Fehler in gewachsenen Themes: Footer-Spalten werden als feste Anzahl <div>-Blöcke direkt in footer.phtml hartcodiert. Sobald ein Drittmodul eine zusätzliche Spalte braucht, etwa für Zahlungssiegel oder Social-Media-Links, bleibt nur die Template-Änderung. Der sauberere Weg führt über einen eigenen <container> pro Spalte im Footer-Layout-XML: Jede Spalte wird zu einem benannten Slot, in den beliebige Blöcke eingehängt werden können, ohne dass footer.phtml jemals wieder angefasst werden muss.

Diese Container-pro-Spalte-Struktur macht den Footer zu einem echten Erweiterungspunkt für Drittmodule: Eine Zahlungs-Extension hängt ihr Siegel per referenceContainer in die passende Spalte ein, ein Newsletter-Modul ergänzt sein Formular in einer anderen. Bei Footer-Anpassungen per Layout-XML bleibt die Spaltenanzahl selbst flexibel: Ein neues Modul kann sogar eine komplett neue Spalte per eigenem Container registrieren, ohne die bestehenden Spalten zu berühren.

<!-- app/design/frontend/Mironsoft/default/Magento_Theme/layout/default.xml -->
<referenceContainer name="footer.container">
    <container name="footer.column.service"
               label="Footer Service Column"
               htmlTag="div"
               htmlClass="footer-column"
               before="footer.column.social">
        <block class="Magento\Framework\View\Element\Template"
               name="footer.links.service"
               template="Mironsoft_HeaderTools::footer/service-links.phtml"/>
    </container>
    <container name="footer.column.legal"
               label="Footer Legal Column"
               htmlTag="div"
               htmlClass="footer-column"
               after="footer.column.service">
        <block class="Magento\Framework\View\Element\Template"
               name="footer.links.legal"
               template="Mironsoft_HeaderTools::footer/legal-links.phtml"/>
    </container>
</referenceContainer>

7. Theme-Vererbung: Layout-XML-Overrides im Child-Theme ohne das Parent-Template zu duplizieren

Ein Child-Theme, das von hyva-themes/magento2-default-theme-csp erbt, muss für Header- oder Footer-Anpassungen kein einziges Parent-Template kopieren. Es genügt, im Child-Theme eine eigene default.xml anzulegen, die per referenceContainer oder referenceBlock gezielt Ergänzungen vornimmt. Genau darin liegt die Stärke von Header und Footer über Layout-XML: Die Layout-Merge-Logik von Magento kombiniert Parent- und Child-Layout automatisch, sodass nur die tatsächlichen Abweichungen im Child-Theme gepflegt werden müssen.

Eine vollständige phtml-Kopie im Child-Theme ist fast immer ein Warnsignal: Sie friert den Stand des Parent-Templates zum Kopierzeitpunkt ein und divergiert bei jedem weiteren Hyvä-Update unbemerkt. Gezielte Layout-XML-Overrides vermeiden dieses Problem, weil sie nur die Positionen, Argumente oder Sichtbarkeit einzelner Blöcke anpassen, während die eigentliche Render-Logik im Parent-Template bleibt. Das reduziert den Wartungsaufwand über mehrere Kundenprojekte hinweg erheblich, insbesondere im Dual-Vendor-Workflow mit mehreren Theme-Varianten.

8. Alpine.js-Komponenten in layout-injizierten Blöcken korrekt registrieren

Ein per Layout-XML in Header oder Footer eingehängter Block bringt oft eigenes Alpine.js-Verhalten mit, etwa für einen Store-Switcher-Dropdown. Der x-data-Scope wird dabei direkt im Template des neuen Blocks deklariert und bleibt sauber gekapselt, solange er nicht versehentlich auf Variablen außerhalb seines eigenen DOM-Teilbaums zugreift. Wichtig für Magento mit aktiviertem CSP-Modus: Jeder Inline-<script>-Block im Template muss unmittelbar danach mit $hyvaCsp->registerInlineScript() registriert werden, sonst blockiert der Content-Security-Policy-Header die Ausführung im Browser.

Das bestehende Alpine.js-Komponentenmuster mobileFooterCollpase bleibt dabei unverändert in footer.phtml. Neue, per Layout-XML für Header und Footer ergänzte Blöcke bekommen stattdessen ihre eigene, kleine Alpine-Komponente im jeweiligen Template - ohne zusätzliches JavaScript-Bundle, weil Hyvä die Alpine.js-Instanz bereits global bereitstellt. Zustände wie eine Statusmeldung werden über x-text ausgegeben, niemals über eine Mustache-Syntax, die es in Alpine.js gar nicht gibt.

<?php
/** @var \Magento\Framework\View\Element\Template $block */
/** @var \Magento\Framework\Escaper $escaper */
/** @var \Hyva\Theme\Model\ViewModelRegistry $viewModels */
/** @var \Mironsoft\HeaderTools\ViewModel\StoreSwitcher $storeSwitcherViewModel */
$storeSwitcherViewModel = $block->getData('view_model');
$hyvaCsp = $viewModels->require(\Hyva\Theme\ViewModel\HyvaCsp::class);
?>
<div x-data="{ open: false, message: '' }" class="relative">
    <button type="button"
            @click="open = !open; message = open ? 'Store list opened' : ''"
            :aria-expanded="open.toString()"
            class="flex items-center gap-1 text-sm">
        <?= $escaper->escapeHtml(__('Store')) ?>
    </button>
    <div x-show="open" @click.outside="open = false" x-cloak class="absolute right-0 mt-2 bg-white shadow-lg rounded-lg p-3 z-40">
        <p x-text="message" class="text-xs text-gray-500 mb-2"></p>
        <?php foreach ($storeSwitcherViewModel->getStores() as $store): ?>
            <a href="#" class="block py-1 text-sm"><?= $escaper->escapeHtml($store->getName()) ?></a>
        <?php endforeach; ?>
    </div>
</div>
<script>
    // Registered header component: no external JS bundle needed, Alpine handles the state
    window.addEventListener('alpine:init', () => {
        Alpine.data('storeSwitcherHint', () => ({
            hint: 'Store switcher ready'
        }));
    });
</script>
<?php $hyvaCsp->registerInlineScript(); ?>

9. Testing und Caching von Layout-Änderungen

Änderungen an Layout-XML für Header und Footer landen nicht sofort im Browser: Magento kompiliert Layout-Handles in den Layout-Generation-Cache, und gerenderte Seiten liegen zusätzlich im Full Page Cache. Nach jeder Layout-Änderung ist bin/cache-clean layout beziehungsweise ein vollständiger bin/cache-clean Pflicht, sonst zeigt der Browser weiterhin die alte Block-Reihenfolge, selbst wenn die XML-Datei korrekt gespeichert wurde. Der Hyvä-Watcher in bin/start hilft bei Tailwind-Änderungen, ersetzt aber nicht das gezielte Leeren des Layout-Caches nach XML-Anpassungen.

Beim Debugging von Block-Reihenfolgen ist bin/magento dev:query-params:sensitive weniger hilfreich als ein direkter Blick in den generierten Layout-Baum: Der Diagnose-Ansatz der Wahl ist, den Block-Namen im Template testweise via var_dump($block->getChildNames()) auszugeben oder in einer separaten Testumgebung mit bin/magento setup:di:compile und anschließendem bin/cache-clean zu prüfen, ob before/after-Referenzen tatsächlich auf existierende Blocknamen zeigen. Ein Tippfehler im referenzierten Namen führt nicht zu einem Fehler, sondern lässt Magento den Block einfach ans Ende des Containers anhängen - ein klassischer stiller Fehler bei Header und Footer über Layout-XML.

10. Zusammenfassung

Die wichtigsten Bausteine, um Header und Footer über Layout-XML statt hart im phtml zu strukturieren, greifen ineinander: Die Blockstruktur mit $block->getChildNames() macht Container zu erweiterbaren Slots, eigene Blöcke werden per referenceContainer ohne Template-Änderung ergänzt, before/after und sortOrder steuern die Reihenfolge deklarativ, und ViewModels übernehmen die fachliche Logik statt eigener Block-Klassen. Footer-Spalten als eigene Container statt fester <div>-Blöcke machen den Footer zu einem echten Erweiterungspunkt für Drittmodule.

Theme-Vererbung profitiert am stärksten von diesem Ansatz: Ein Child-Theme, das Hyvä-Layout-XML statt phtml-Kopien nutzt, bleibt bei jedem Parent-Update automatisch aktuell. Alpine.js-Komponenten in layout-injizierten Blöcken müssen dabei konsequent über $hyvaCsp->registerInlineScript() registriert werden, und jede Layout-Änderung braucht ein gezieltes Cache-Clearing, bevor sie im Browser sichtbar wird. Wer diese Bausteine konsequent kombiniert, ersetzt fragile Template-Kopien durch ein wartbares, erweiterbares Fundament für Header und Footer.

11. FAQ: Header und Footer per Layout-XML strukturieren