The Better Way to Modify Magento Layouts

In this article, I’m going to be covering what I believe to be a very effective way of modifying the layout of any Magento theme.

For several of the first Magento themes I built, I copied the layout files from the default or blank theme into the custom theme layout folder. I would then modify the layout files directly, editing or commenting out content in files like: catalog.xml, page.xml, checkout.xml, etc… I never liked editing these files directly, as I knew that when it came time to upgrade to a newer version of Magento that had upgraded the layout files, I’d have to merge the changes into the new layout files.

One day, I was digging through the Magento code relating to layout files and discovered a bit of code that made me realize that it was possible to just place a local.xml file in my custom theme’s layout folder and have it loaded automatically by Magento. (this code is on line 283 in /app/code/core/Mage/Core/Model/Layout/Update.php in the fetchFileLayoutUpdates() method).

Due to Magento’s brilliant tags, it’s possible to do just about anything you want without having to edit any of the default layout files.

Before delving into the code, let’s look at the advantages/disadvantages of this method:


  • Allows you to upgrade themes without having to merge in changes
  • All custom layout changes are centralized, allowing developers to more easily make changes to custom theme elements


  • At first, it’s slower to use this method than hacking up the standard layout files directly
  • You will have one more place to look where the site might be pulling code (template phtmls, standard layout files, admin layout updates, AND local.xml)

Here is the slimmed down, commented local.xml from one of our recent projects:

I hope with article has given you some direction as to how you can improve you Magento theming skills. If you have any additional tips/comments on coding layouts, please suggest them in the comments section.

Posted on February 23, 2010

