Using local.xml for overriding or updating xml structure

Over the past 3 years working with Magento and complying with the “Magento way” of managing code, usage of the “local.xml” file presented itself as one of the best ways to update xml layout.

This article is aimed at those who are not aware of the “local.xml” method. If you’re already using it, kudos to you. If not, you definitely should use it.

The idea is simple: Use only one file, the local.xml, placed inside your theme’s layout folder to override or update all xml references for that theme.

Benefits:

1. Only one file to manage overrides and updates
2. No need to have any other .xml file for your theme since it’s dependent on the xml files inside the base folder
3. Every change to the local.xml file is evident so there is no need to search for changes inside xml files

Drawbacks:

1. None that I could think of, unless transparency and evident code changes aren’t your thing.

How to use the local.xml file. All you have to do is to create one inside your theme’s folder and write your xml. Since magento reads through the xml files it will first search for the changes inside your newly created local.xml and apply overrides and updates and then fall through the .xml files inside the base folder if that is the default xml folder set via the magento administration.

How to set it up:

1. Create the local.xml inside your theme’s layout folder (app/frontend/default/your-theme/layout)
2. Add basic xml markup structure

1 2	< ?xml version="1.0"?> <layout version="0.1.0"></layout>

3. Place xml overrides minding the structure. See the examples:

Examples:

1. Removing/Adding javascript from the section:

1 2 3 4 5 6

<!-- Let’s remove sleight js for IE7--> <reference name="head"> <action method="removeItem"><type>js</type><name>lib/ds-sleight.js</name><params /><if>lt IE 7</if></action> </reference> <!-- Instead, add belated.js from your theme’s /js folder --> <action method="addItem"><type>skin_js</type><name>js/belated.js</name><params /><if>lt IE 7</if></action>

2. Add a layout change for the category page only. Setting a template and adding some javascript

1 2 3 4 5 6 7 8 9 10 11 12 13

<catalog_product_view translate="label"> <reference name="root"> <action method="setTemplate"> <template>page/1column.phtml</template> </action> </reference> <reference name="head"> <action method="addItem"><type>skin_js</type> <name>js/stereotabs.js</name></action> <action method="addItem"><type>skin_js</type> <name>js/shadowbox/shadowbox.js</name></action> </reference> </catalog_product_view>

3. Remove specified blocks from the layout (products compare, products viewed and related products) using “remove”

1 2 3 4 5 6 7

<default> <reference name="right"> <remove name="catalog.compare.sidebar" /> <remove name="left.reports.product.viewed" /> <remove name="catalog.product.related" /> </reference> </default>

4. Remove specified blocks from the layout (products compare, products viewed and related products) using method=”unsetChild”

1 2 3 4 5 6 7

<default> <reference name="left"> <!-- Removed the Newsletter from the left sidebar --> <action method="unsetChild"><name>left.newsletter</name></action> <action method="unsetChild"><name>tags_popular</name></action> </reference> </default>

There are many other uses of course but I merely wanted to point out ways of adding, removing and updating to better illustrate the point of having local.xml in your development workflow.

Hope this makes a good starting point in your next project for the first time users and very welcome topic to discuss about for those
with a working experience.

Thanks for reading