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
< ?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:
<!-- 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
<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”
<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”
<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 🙂
35 comments
can i set other extensions js and css file in local.xml ?
i have done a lot of changes but does not work to add a js file can an body tell me
What does mean when you are adding js file to the layout? Is it required?
Hi there,
is it possible to use local.xml to bypass the login/register for guest when using wishlist.
Thanks in advance
Thanks for the post !
As i am a newbee on Magento, I try to read a lot but not sure how to do this.
I d like to create a landing page with a custom head.
I created a module landing_page. Everything works I can create a cms page and select landing page as layout. I’d like to remove few files from the head but only for this layout. Can I do it from the local.xml and How to ? thanks for your answer!
Hi,nice article. By reading this I am trying to move my related products block into my product’s description. BUt some how it is not working.Hwat i do nis i remove related product block from local.xml and add that block into main content block under product-info block.Any suggestion??
Hey, is there way to add attributes to the products list page (list.phtml) by using local.xml? For example I use the getData function to show a custom attribute in list.phtml but they don’t display. I think I need to add the attributes using the layout xml file. Thanks 🙂
@Bijal
Try with $this->getChildHtml instead of $this->getChildhtml
I don’t see example of your local.xml file.
If my suggestion doesn’t work, can you show us what did you write in your local.xml file?
Also did you refresh the Magento cache?
Hello,
Nice article. Thanks for sharing.
I need help, i want to add one block like cart_sidebar block in local.xml, i am calling it as $this->getChildhtml(‘cart_sidebar’); in 1column.phtml
how can we add it?
i have tried adding like:
simplecheckout/cart_item_renderercheckout/cart/newsidebar/default.phtml
groupedcheckout/cart_item_renderer_groupedcheckout/cart/sidebar/default.phtml
configurablecheckout/cart_item_renderer_configurablecheckout/cart/sidebar/default.phtml
Shopping Cart Sidebar Extra Actions
The above code is not working. can you plz help me to display cart block in homepage.
Thanks,
Bijal Bhvsar
I want to know that if we add local.xml file in our theme’s layout folder then is there any need of other xml files?
And if not then our layout will only consist of only one xml file? that is local.xml?
Thanks
Kaushal.
Hi dave, not sure why my comment was not displayed… i think the below should help
goog article.
Same question cedddd
Great article.
How to remove header link whith local.xml ? for example my account or checkout
thanks
the response of nav is empty.
how to remove header link ?
@Tsvetan. I don’t think is something dirty. :D. I did the same with “page/switch” block. But no success with “core/text_list” block types. Yes, I put the line getChildHtmel(‘topMenu’) is my 3columns.phtml.
Try to make a simple test and u will see …
@Catalin You are trying to do something dirty 🙂 I advice you to use CSS technique instead of local.xml for your case. I think that your question is not related with article …
Please read this article and you will get how it works: https://inchoo.net/ecommerce/magento/custom-reference-structural-block/
ANYWAY check /app/design/frontend/base/default/template/page/html/header.phtml for reference.
So you notice that line:
getChildHtml(‘topMenu’) ?>
Now you have to add this line to: /app/design/frontend/base/default/template/page/ 1column.phtml, 2columns-left.phtml, 2columns-right.phtml, 3columns.phtml
I try to move top.menu block from header to root using local.xml.
In page.xml we have:
In my local.xml I have:
The menu do not show. But language switch block it shows. Seems there is a problem it structural core/text_list blocks.
@Tsvetan
Thanks for your quick reply. I had read the hierarchy article before and visited your 3-mistakes article. I understand the way that works, and hadn’t made any mods to the base theme. I’m in default/my_theme.
I got the local.xml file to adjust one of the pages last night (finally!). My lack of understanding now is on the “handles”. I will check this article out and let you know if I have more questions.
Thank you!
@Tom As I understand your comment you did modifications in your base theme. It is not good practice to do that. Probably your problem is a result from Magento fall-back hierarchy, because Magento doesn’t load changed file.
Please read carefully those 2 articles:
1 ) http://www.magentocommerce.com/knowledge-base/entry/magentos-theme-hierarchy/
2 ) https://inchoo.net/ecommerce/magento/top-3-mistakes-by-magento-beginners/
“How do I know what page controls what?” If I understand you I think that you have to read more about handles, so this article will be perfect for you:
https://inchoo.net/ecommerce/magento/how-to-update-layout-of-your-custom-controller-in-magento/
Sorry, source code from above:
(both examples)
How do I know what page controls what? In the XML I mean? I’ve got a local.xml set up but I can’t seem to get the 2columns-left.phtml to work. I’ve copied it into my PAGE directory in my theme (blank) and with the following code, nothing happens:
31
32
33 page/2columns-left.phtml
34
35
OR
30
31
32
33 page/2columns-left.phtml
34
35
36
still nothing.
Help?
By the way, incase you haven’t seen it, Alan Storm wrote a great little “Layout Unremove” extension (http://alanstorm.com/magento_layout_unremove_in_local_xml). Lets you “undo” remove tags in other layout files, from the local.xml, simply by adding:
Just want to append something, that is not so intuitive to me. While I was doing research about Magento template system I met next situation:
For example I have:
my-theme/layout/local.xml
my-theme/layout/customer.xml
I have handle “customer_account_login” in both files.
So I was curious how Magento will proceed in this situation. As I said this is not intuitive for me. First I was thinking that it will ignore customer.xml, but decided to not look at Magento source and to do some tests.
The result is, that Magento likes to merge. It merges the nodes from both files. So we have the changes from both files.
Other thing that I tried was to see who will be the winner in next situations:
in my-theme/layout/local.xml
page/1column.phtml
my-theme/layout/customer.xml
page/2columns-left.phtml
Changes from local.xml were applied. So local.xml won!
I played more with another handle “customer_account_index” in
my-theme/layout/local.xml
my-theme/layout/sales.xml
to see how Magento merges. Is it in alphabetical order?
Again changes from local.xml were applied.
So I suspect, that Magento merges all files in alphabetical order and at the end applies changes from local.xml
I finally looked at the source and found in:
app/code/core/Mage/Core/Model/Layout/Update.php
On lines: 417 & 418
// custom local layout updates file – load always last
$updateFiles[] = ‘local.xml’;
Hope that helps to somebody and folks from Inchoo to excuse me for long comment!
Nice post!,but i cannot postion my blocks at the exact location.It always go to the bottom of the screen.any ideas?
to be clear, are u saying that EVERYTHING can be controlled from this file? or ?
what can not be controlled from this file?
Small typo in your first line 1. There’s a space between < and ?xml
Very useful article.
I love the way.
More info:
http://www.magentocommerce.com/wiki/4_-_Themes_and_Template_Customization/0_-_theming_in_magento/designing-for-magento
http://classyllama.com/development/magento-development/the-better-way-to-modify-magento-layout/
Thanks
@ceddd
To remove checkout links:
Hello,
Great article.
How to remove header link whith local.xml ? for example my account or checkout
thanks
@Martin Martinov Nope 🙁 I do it the same way, but if you find another way that would be great 🙂
Hm, your comment form ate part of my text instead of encoding it with < and > 😉
Please replace above “in the tags” with “in the <block> tags” and “-ing” with “<remove>-ing” 🙂
Hey, I’m also using the local.xml file for the theme of my current project and there’s one thing I’m still wondering how to do. It’s ordering blocks. I’ve used to just add the attributes after=”” or before=”” in the tags in different module layout files. Do you know how to order blocks in local.xml without first -ing and then adding the block again?
Thanks,it’s good
Great article Željko, I couldn’t agree more! We’re also experimenting with described local.xml method lately.
@Brady You can use any of the nodes already present in every other xml file from the layout folder. The article explains how to override and update them, so feel free to use any of the nodes you need.
Very cool tip! I wasn’t aware of this “one stop” method for updating the XML, but I love the idea!
Is there a document or library that outlines what XML nodes are available?
Thanks Željko, that’s a real time saver, how long have I spent jumping from one layout file to the next to discover your elegant solution. I love the whole catch all nature of the local.xml file and there’s no drawbacks.
Right, off to give this a try now.
David