Posted by Erik Hansen


  1. Helped a Lot in editing my theme layout


  3. How do you have control over number of products in the category ? Also, how to handle the out of stock notification indicator when you create custom layout ?

  4. Great tutorial for understanding the possiblities of the theme-topic 😉

  5. Thank you for your post!

    Anybody knows how to restore left block which is removed on checkout-page via checkout.xml

    I am using local.xml file, and need to show this left block which is not showing. Any help will be great!

  6. Great help & better tutorial, nice. can u provide some similar help for Joomla also ? Thanks in advance !!!

  7. Love this! Building my first site in Magento and this article is a life saver…thank you! :)

  8. Great post, used it to remove all the unnecessary javascript from the checkout pages.



  9. If your local.xml is being ignored, then your problem is probably the caching. Magento really loves to cache its layouts. If it had to compile everything for every request it would quickly grind to a halt.
    Go to your admin page. System | Cache Management. Make sure “Configuration” cache is disabled. IMO it’s best to turn off *all* caching while a site is in development.

  10. Some of the code was removed.

  11. I’ve tried, but I am not getting my local.xml file to override anything. Its like It is being completely ignored. I created a new theme (genesis), and in there created 3 new folders (template, layout and genesis) and in the layout folder i have my local.xml file. The contents of the file is:

    < ?xml version="1.0" encoding="UTF-8"?>



    I simply want to update the default layout of the pages and this is not happening at all, neither is anything (for instance, breadcrumbs) being removed. Can anyone advise me as to what the solution is?

  12. I am extremely impressed thanks for sharing all information. It is a great post for the people to get the proper information.

  13. Extremely awesome and helpful post for me… even about a year after you wrote it!! These layouts are tough to get the hang of, but your code example really helped me out.

    You should write a book on templating Magento. Stuff like local.xml best practices and “stuff you need to know”. I’d for sure buy it. 😉

  14. @hartog actually in 1.5 the code has just been moved to a different method. Have a look in public function getFileLayoutUpdatesXml in the same file, line 418

  15. Hello
    Great articles.
    How to unsetChil one block

    Its possible ? or only emove is ok for this block ?

  16. hmm just a note here but maybe it would be a good idea to dig into the source for this site and add “htmlspecialchars()”
    to the php for the comment post. would make it a WHOLE lot easier on your commenters.

  17. So I got past my initial issues and I am successfully designing a theme based on your method.

  18. from:


  19. from:


    reference name=”content”>
    reference name=””>
    action method=”unsetChild”>addto
    remove name=”addto”/>


  20. Why are you doing both unsetChild-addto AND remove addto ? Was the unsetChild not enough ?



  21. Is there a tag type similar to that specifies if the shopping cart has anything in it? For example if I only wanted to display the My Cart toplink if the cart had something in it. I’ve seen a few ways it can be done by editing the php core directly, but I don’t want to to that.

  22. I love the way you explain it. Thank you!

  23. third try with xhtml tags:

    I love your article and I kept everything clean with this. I know you worte this ages ago, but maybe someone can give me a hand with one problem. I cannot add a new reference between content and footer without changing page.xml. Do you know a way to do this?
    It works when I change page.xml and add into the default layout and:
    <block type=”core/text_list” name=”middlespace” as=”middlespace” translate=”label”>
    Then I can use:
    <reference name=”middlespace”>
    <block type=”core/template” name=”three-teasers-home” template=”page/html/three-teasers-home.phtml” after=”-” />
    But I don’t want to change page.xml, can you help me out? Or maybe someone else?

  24. Hi,
    I love your article and I kept everything clean with this. I know you worte this ages ago, but maybe someone can give me a hand with one problem. I cannot add a new reference between content and footer without changing page.xml. Do you know a way to do this?
    It works when I change page.xml and add into the default layout and:


    Then I can use:

    But I don’t want to change page.xml, can you help me out? Or maybe someone else?

  25. Hi,
    I love your article and I kept everything clean with this. I know you worte this ages ago, but maybe someone can give me a hand with one problem. I cannot add a new reference between content and footer without changing page.xml. Do you know a way to do this?
    It works when I change page.xml and add into the default layout and:


    Then I can use:

    But I don’t want to change page.xml, can you help me out? Or maybe someone else?

  26. if you want to create your own magento blocks and insert it in a layout look at :

  27. I guess the code tag didn’t really work:


  28. Thanks for pointing out this helpful technique. With the following code in local.xml, I was able to simply incorporate an alternate body style.


  29. How do you control number of products in the category view in Magento?

  30. Hi ehansen,

    Thanks for great article lots of things are cleared to me by this article.

  31. Thanks for your helpful tip. I have a question. Are there any way to determine the block position from layout.xml file based on module configuration? EX: i have config from backend to show one block at: left, right or not. So the layout file of this module will reference to left, right or not. How do i approach this?

    Sorry for my poor English. Hope you understand.

    Thanks and hope to hear from you soon.

  32. Great article, one issue that I’ve come across is when you need to reorder the JavaScript includes in .

    How do you normally approach this?

  33. @Thomas- Sorry for being dump here. Are you referring to create a custom module for “another block”. Please explain what do you mean by “new reference” and “another block”.

  34. Magento version
    Dear hansen,
    we have gone through all the posts, excellent discussion but couldn’t solve our simple problem i guess.

    we are simply trying to display a news ticker on the right column of our home page.We are successful in creating a static block on the right column from the admin interface but data of news updates is required to be fetched from database.we have no clue how to fetch and display data on our static block. Design guide doesn’t say any thing on the topic.
    A quick help is appreciated.

  35. @ Zahid – you should not be using a “static” block to fetch database content. You should create a new reference or create another block to pull it in.

  36. @seif That is indeed possible, if you copy the page refrence code to the xml you can change everything.

    For example the category page is ‘catalog_category_default’. You can find it if you look in your page source, it’s attaced to you body class (don’t forget to change the – with _ in the xml).

  37. Hi .
    Thanks for this article , well done .
    Can i use local local.xml to force the template in every page to 3columns.phtml ?
    Thanks !

  38. Thanks for this article it is very helpfull, i was looking for this kind of tutorial.

    Question tough: For example if i want to remove the ”My Cart” link out of the, what is the best way to do this? Because in the checkout.xml this is inserted using a so i can’t remove this using of because it isn’t a block (am i right or am i totally thinking wrong)?

    Also how can i change the quantity of the upsell blocks on the product detail page using the local.xml


  39. Hi, this post has been quite useful to me. Thank you.

    I do have a question following from it, though. It seems like if you use a local.xml file that you would be updating the layout of every page with that theme.

    If this is true, then every unique page would require a new theme. It seems like that would be bulky, time-consuming and difficult to update.

    Is there a way to get the local.xml file to make different changes to the layout based upon the template which has been chosen for the particular page? Or have I misunderstood what Magento is doing?


  40. Custom Layout Update,it can work, thanks for your share.


  41. I am trying to move the breadcrumbs on the Product View Page, so that it appears just below the product name. Is there any way to achieve this. Thank you for your great tips.

  42. @Jonathan_Hodges: Thanks, that worked like a charm. Didn’t think of doing it that way. I found an article that in navigation.phtml loops through all cms pages and adds the cms-pages to the navigation. I think that fogged my “clear thinking”. Happily, I posted my problem here and now I’ve got it working. Thanks again.

  43. @Percy: You could add your static block in the default layout handle and echo it in the top of the footer template. Then unset child in the footer block in the layout handles for My Account and Checkout pages.

  44. I am wondering if the following is possible:

    I want to add a static block to the bottom of the content (between content and footer) for all pages, except for the checkout pages and the “My Account” pages. All other pages, being all CMS, Catalog, Products.

    It seems to me that there should be a possibility to set this in the local.xml layout file. Can you help me with that?

  45. Hi I’m completely new to magento. I just want to know where do i go to edit code. Is it through the Magento dashboard? Thanks i appreciate any help for this newbie.

  46. I am so confused. Sorry! I cannot figure this out. Why is it so difficult to edit the top menu bar with cart, login, etc? What file do I go to so I can just edit it, or put a stupid breadcrumbs add-in to manage the links myself? Sorry, I have searched at least 30 blogs and not gotten an answer and everything I try crashed the site, been working at it for at least 6 hours now, and it is late and the pub under my office is having karaoke night to top it off. hahahahah! Thanks for any help.

  47. I think managing all custom updates via local.xml is a bad idea.

    If your upgrading Magento you should still merge any changes to layout or template files. This method does not solve that issue, it only makes it more difficult to track down which files need to be merged. For instance, if an update include some new blocks in you really wouldn’t be able to find out unless you went through all the diffs between magento and then your custom theme.

    Your custom layout changes should be all in your custom_package/default (assuming version 1.4+ which falls back to base/default).

    If you’re running on a version of magento that falls back on base/default then it’s possible to only update the necessary files in your custom package and theme directories. When you upgrade, you compare the changes between the old and new magento versions, check if any of those files exist in your custom theme and only merge those files.

    I’ve stared a script to help speed up this process,
    As a bonus it can also scan app/code/local for php classes which extend core magento classes and inform you if they should be reviewed. Currently only runs on *nix systems due to the use of the diff command.

  48. @hartog actually in 1.5 the code has just been moved to a different method. Have a look in public function getFileLayoutUpdatesXml in the same file, line 418

  49. Thank you for this tutorial, it´s really good. I was wondering if it´s possible to add simple text via local.xml, like a phone number, or an adress into the top.links section, I just can´t figure it out. Cheers!

  50. I’m trying to add a new / custom reference to my store. I’ve set it up so that I’ve got custom_content reference in my xml under the <catalog_product_view> and it set to getChildHtml(‘custom_content’) in the view.phtml file. I’ve also added the custom page in my page.xml file, so it registers.

    However, a LOT of basic stuff is yanked out immediately (like the Add to Cart button). When I add it back in local.xml I get a javascript error Cannot call method ‘submit’ of undefined.

    If I copy the ENTIRE content reference from catalog.xml I still get the same error. What am I missing?!


  51. Ended up being a jQuery / Prototype conflict. I simply had to add jQuery.noConflict() at the end of my jquery.js file. I thought by replacing the $ with jQuery it would have fixed it originally.

  52. @ hartog – the code is still there, just moved a little – see line 418

  53. By the way, in case you haven’t seen it, check out Alan Storms “Layout Unremove” extension. Lets you “undo” remove tags using your local.xml file. You can just add:

  54. Allas…

    The code that makes using local.xml possible has been commented out in 1.5.x :-(

  55. @Mike plant
    I’m sure you have found the solution to your issue already, but can you not use the local.xml file for your theme to remove the specific block?
    <reference name=”root”>
    <remove name=”product_list_toolbar”/>

    @ehanson or whoever wrote this
    This has been very useful to me! Thank you for this post and your contribution to the Magento community! The file really needs more documentation as well as a central repository for information like this. But then I suppose Magento as a whole could use better documentation.

  56. Ok I figured it out. I commented out the code for the logo in header.phtml.

  57. Ok here we go!

    <reference name="header">
    <action method="setTemplate"><template>page/html/homeheader.phtml</template></action>
    <action method="unsetChild"><name>logo</name></action>
    <remove name="logo"/>

  58. The code did not come through ok. Let me try again. I tried this:


  59. ok I am not posting the code correctly I put it in “code” tages. HMM. Maybe you can help anyway because you probably know the answer. Thank you.

  60. Any advice on how to use the custom layout update field in the CMS pages admin for the homepage to remove the logo form the homepage only.

    I tried this :


    and that did not work. I also tried it with “remove” that did not work either. I also put it in a separate tag and that did not do it either. Any tips. Thank you!!!

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

    what can not be controlled from this file?

  62. First off Great tutorial…

    My Question is:
    Would you know if it is easily possible to have a static block hidden on a category page if product page != 1. (obviously when product paging is on)

    What I’m trying to achieve is to only display the static block (as assigned in the Manage Categories> Display Settings > Display Mode >”Static Blocks & Products”) on the first page of the particular category. When paging through to the next pages essentially I only want to display the product thumbs and hide the static block.

    Is there any Custom Layout Update that you can suggest. Or at least point me in the right direction?


  63. page/2columns-right.phtml

    You’ll need to set the template again for pages that are set to one of the other templates in base/default.

  64. Sorry I will try an html encoded version,
    <?xml version="1.0" encoding="UTF-8"?>
    <reference name="root">
    <action method="setTemplate"><template>page/right.phtml</template></action>

  65. I am trying to use the local.xml file to update the default template to page/2columns-right.phtml. The xml I am using is as follows.


    But for some reason it doesn’t seems to be in effect. I tried some other overrides and that is working. Any idea, what could be wrong, please? Thanks,

  66. I am quite the rookie with Magento. I am looking for the string within Magento that will get me to where exactly I need to be to replace the Magento logo and any other images. My designer has descided to disappear on me…and I am under a huge deadline. Any help would be greatly appreciated.
    Thank you in advance…

  67. @kodeeco – We don’t provide support for those kinds of questions on this blog. You might try the Magento forums.

  68. Sorry, code properly encoded:

    Lines I need to change, I want remove the product_list_toolbar:

    <reference name="content">
    <block type="catalog/category_view" name="category.products" template="catalog/category/view.phtml">
    <block type="catalog/product_list" name="product_list" template="catalog/product/list.phtml">
    <!-- <action method="addReviewSummaryTemplate"><type>default</type><template>review/helper/su.phtml</template></action> -->
    <block type="catalog/product_list_toolbar" name="product_list_toolbar" template="catalog/product/list/toolbar.phtml">
    <block type="page/html_pager" name="product_list_toolbar_pager"/>
    <!-- The following code shows how to set your own pager increments -->
    <action method="setDefaultListPerPage"><limit>4</limit></action>
    <action method="setDefaultGridPerPage"><limit>3</limit></action>
    <action method="addPagerLimit"><mode>list</mode><limit>2</limit></action>
    <action method="addPagerLimit"><mode>list</mode><limit>4</limit></action>
    <action method="addPagerLimit"><mode>list</mode><limit>6</limit></action>
    <action method="addPagerLimit"><mode>list</mode><limit>8</limit></action>
    <action method="addPagerLimit" translate="label"><mode>list</mode><limit>all</limit><label>All</label></action>
    <action method="addPagerLimit"><mode>grid</mode><limit>3</limit></action>
    <action method="addPagerLimit"><mode>grid</mode><limit>6</limit></action>
    <action method="addPagerLimit"><mode>grid</mode><limit>9</limit></action>
    <action method="addPagerLimit" translate="label"><mode>grid</mode><limit>all</limit><label>All</label></action>
    <action method="addColumnCountLayoutDepend"><layout>empty</layout><count>6</count></action>
    <action method="addColumnCountLayoutDepend"><layout>one_column</layout><count>5</count></action>
    <action method="addColumnCountLayoutDepend"><layout>two_columns_left</layout><count>4</count></action>
    <action method="addColumnCountLayoutDepend"><layout>two_columns_right</layout><count>4</count></action>
    <action method="addColumnCountLayoutDepend"><layout>three_columns</layout><count>3</count></action>
    <action method="setToolbarBlockName"><name>product_list_toolbar</name></action>

    and what I tried to do:
    <reference name="content">
    <remove name="product_list_toolbar" />

  69. I have read through your enourmous discussion, thank you for responding to everyone! I have a similar question and I can’t seem to find the answer?

    I want to remove the Sort By drop down on the Category Listing page.

    I have checked the catalog.xml and i see this:

    <!-- defaultreview/helper/su.phtml -->



    And I tried adding this to remove it:

    I have a feeling I need to do something like unset child; but what reference name do I use? I am a bit confused?

  70. @Mike Plant – Unfortunately we don’t have time to respond as we’re in crunch-mode on a couple projects. Maybe one of the other commenters on this post will be able to help you out.

  71. @Daniel: Have a read through this thread:

  72. (WordPress doesn’t seem to allow me to send with http)

  73. How can I include links to external .js files (not in my server) using this method?

  74. &&
    CMS Page



    Category Page




  75. Sorry used wrong tag for code

    CMS Page



    Category Page



    Thanks Again!

  76. CMS Page 2 columns with left bar



    Category Page 2 columns with left bar



    last try I apologize for the mess.

  77. Great article! I have had good luck using this technique and very much appreciate this article. We have been able to eliminate many core overrides that we used in our 1.3 theme using this approach. I would like to use the local.xml to define new layouts (1 column 2 column 3column) it also would be nice to be able to remove unused layouts. I have not been able to add new layouts using the mytheme/mytheme/layout/local.xml. we have tried an array of code variations it just doesn’t seem to work. I am still able to add new layouts via app/etc/local.xml and by overriding the core/mage/page/etc/config.xml. I am would like to know if anyone else is experiencing this issue and if anyone has found a solution. Here is the code I have been trying to use.
    CMS Page


    Catalog Page


    Thanks in advance!

  78. Hey ehansen, nice article, but can this also for meganto 1.4 ( I am really a newbie on meganto )

  79. @Umar: yes.

  80. @Joel – Since your question regarding Magento resources, I’ve come across this excellent resource for learning Magento development:

  81. Sorry the code is:

  82. local.xml is a great ideal.

    It seems to me there is a difference between placing xml block in local.xml file and Magento CMS page layout design field.

    For example: when I placed code:

    in Magento layout design field of the Homepage, it removes the “Log In” link from the header.

    However, when I put the same code to local.xml file, it didn’t remove the “log in” link from the header.

    Does anyone know why?

  83. < reference name=”root” >
    <reference name=”top.links”>
    <action method=”removeLinkByUrl”> <url helper=”customer/getLoginUrl”/> </action>

  84. @Martijn – I don’t know of an available cheatsheet. If I come across one, I’ll let you know.

    If you look at the public methods in the Mage_Core_Block_Abstract and Mage_Core_Block_Template classes, you’ll see most of the methods that are available to all blocks. Also, keep in mind that all Blocks extend Varien_Object which means you can set and get data using the setVariable() and getVariable() methods. Method calls like setTemplate don’t exist in the aforementioned classes – the template just gets set using the magic method in Varien_Object.

  85. @ehansen Great tutorial, thanks! I’ve been reading the updated PDF I found on . Combined with your tutorial, creating your own Magento themes makes more sense now.

    So basically, starting with 1.4, all you need, most of the time, is local.xml combined with skin parts like CSS, images and JS? I was wondering though. The XML references and all the basic functions: like removeItem, addCss etc: is there a cheatsheet for this? I’d love to have an overview of all the XML possibilities regarding managing Magento themes.

    Thanks in advance!

  86. And here’s the xml to accompany the above post:

    <reference name=”right”>
    <block type=”checkout/cart_sidebar” name=”cart_shoppingbag” template=”checkout/cart/shoppingbag.phtml”>

    Sorry 😉

  87. Hi! Thanks for this useful post. I have been successfully updating layouts using this method, but I have a problem with a global update I wanted to perform, and I was wondering if you knew why this doesn’t work:

    If I paste the same update (without the layout and default tags of course) into a cms page, the block gets rendered as desired. However, it doesn’t if I place it in any of the layout overrides in my theme’s local.xml file. I’m a little baffled by this :)

  88. @Steve – If our clients want to be able to edit all the stylesheets for a site, we generally provide them FTP access to our stage site so they can edit the CSS files directly. Other clients don’t want to edit existing stylesheets but want to be able to add small amounts of CSS ad-hoc. For those clients, we setup a “Global CSS” Static Content Block that we then output into style tags in the header of every page.

  89. @ehansen – If we can use Admin UI to edit CSS, that would be geat.
    At this moment, I am try to find a way to use Admin UI to edit local.xml file. More like an Admin UI Layout design page for local.xml file.

  90. Doing one page at a time is a lot of pain if you have thousands of pages.
    It would be nice if we can do it once and it will update, say the header, on all the pages.
    I don’t know why Magento don’t have layout design pages for the header, footer, left column, and right column on the Admin panel.

    If Magento does not support them natively, can we do it via a module?
    I see following article:
    I haven’t try it yet.

    What are the easiest way to put the header, footer, left column, right column layout xmls on the Admin Panel?

  91. @Steve – You can pretty much do anything via a custom module with Magento. What exactly are you wanting to accomplish?

  92. @Bryce (aka SEM Truth) – When we build our Magento themes, anything that the client would want to update is either editable: via a Static Content Block or via the Translate Inline feature. Ultimately, how manageable a site is determined by how well the theme is built.

  93. It appears that Steve is looking to have an admin ui that would allow for certain changes should someone want to jump into the setup of their site and update the header without having to use FTP or editing parts of the xm files etc.

    I agree that being able to edit the .css files through the admin would be an advantageous addition to the setup. Especially for web developers that want their clients to make certain changes without having to take the time to make updates that do not equate to enough hours or warrant a charge for such a small change.

  94. @Steve – No, there’s no way to edit the local.xml file from a native Magento installation. Layout xml can be added to specific product/category/cms pages if you want to edit the layout for specific items.

  95. Thanks for the helpful tip. I think this is a great way for managing adjustments to theme layouts.

  96. @David: in short, you saved my life.
    For testing purpose, i’m playing with a clean new installation from SVN (~ I didn’t change anything in header.phtml. But i didn’t change anything in, say, footer.phtml.
    I didn’t figure out that echo $this->getChildHtml() doesn’t exist in header.phtml.

  97. @Gilles: Having trouble getting the code to show…
    echo $this->getChildHtml('[cms_test_block]')

  98. @Gilles: have you also included the echo in app/design/frontend/[package]/[theme]/template/page/html/header.phtml ?

    getChildHtml('[cms_test_block]') ?>

  99. Great idea.

    Is there anyway that we can edit such XML files via Magento’s Admin Panel?
    I am trying Magento 1.4.1

  100. Hi Eric,
    Thanks a lot for this post.
    however i ran into a problem i can’t fix.
    I have spent several hours digging into the code.
    Before i commit suicide i dare ask you some help.
    Hope you can save my life…

    <reference name="footer">
    <block type="cms/block" name="cms_test_block" before="-">
    <action method="setBlockId"><block_id>test_block</block_id></action>

    ==> works as expected !
    idem for several other handlers.

    <reference name="header">
    <block type="cms/block" name="cms_test_block" before="-">
    <action method="setBlockId"><block_id>test_block</block_id></action>

    ==> does not work.

    btw the following works :

    <reference name="header">
    <action method="unsetChild"><alias>topLinks</alias></action>

    is there anything special for adding a block to header ?


    Gilles (Paris, France)

  101. So awesome, thank you for saving me an epic amount of time and hassle. You should do a Wiki on the Mage website on this.

  102. @Tom – Glad you were able to figure out a solution!

  103. Hello Eric,
    thanks a million for looking into my case. I’ve solved the issue now. Actually, I simply do a modifying of the layout handle itself. So, I do have 2 one-column – layouts which are updated within the local.xml file.
    Thanks again!

  104. @Tom – Can you convert your xml to its html entity equivalent and then post it? You can use a tool like this to convert it:

  105. …. uhmm the code belonging to the above post does not appear as I thought it will. This is the next try. Please delete it if not working.

    Thanks again & sorry for doublepost.



  106. .. no luck again. I don’t have a clue how to post code here. Will stop to try not to fully trash you website :-/

  107. Hi Eric. Now it should be fine I hope:

    <reference name="root">
    <block type="cms/page" name="homepage">
    <reference name="content">
    <block type="cms/block" name="cms_staticblockname">
    <action method="setBlockId"><block_id>staticblockname</block_id></action></block>

    Thanks again.

  108. Hi Eric!
    Thanks a very lot for your inputs. I’m just learning about Magento, so I’ve found your post at the right time.
    While dealing around with it, I’ve got one issue you could help me out with, I’m sure.

    Say, I’ve got 3 different CMS pages acting as landing pages for three different stores. So far, so good and all working fine. I also have got some static blocks ready. Now, I’ld like to specify, which static block to appear on which CMS page. I know, I can do this in the backend. But, I more like to local.xml – idea.

    To find out how it works, I’ve done a new static block “staticblockname” enabling it for all store views! The idea behind is, not to restrict the block’s validity. I must be able to put it on the CMS page (if I want it to appear there) by editing the local.xml only. So, it shall not appear on each and every site by default, just on the specified pages (local.xml). Surprise, surprise: this is not working. It in fact appears on each of those three CMS pages.

    As I’m trying around for hours now, I’ve found not to be able to directly reference to a specified CMS page out the local.xml – file. Being able to do this must also enable me to solve my issue.

    Maybe I’m just too blind to see. This is what I’ve got (working):


    Let’s do it hardcore: CMS page 1 has 1-column, page 2 has 2-columns and page 3 has got 3-columns. That’s why I’ve thought to reference to “root” – as this is changing with the default layout of my three pages.

    Finally, my big question to you is: how can I do a reference to a specific CMS page within the local.xml – file? Is there something like a … ?

    Thank you very much in advance…

  109. Tom – I dug into the Mage_Cms_Helper_Page::_renderPage() method, and it looks like default, and cms_page are the only handles that get called when a CMS page is loaded. Since that is the case, I think you’re likely going to have to resort to adding the xml to the Layout Updates section of the CMS Page.

  110. That’s ok Mr.Erik Hansan i will follow your suggetion but i wanna ask u something that everything( template,layout) we found in our theme at path C:\xampp\htdocs\magento\app\design\frontend\blank\theme003 . but now i m confude that what base directory contain about our theme C:\xampp\htdocs\magento\app\design\frontend\base\default. instead my teme is in blank directory. please clear my confusion about this.

    if u have any structure or hirerchy to find all relevent .phtml , .xml file for my theme then please recommend me. that would me worthfull for me . thank you

  111. @Agam – I’d recommend posting that question to the Magento forums.

  112. As i new to magento i enciunterd some problem that is , when i install a new theme and start working on this .i want to replace position for my cart from right to left but i checkout.xml file is not there. please tell me the solution .


  113. @Rick – This is unfortunately one of the few things that can’t be modified using the local.xml file. You can’t currently “unremove” a block that has been removed. You’re going to have to copy the checkout.xml file into your custom theme and comment out that remove line. We’ve considered overriding a Magento block to allow us to add an unremove a block, but we’ve not done that yet.

  114. <checkout_onepage_index translate=”label”>
    <reference name=”root”>
    <action method=”setTemplate”><template>page/2columns-left.phtml</template></action>
    <block type=”core/text_list” name=”left” as=”left” translate=”label”>
    <label>Left Column</label>
    <reference name=”left”>
    <action method=”unsetChildren”></action>
    <block type=”page/html_wrapper” name=”checkout.progress.wrapper”>
    <action method=”setElementId”><value>checkout-progress-wrapper</value></action>
    <block type=”checkout/onepage_progress” name=”checkout.progress” before=”-” template=”checkout/onepage/progress.phtml”/>

  115. How can you go about reactivating a left or right column after it’s been removed in the base xml file.

    E.g. checkout.xml’s onepage removes the left column, but I want a 2columns-left.phtml template. Even after calling the proper template, the remove prevents anything from displaying in the left column.


    Left Column


  116. the following will remove the paypal logo in 1.4:

  117. @jon – The method espoused in this post doesn’t hack any core code, so I’m not sure what you’re talking about. Can you be more specific as to what you think is being hacked? Thanks!

  118. first thanks for the tip!

    after looking into this a bit more, i just wanted to suggest that you update your guide.

    there is a similar approach as described in the wiki which does not require hacking the core code:

  119. Thanks – I have already made a load of modules, with their own layout files – but this is great for making small changes to the site structure, without having to either override another layout file, or add a new one via another module. I’m gonna use this for all those extra little changes that don’t warrant a full extension of their own!

  120. @Sam – If you’re creating your own module, you may actually want to create an xml file specifically for that module. In the config.xml file of your module, you can specify a new layout file using the layout tag. Search the app/code/core/Mage/Catalog/etc/config.xml file for layout to see an example of the exact syntax.

  121. Excellent find – this has just saved me a load of work creating a new module just to add a few misc layout updates – now I can just stick them all in the local.xml file and viola! Cheers for sharing this!

  122. @Steve – Based on what I remember, the remove tag doesn’t always work. Some times, you have to use action method=”unsetChild”. See the initial example XML for how to use this.

  123. Erik,

    Thank you for your time and I think I found the problem to my previous posts. I had copied & pasted your code into a file and I guess there were some extraneous characters that get inserted when using this procedure.

    So I recreated the file from scratch and for the most part everything seems to work with the exception of my left column.

    To be sure I’m not screwing anything else up I’m learning how to code the xml file using the default/default theme as supplied by magento in 1.4.1, and I have the cache turned off.

    <?xml version="1.0"?>
    <layout version="0.1.0">

    <reference name="header">
    <remove name="store_language"/> <!– This works –>

    <reference name="left">
    <remove name="left.permanent.callout"/> <!– This does not –>
    <remove name="tags_popular"/> <!– This does not –>

    <reference name="content">

    <reference name="right">
    <!– This works –>
    <remove name="right.permanent.callout"/> <!– This works –>
    <remove name="right.poll"/> <!– This works –>
    <remove name=""/> <!– This works –>
    <remove name="right.paypal"/> <!– This does not –>

    <reference name="footer">
    <remove name="footer_links"/> <!– This works –>

    Can you see anything in my code that I might be missing.

    BTW. Thanks for the tip about encode.aspx


  124. @Matt – Can you convert your html to its html entity equivalent and then post it? You can use a tool like this to convert it:

  125. I’ve put local.xml into my theme’s layout folder, but it doesn’t seem to load. Any thoughts? Here:s the code:


  126. Sorry, I screwed up my gt tags in the above post

    <?xml version=”1.0″?<
    <layout version=”0.1.0″<

    <reference name=”right”<
    <remove name=”right.poll” />
    <remove name=”right.permanent.callout” />
    <remove name=”” />

    <reference name=”left”>
    <remove name=”left.permanenet.callout” />

    <reference name=”head”>
    <action menthod=”addcss”>


  127. Thanks for the response.

    I had just omitted those lines from my post. Here’s the complete file.

    <?xml version=”1.0″?<
    <layout version=”0.1.0″<

    <reference name=”right”<
    <remove name=”right.poll” /<
    <remove name=”right.permanent.callout” /<
    <remove name=”” /<

    <reference name=”left”<
    <remove name=”left.permanenet.callout” /<

    <reference name=”head”<
    <action menthod=”addcss”<


  128. @bipedal_bill – Unfortunately I don’t know off the top of my head, so you’ll have to dig in and figure that out.

    @Steve – You need to wrap the XML in your local.xml file with the layout and default tags. See the example code block in the post for details.

  129. Thank you for explaining the correct way to modify Magento layouts.

    I’m using magento 1.4.1 and learning how to modify my layout on a local server.

    I’m using the default theme and I defined this in System>Configuration>Design, defining the Template, Skin, Layout, & Defautl as default.

    I also turned off the cache.

    I then created a local.xml file in magento\app\design\frontend\default\default\layout and added the following lines:

    <reference name=”left”;&gt
    <remove name=”left.permanent.callout”/>

    <reference name=”right”;&gt
    <remove name=”right.permanent.callout”/;&gt
    <remove name=””/;&gt
    <remove name=”right.poll”/>

    However when I refresh the home page there are no changes to the layout.

    Any ideas on what I might be doing wrong?


  130. @Steve – Unfortunately I’m not able to spot any errors with your XML, so you’re going to have to continue debugging on your own.

  131. I’ve been diggin’ everywhere on the web with no luck, you seem like a person that might know where I can edit the actual code that pulls up the tag that displays the page title in the CMS block? Not to be confused with the logo issue, I understand how that works. Is it a core file?

    Thank you kindly.

  132. Hi,
    thanks for this tips (an other version of local.xml can be found in the last version of the magentoecommerce wiki).

    I’ve a little question (Magento 1.4.1) : I create a new theme and place this local.xml in /magento/app/design/frontend/default/mytheme/layout/local.xml
    But all the modification I’ve write in it doesn’t work… (I change the System>>Configuration>>Design : Themes >> default field to “mytheme”)
    If I put this local.xml file in an existing theme that not work too…
    (Same problem with the custom /app/design/frontend/mytheme/templates/page/html/xxx.phtml by the way)
    May I miss something.

    Thks for help.

  133. @Mickael: have you turned Magento’s caching off?

  134. Thanks a lot ! (and shame on me)

  135. ehansen, is there a way that I can PM you the exact code I have been working with?

  136. You can email me at erik AT

  137. FYI, in you should name it local.xml, not layout.xml for Magento to read it properly. Here’s the documentation for that: Designing for Magento

  138. whew, been a long day…nevermind what I just said 😀

  139. Hi

    Like Josh, I too am trying to remove ‘My Downloadable Products’ from the menu in the My Accounts section. OK, I can comment out the downloadable.xml in the base folder, but in the spirit of things, it’d be better to override this in local.xml.

    I’ve tried out the removeLinkByUrl method like, but it only throws an error. I’m a bit stumped (many things in magento stump me) – what is the helper method in the tag?


    My current code is:

  140. ehansen – thank you

    The layout update is as follows:


    This is great for adding something to a sidebar. But if I am trying to add this layout update and call it within a specific place within the homepage or a CMS block:

    {{block type=’feedreader/sidebar’ name=’left.feedreader’ template=’feedreader/sidebar.phtml’}}

    how would I be able to set actions or assign the layout update to a specific place within the layout of my design?

  141. blog_news

  142. Thank you for this post I found you via the Magento forum.

    really helpful….

  143. @David – Glad you found it useful. Thanks for the heads-up about the “magentoexpert” site. I’ll contact them requesting they remove the plagiarized post.

  144. Thanks for this gem – I’m now using it for all future themes.

    This post has been aped without credit at

  145. @Josh – There’s a removeLinkByUrl method – check out our posts about editing Magento’s top links and editing footer links for a more detailed documentation.

  146. Thanks for the reply. I have another quick question, is it possible to remove links (do the opposite of method=”addLink”)? I am trying to remove some links from the my account sidebar block (customer_account_navigation) and I didn’t know if this was possible from local.xml.

  147. @Josh – Sorry for not getting back with you sooner. Glad you figured out your initial questions. Is this possible without overwriting the customer.xml? – Unfortunately it’s not possible to “unremove” a block that’s been removed. This is one of those instances where you’re going to have to edit one of the core layout files. If you have to edit one of the core layout files, I would recommend commenting the lines you edit. Also, if you’re using svn (or any other source control system) I’d recommend doing an “svn cp” of the core layout file to your custom layout directory and then making the edits. Doing so will ensure that the edits you make to the layout file show up as a changeset in svn.

    @Jo – Most of the “action methods” are contained in the Mage_Core_Block_Abstract class. In case you didn’t know this, the <block> syntax corresponds directly to Block classes that are found in the app/code/core/Mage folder. So a block tag with the type of “catalog/product_view” uses the Mage_Catalog_Block_Product_View class that can be found in the app/code/core/Mage/Catalog/Block/Product/View.php file. The “method” attribute value on <action> tags correspond directly to method names on the block.

  148. Hi,
    this is a really helpful article.

    I found a lot of pre 1.4 tutorials, mainly copy layout and edit directly, but I prefere this new way of modifying themes.

    Does anybody know where to find all of those action methods`?
    Possible values etc

    Thanks in advance,
    (greetings from germany)

  149. So I got past my initial issues and I am successfully designing a theme based on your method.

    I was wondering if it is possible to override a remove call in a different layout xml? Basically, in the default customer.xml in the customer_account_login layout the left block is being removed. I want to override this in my local.xml so the left block will display for that layout. Is this possible without overwriting the customer.xml?

  150. Thanks for the tips. So if I wanted to change the default template layout to 2columns-left I would just added the following to the local.xml section?


    Also, with just using local.xml (and not recreating a page.xml) I should be able to override templates like 2columns-left.phtml and header.html correct? It does not seem to work for me and I just wanted to verify that in theory it should. I just have .phtml copies from the default theme with a some simple html changes for testing. I have them located here:


    My css changes in skin\frontend\default\mytheme\css\ were picked up but from some reason none of the template changes worked.

    Any thoughts or any help in general would be great. I would love for your theming method to work for me.

    Thank in advance.

  151. Yes, sorry about that. I used the code block instead. Here are the lines I added in the default section of local.xml:


    Also, any thoughts on why the system is not using mytheme’s defined .phtml files?

  152. not sure why the pre tags are not working for me either. Here’s another go. Feel free to delete these comments.


  153. @Josh & SEM Truth – Can you post your code examples inside of blocks like this so I can respond to your questions:

    <pre lang="xml" colla="+">
    …your code here…

  154. Here is the code:

    Blog Posts

  155. Your information is insightful and I strongly feel that you are the one to assist with the following two updates I am looking for.

    First I am looking to update a category through the Custom Layout Update and remove the prices from displaying. I would be looking to remove the price-box from that specific category. Something along the lines of:

    Also I have another snipet of code that I am using to which calls a specific file – template\feedreader\feedreader.phtml.

    In adding that file to the layout an update to the layout is added:

    Blog Posts

    However I am unable how to add this information to a specific place on the homepage. Can I create a CMS Static Block and use these functions that are necesasry to allow the feedreader.phtml to run? Or can I add a block to the homepage through the homepage Layout Update XML, and force the feed to display in a specific Static Block on the homepage?

  156. @ehansen – thanks, yeh I need to read SOME book, just didn’t know which one I could read that wasn’t too out-dated! Thanks for the recommendation on this book – I’ll give it a look over.

    I am familiar with OOP – and haven’t really poked around in the core modules yet, kind of wanted to read documentation before doing that.

    Thanks again.

  157. @ehansen Can you direct a developer to any in-depth resources as to the structure, classes, etc of Magento? Documentation seems to be sparse which is making learning frustrating.

    Thanks for your advice!

  158. @Joel – I would recommend reading PHP Architect’s Guide to E-Commerce Programming with Magento. The first 5~ chapters provide a really good insight into the structure of Magento. After reading through the first 5~ chapters, you should start digging into Magento’s core modules. The app/code/core/Mage/Cms/ and app/code/core/Mage/Customer are two good modules to start with. Note: The book was written over a year ago, so a lot of the examples in the book are out-dated.

    In addition to reading that book, it’s important to have a solid understanding of Object-Oriented PHP.

  159. @Jenn – Yes, that is possible. You can do that using the “append” method:

  160. Is it possible to add something to another column through this method? For example, if I wanted to remove the cart sidebar from the left column and add it to the right column how would I do that?

  161. @Phillip Jackson – Yes, that is possible. Here’s the layout xml you’d add to replace a product description with a static content block:

  162. Great tutorial my friend –

    Is there any way you can add/override blocks by their named attributes by using admin layout updates? For instance, on a product page I would like to use a CMS static block in place of the product descriptions – or sometimes to insert a small static block (e.g. advertising, etc.) above the add to cart button on a simple product page.

    Any ideas?

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=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">