Magento 1.9 – Understanding Layout XML Merging

layoutlayout-updatemagento-1.9

How does Magento handle layout XML files?

For example if I have created a theme app/design/frontend/example/theme and copy an XML file from the base/default/layout directory in my theme's layout directory:

Does it override the whole file? Meaning will I have to copy the XML file into my theme to begin overriding things, or
Does it merge with the base/default and override only the changes I have made in my XML file?

Best Answer

In brief, this is how Magento loads layout files:

When loading a theme, Magento reads the configuration of all the available modules, and checks which layout files should be loaded.
For each file, Magento tries to load it from your theme.
If it exists in your theme, it loads it and goes directly to step 4.
If the file doesn't exist in your theme, it tries to load it from the base/default theme.
Magento parses the XML files and merges them into one.
Magento looks for a local.xml file in your theme, and appends whatever is there, to the previously merged layout handles.

So, unless absolutely required,

Use the local.xml for changing the layout of a theme, instead of copy/pasting the xml files from base to your theme.
Create your own layout files for your own custom modules.

Tip
It - almost - doesn't matter if a layout handle exists in foo.xml or bar.xml.
I've seen implementation where people copy/paste catalog.xml to their own theme, because they think that's the only place where they can edit "catalog-related" handles.
The difference you would notice between adding a handle in foo.xml instead of bar.xml, is that a block would be appended in a different order, depending on which layout file was first loaded.

Related Solutions

Magento – Magento custom module – cannot load layout file via XML

First check if the layout handle is correct.
Add this line in the controller to see the layout handle

echo $this->getFullActionName();

I have a feeling it will print something like this adminhtml_module_sync_index. This is the layout handle you have to use in the layout file.
Also, just to be save, add a name and alias to the block from the content section.
Something like this:

    <adminhtml_module_sync_index><!--put here what you get from the echo in the controller -->
        <reference name="head">
            <action method="setTitle" translate="title">
                <title>Module</title>
            </action>
        </reference>
        <reference name="content">
            <block type="module_sync/adminhtml_index" template="sync/index.phtml" as="index" name="index" />
        </reference>
    </adminhtml_module_sync_index>

Magento 1.9 – Layout Updates in theme.xml to Pick Up Parent Theme’s XML

I found the problem was with my syntax, as per Alan Storms post on infinite theme's fallaback the proper syntax is:

<?xml version="1.0"?>
<theme>
    <parent>rwd/enterprise</parent>
    <layout>
        <updates>
            <my_new_file_name>
                <file>my_new_file_name.xml</file>
            </my_new_file_name>
        </updates>
    </layout>
</theme>

So in my case this meant I needed:

<theme>
    <parent>blacknwhite/default</parent>
    <layout>
        <updates>
            <parentslocal>
                <!--should be linking to app/design/frontend/hoi/default/layout/parentslocal.xml-->
                <file>parentslocal.xml</file>
            </parentslocal>
        </updates>
    </layout>
</theme>

Best Answer

Related Solutions

Magento – Magento custom module – cannot load layout file via XML

Magento 1.9 – Layout Updates in theme.xml to Pick Up Parent Theme’s XML

Related Topic