Categories


Archives


Recent Posts


Categories


Layout XML Merging in Magento 2

astorm

Frustrated by Magento? Then you’ll love Commerce Bug, the must have debugging extension for anyone using Magento. Whether you’re just starting out or you’re a seasoned pro, Commerce Bug will save you and your team hours everyday. Grab a copy and start working with Magento instead of against it.

Updated for Magento 2! No Frills Magento Layout is the only Magento front end book you'll ever need. Get your copy today!

One of the bigger changes to Magento 2’s layout system is how a end-user-programmer uses layout handles. In Magento 1, layout handles were top level configuration nodes in a set of layout update xml files

<handle_name>
    <!-- layout update xml nodes -->
</handle_name>

In Magento 2, layout handles are individual XML files (which I’ve been calling layout handle XML files)

#File: path/to/module/view/layout/handle_name.xml
<!-- layout update xml nodes -->    

One interesting side effect of this is, unlike Magento 1, Magento 2’s layout XML files are susceptible to node level merging. i.e. — consider this core XML file

#File: vendor/magento/module-catalog-search/view/frontend/layout/default.xml
<?xml version="1.0"?>
<!--
/**
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
 */
-->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="top.search">
            <block class="Magento\Framework\View\Element\Template" name="advanced-search-link" template="Magento_CatalogSearch::advanced/link.phtml" />
        </referenceBlock>
        <referenceBlock name="footer_links">
            <block class="Magento\Framework\View\Element\Html\Link\Current" name="catalog-search-advanced-link">
                <arguments>
                    <argument name="label" xsi:type="string" translate="true">Advanced Search</argument>
                    <argument name="path" xsi:type="string">catalogsearch/advanced</argument>
                    <argument name="attributes" xsi:type="array">
                        <item name="data-action" xsi:type="string">advanced-search</item>
                    </argument>
                </arguments>
            </block>
        </referenceBlock>
    </body>
</page>

If you, as a module developer, create a file with the same name in your module and give its nodes the same names

#File: app/code/Pulsestorm/Nofrillslayout/view/frontend/layout/default.xml
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="footer_links">
            <block class="Magento\Framework\View\Element\Html\Link\Current" name="catalog-search-advanced-link">
                <arguments>
                    <argument name="label" xsi:type="string" translate="true">Changing the Advanced Search Label</argument>
                </arguments>
            </block>
        </referenceBlock>
    </body>
</page>     

Magento will merge your values for the name=catalog-search-advanced-link node and name="label" node over the values in Magento’s original file. While this sort of merging happened with Magento 1’s config.xml tree, it did not happen with Magento 1’s layout update XML files.

It’s hard to say if this is a technique developers should lean heavily on or not. Most long-time Magento 1 developers avoided using these sort of layout merges in the config.xml tree due to a lack of clarity around how the merging rules worked. Questions like when does Magento add a new node vs. merging a node? Are node attribute values merged? If node attribute values are merged, does a missing node in the merged XML mean leave the old value, or remove the node? These same questions remain for Magento 2, with the added complexity that there are dozens of classes for XML loading and merging in M2. i.e. tracking down these merge rules is a non-trivial affair, and without any promise of future behavior from Magento’s core team the behavior could easily change out under you.

Regardless of whether using XML merges is a good idea, you will encounter third party Magento code that uses them. Be sure you’re searching all the code in your system when you’re trying to track down block arguments.

Copyright © Alana Storm 1975 – 2023 All Rights Reserved

Originally Posted: 26th December 2017

email hidden; JavaScript is required