Don’t use local.xml for layout changes

Up until a short while ago I was still using local.xml for modifications to a project-specific theme, even though 1.9 introduced the theme.xml file. The scenario I encountered which forced me to ditch local.xml is pretty interesting and made me understand the need for the theme.xml layout updates.

Basically, I was working on a website that now wanted to expand in a different country. The new store looked similar, but would have slightly different templates. Usually - in a similar situation - I would use a different theme under the same package (to make use of the “natural” theme fallback to “default”).

I couldn't use a different theme in this case because I was already using themes for certain pages that looked slightly different as a way to easily override template files without having to write any XML. (I was changing the theme in an observer event for specific pages.)

Then I tried using a new package. But that didn’t work out because I didn’t want to override local.xml. Overriding the local.xml means the whole thing needs to be copied and results in duplication.

Eventually I added a layout update to the theme.xml in the new package. Also that didn’t work out because I couldn’t reference anything which was defined in the local.xml.

$updateFiles = array();
foreach ($updates as $updateNode) {
    if (!empty($updateNode['file'])) {
        $module = isset($updateNode['@']['module']) ? $updateNode['@']['module'] : false;
        if ($module && Mage::getStoreConfigFlag('advanced/modules_disable_output/' . $module, $storeId)) {
            continue;
        }
        $updateFiles[] = $updateNode['file'];
    }
}
// custom local layout updates file - load always last
$updateFiles[] = 'local.xml';

As shown in this code snippet (Line 426 in Mage_Core_Model_Layout_Update class) local.xml is always loaded last.

I remembered that since Magento 1.9.0.1 you can add your own layout updates in the theme.xml. All I did was copy everything which was in local.xml into my newly defined layout update file (in the package of the existing store) and everything kept working. Then I created a theme.xml for the new package which I added my changes of the new store to. Tada!

(The new store’s theme.xml had to define both layout updates, even though it was inheriting from the existing store. This is either a feature or a bug. See https://ericwie.se/blog/magento-infinite-theme-fallback-fix and http://alanstorm.com/magento_infinite_fallback_theme_xml.

In short, you can add a layout update in app/design/frontend/yourpackage/etc/theme.xml. The advantage is that you have control over the load order of your layout updates. Before Magento 1.9 local.xml was always loaded last, and it was impossible to have layout directives be executed after it.

I’m not using local.xml any more for project-specific theme modifications. I think local.xml is just used for backward compatibility reasons (in 1.9 and above) as there is no point in using it any more. Local.xml is also eliminated in Magento 2 (https://github.com/magento/magento2/issues/1037).

layout.xml theme magento