Bypassing Magento 2 layout update restrictions in Admin

Magento’s layout system has been vastly improved in Magento 2 to be more accessible, more powerful and to be more streamlined. But, for some reason, only a very small subset of layout functions is made available for use in Magento 2 Admin (category layout XML updates, to be more precise). In this article, we’re going to show a very simple way of bypassing this pesky restriction.

Layout update restrictions in Magento 2 Admin

In the interest of keeping the example simple and straightforward, let’s say we want to remove the page title element from a specific category. In Magento 2 admin, in the category layout update XML field we add the following line.

<referenceBlock name="page.main.title" remove="true" />

And when we click save, we get the following error:

Please correct the XML data and try again. Element ‘referenceBlock’: This element is not expected. Expected is one of (referenceContainer, container, update, move ). Line: 1

It’s important to note that this XML would be valid if added using XML files in a theme. It seems that different standards apply for the layout update field in Magento 2 Admin and for the theme layout files.

So, only the following XML is allowed:

• referenceContainer – we can reference existing containers
• container – we can create new containers
• update – we can include various layout handles
• move – we can move existing blocks around

This info will help us bypass the restriction.

Bypassing the layout update restrictions

We can simply bypass this restriction by wrapping our referenceBlock code in referenceContainer code. But we need to find the container which contains our page title element. By doing a simple search in IDE, we find the following code snippet.

<referenceContainer name="columns.top">
<!-- ... -->
    <block class="MagentoThemeBlockHtmlTitle" name="page.main.title" template="html/title.phtml"/>
            <container name="page.messages" htmlTag="div" htmlClass="page messages">
                <block class="MagentoFrameworkViewElementTemplate" name="ajax.message.placeholder" template="Magento_Theme::html/messages.phtml"/>
                <block class="MagentoFrameworkViewElementMessages" name="messages" as="messages" template="Magento_Theme::messages.phtml"/>
            </container>
<!-- ... -->
</referenceContainer>

We use the columns.top container and reference it in our Layout Update XML in Admin and wrap it around our initial code.

<referenceContainer name="columns.top">
    <referenceBlock name="page.main.title" remove="true" />
</referenceContainer>

When we save this configuration, we do not get any errors on the category page in Admin and the page title block is removed on that specific category.

Conclusion

We hope to see these restrictions either removed from Magento 2 Admin XML layout update fields or better documentation that will explain the behavior in more detail. Magento 2 Admin would most certainly benefit of having unrestricted layout update features. Until then, we can hopefully use this bypass safely and hope that it’s upgrade-proof.