In Magento 2, some layout handle XML files open with the


root tag. Others open with the


root tag. Does using either of the above tags introduce any functionality differences to a layout handle XML file? Or is this pure window dressing? Or something in between.

Two examples

<!-- File: vendor/magento/module-weee/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">


<!-- File: vendor/magento/module-widget/view/adminhtml/layout/adminhtml_widget_loadoptions.xml -->
<layout xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/layout_generic.xsd">

3 Answers 3


These matters due to a different XSD configurations. The

<layout xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/layout_generic.xsd">

declaration says that we want to use layout with XSD definition provided in the


In the layout_generic.xsd file it provides definition for layout node with genericLayout element type.

<xs:complexType name="genericLayout">
    <xs:sequence minOccurs="0" maxOccurs="unbounded">
        <xs:element ref="referenceContainer" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="container" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="block" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="referenceBlock" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="update" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="move" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element ref="uiComponent" minOccurs="0" maxOccurs="unbounded"/>

Having that, the layout file has been validated by the XSD when xml is loaded. In addition to this it highlights all possible nodes and node attributes in the layout.xml file.

Same with page_configuration.xsd definition for <page /> node. This XSD describes nodes which can be used to describe page.

Hope it helps.

  • 2
    hat helps some, +1 for that, but it's still not clear why the difference exists. Is layout just unconverted legacy? Or does the distinction exists for a good reason. Jan 16, 2016 at 0:36
  • 1
    It exists for a reason. Just imagine flexibility when instead of creating phtml or html file and if you need some modification to existing file you have to copy it, you have declarative way of defining a page. With it's html, body and head elements. Layout - it is just another, different layer of configuration, where you opera with pieces of content such as block, component, container etc.
    – Max Pronko
    Jan 16, 2016 at 0:42
  • 1
    Not sure I see the distinction -- can't the inner nodes of a <layout/> file be included in a <page/> <body/> for the same effect? Or am I missing something? Jan 16, 2016 at 1:23
  • Consider this approach as a separation of concerns. Including many other places where Magento 2 split classes, configuration, layouts etc.
    – Max Pronko
    Jan 16, 2016 at 11:04

Layout files which open with <layout></layout> are page layouts that declare the wireframe of a page inside the <body> section, for example one-column layout or two-column layout.

The layout files which open with <page></page> are page configuration files that add content to the wireframe defined in a page layout file.

Here is the official doc about it, please let us know if it can be improved: http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/layouts/layout-types.html

  • This would be a lot easier to understand if you clarified, as you did in your response, that one opens with <layout> and one with <page> on this article.
    – jamil
    Nov 2, 2016 at 21:20

One difference that I've noticed is, because is wireframe of a page inside body, you can ajax retrieve just a part of html. Normally if you hit a controller you get the whole page starting with tag. These controllers are returning page objects created by PageFactory which uses type layout xml. But when you want to dynamically load some phtml with ajax call like filter form, is helpful. Magento_ImportExport dynamically changes export filters when entity (product,customer) changes. This is an example of when magento uses (adminhtml_export_getfilter.xml).

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.