Magento 2 Theme – Modify Layout Guide

layoutlocal.xmlmagento2themexml

In Magento 1, themes had a special file named local.xml. Through this file, a Magento 1 theme could directly modify the layout without needing to replace a specific layout update XML file.

Does Magento 2 have a similar mechanism? I know a Magento 2 theme can replace a layout handle XML file from a module — what I want to know is does Magento 2 have a way for a theme to add layout rules that are specific to that theme.

If not, are there classes/methods provided that would allow a module developer to only add certain layout rules when a certain theme is added?

Best Answer

You have two options, you can either extend or overwrite the existing XML.

Extending

To extend an existing layout in a similar fashion to local.xml in Magento 1 you need to add an XML file in a location like this:

<theme_dir>
 |__/<Namespace>_<Module>
   |__/layout
     |--<layout1>.xml
     |--<layout2>.xml

Where <layout1> and <layout2> are your layout handles, for example:

<your_theme_dir>/Magento_Catalog/layout/catalog_product_view.xml

Official documentation can be found here - http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/layouts/layout-extend.html

Overwriting

Overwriting XML is done in the same way, it's just the file location that changes. You can overwrite the base module's XML or the parent theme's XML, the file location determines which is overwritten.

To overwrite the base module's XML place your XML file in:

<theme_dir>
  |__/<Namespace_Module>
    |__/layout
      |__/override
         |__/base
           |--<layout1>.xml
           |--<layout2>.xml

To overwrite the parent theme's XML place your XML file in:

<theme_dir>
  |__/<Namespace_Module>
    |__/layout
      |__/override
         |__/theme
            |__/<Parent_Vendor>
               |__/<parent_theme>
                  |--<layout1>.xml
                  |--<layout2>.xml

Official documentation can be seen here - http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/layouts/layout-override.html

Related Solutions

Magento – Multiple local.xml layout files in a package

You are correct, and this is a valid & used approach for sites with multiple themes. There are a couple of additional (little-known, seldom-used) options which can be used for layout updates which apply to different store scopes: the store handle and the theme handle.

From the action controller superclass Mage_Core_Controller_Varien_Action (link):

public function addActionLayoutHandles()
{
    $update = $this->getLayout()->getUpdate();

    // load store handle
    $update->addHandle('STORE_'.Mage::app()->getStore()->getCode());

    // load theme handle
    $package = Mage::getSingleton('core/design_package');
    $update->addHandle(
        'THEME_'.$package->getArea().'_'.$package->getPackageName().'_'.$package->getTheme('layout')
    );

    // load action handle
    $update->addHandle(strtolower($this->getFullActionName()));

    return $this;
}

For a store with the code 'deutsch' and a theme configuration of 'default' package, 'german' theme, the following handles would apply to almost every view, as most views use them:

<STORE_deutsch>
<THEME_frontend_default_german>

By implementation these handles can be utilized in much the same way as <default />.

Magento2 Module Layout – Relationship Between Module Layout Handle XML Files and Theme Update XML Files

the order of layout files collecting is documented here under "Extend layouts" http://devdocs.magento.com/guides/v2.0/frontend-dev-guide/themes/theme-inherit.html

Extend layouts

The layouts processing mechanism does not involve fallback. The system collects layout files in the following order:

Current theme layouts: /_/layout/

Ancestor themes layouts, starting from the most distant ancestor, recursively until a theme with no parent is reached: /_/layout/

Module layouts for the frontend area: /view/frontend/layout/

Module layouts for the base area: /view/base/layout/

Unlike templates or images, layout can be not only overridden, but also extended. And the recommended way to customize layout is to extend it by creating theme extending layout files.