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:

Advantages

  • 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

Disadvantages

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

Recent Posts
Showing 165 comments
  • Phillip Jackson
    Reply

    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?

  • ehansen
    Reply

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

  • Jenn Oster
    Reply

    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?

  • ehansen
    Reply

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

  • ehansen
    Reply

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

  • joel
    Reply

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

  • joel
    Reply

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

  • SEM Truth
    Reply

    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
    http://www.url.com/feed/
    5

    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?

  • SEM Truth
    Reply

    Here is the code:

    Blog Posts http://www.athletictapeinfo.com/feed/ 5

  • ehansen
    Reply

    @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…
    </pre>

  • Josh
    Reply

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

    page/2columns-left.phtml

  • Josh
    Reply

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

    page/2columns-left.phtml

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

  • Josh
    Reply

    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?

    page/2columns-left.phtml

    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:

    app\design\frontend\default\mytheme\templates\page\2columns-left.phtml
    app\design\frontend\default\mytheme\templates\page\html\header.phtml

    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.

  • Josh
    Reply

    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?

  • jo
    Reply

    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,
    Jo
    (greetings from germany)

  • ehansen
    Reply

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

  • Josh
    Reply

    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.

  • kkirchner
    Reply

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

  • David Oliver
    Reply

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

    This post has been aped without credit at http://magentoexpert.blogspot.com/2010/05/better-way-to-modify-magento-layouts.html

  • ehansen
    Reply

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

  • Tim
    Reply

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

    really helpful….

  • SEM Truth
    Reply

    blog_news http://www.athletictapeinfo.com/feed/ 5

  • SEM Truth
    Reply

    ehansen – thank you

    The layout update is as follows:

    blog_news
    http://www.url.com/feed/
    5

    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?

  • Si
    Reply

    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?

    cheers

    My current code is:

  • Si
    Reply
  • Rick Pickett
    Reply

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

  • Rick Pickett
    Reply

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

  • ehansen
    Reply

    You can email me at erik AT classyllama.com

  • SEM Truth
    Reply

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

  • Mickael B.
    Reply

    Thanks a lot ! (and shame on me)

  • David Oliver
    Reply

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

  • Mickael B.
    Reply

    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.

  • bipedal_bill
    Reply

    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.

  • ehansen
    Reply

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

  • Steve
    Reply

    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;&gt

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

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

    Any ideas on what I might be doing wrong?

    Cheers

  • ehansen
    Reply

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

  • Steve
    Reply

    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″<
    <default<

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

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

    <reference name=”head”<
    <action menthod=”addcss”<
    <link<local.css</link<
    </action&lt
    </reference<

    </default<
    </layout<

  • Steve
    Reply

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

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

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

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

    <reference name=”head”>
    <action menthod=”addcss”>
    <link<local.css</link>
    </action>
    </reference>

    </default>
    </layout>

  • matt
    Reply

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

    Home/Home1

  • ehansen
    Reply

    @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: http://www.opinionatedgeek.com/dotnet/tools/htmlencode/encode.aspx

  • Steve
    Reply

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

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

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

    <reference name="content">
    </reference>

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

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

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

    BTW. Thanks for the tip about encode.aspx

    Cheers.

  • ehansen
    Reply

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

  • Sam
    Reply

    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!

  • ehansen
    Reply

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

  • Sam
    Reply

    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!

  • jon
    Reply

    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:
    http://www.magentocommerce.com/wiki/4_-_Themes_and_Template_Customization/0_-_theming_in_magento/designing-for-magento

  • ehansen
    Reply

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

  • jon
    Reply
  • jon
    Reply

    the following will remove the paypal logo in 1.4:

  • Rick Pickett
    Reply

    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.

    page/2columns-left.phtml

    Left Column

    checkout-progress-wrapper

Leave a Comment