Using local.xml for overriding or updating xml structure

Featured Image

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 :)

Interested in hiring us?

Have a chat with us. You would be surprised how small changes can make your business even more successful.


32 comments

  1. Hi there,
    is it possible to use local.xml to bypass the login/register for guest when using wishlist.
    Thanks in advance

  2. 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!

  3. 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??

  4. 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 :)

  5. @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?

  6. 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

  7. 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.

  8. Hi dave, not sure why my comment was not displayed… i think the below should help

    <reference name="top.links">
    		<!--<remove name="checkout_cart_link"/>
      		<action method="removeLinkByUrl" module="catalog"><url helper="customer/getAccountUrl" /></action>
    		<action method="removeLinkByUrl" module="catalog"><url helper="customer/getLoginUrl" /></action>
    		<action method="removeLinkByUrl" module="catalog"><url helper="checkout/getCartUrl" /></action>-->
    		<action method="removeLinkByUrl" module="catalog"><url helper="customer/getLoginUrl" /></action>
    </reference>
  9. 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 ?

  10. @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 …

  11. @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: http://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

  12. I try to move top.menu block from header to root using local.xml.

    In page.xml we have:

                <block type="page/html_header" name="header" as="header">
                    <block type="page/template_links" name="top.links" as="topLinks"/>
                    <block type="page/switch" name="store_language" as="store_language" template="page/switch/languages.phtml"/>
                    <block type="core/text_list" name="top.menu" as="topMenu" translate="label">
                        <label>Navigation Bar</label>
                    </block>
                    <block type="page/html_wrapper" name="top.container" as="topContainer" translate="label">
                        <label>Page Header</label>
                        <action method="setElementClass"><value>top-container</value></action>
                    </block>
                </block>

    In my local.xml I have:

    	<default>
    
    			<reference name="root">
    
    				<block type="core/text_list" name="top.menu" as="topMenu" translate="label">
    					<label>Navigation Bar</label>
    				</block>
    <block type="page/switch" name="store_language" as="store_language" template="page/switch/flags.phtml" />
    			</reference>
    ...

    The menu do not show. But language switch block it shows. Seems there is a problem it structural core/text_list blocks.

  13. @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!

  14. @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 ) http://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:

    http://inchoo.net/ecommerce/magento/how-to-update-layout-of-your-custom-controller-in-magento/

  15. Sorry, source code from above:
    (both examples)

     30     <catalog_product_view translate="label">
     31         <reference name="root">
     32             <action method="setTemplate">
     33                 <template>page/2columns-left.phtml</template>
     34             </action>
     35         </reference>
     36     </catalog_product_view>
  16. 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?

  17. 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!

  18. Nice post!,but i cannot postion my blocks at the exact location.It always go to the bottom of the screen.any ideas?

  19. to be clear, are u saying that EVERYTHING can be controlled from this file? or ?

    what can not be controlled from this file?

  20. @Martin Martinov Nope :( I do it the same way, but if you find another way that would be great :)

  21. 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” :-)

  22. 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?

  23. @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.

  24. 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?

  25. 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

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <blockquote cite=""> <code> <del datetime=""> <em> <strike> <strong>. You may use following syntax for source code: <pre><code>$current = "Inchoo";</code></pre>.