The random eclecticisms of loonytoons

Magento – add custom layout template

Current magento version –

This is what you need to do to add a new layout template, eg 4 column page layout.

  1. Copy app/code/core/Mage/Page/etc/config.xml
    to app/code/local/Mage/Page/etc/config.xml.
    Creating this new file will allow magento core updates to occure without over-writing your changes (you’ll probably have to look out for changes to the core config.xml to megre them into your custom file).
  2. Register your custom module by adding a new file to app/etc/modules, called something like Mage_Local.xml
  3. In this file add the following code:
    <?xml version="1.0"?>
    <Mage_Page> //relates to file structure
    <active>true</active> //set to active
    <codePool>local</codePool> //tell which folder to look in
    <depends> //requires the mage core
  4. Now create your new template file, easy way is to copy an existing one such as 3columns.phtml (in app/design/frontend/your_package/your_theme/template/page), and give it a name, such as 4columns.phtml
  5. Register this new template in the config.xml file your created in step 1 by adding your module to the layouts list. For my 4 column example I have added:
    <four_columns module="page" translate="label">
    <label>4 columns</label>

You should now be able to access this new template in the cms->manage pages option in the magento admin backend.


24 thoughts on “Magento – add custom layout template

  1. […] LoonyBlurb – Custom Layout Templates If you work with Magento for very long, you’ll find yourself needing to create custom layout templates. This blog makes that easy to do. […]

  2. Peter Hinton says:

    Great post, I have been tearing my hair out over this

  3. I am indeed very grateful for receiving such pertinent information from your post. I do expect for
    more essential information for the next post. Keep it up.

  4. Sankho says:

    Great post! Really helped me out with a project. Thanks!

  5. Very usefull Info Thank You for sharing

  6. James says:

    Hi, i’m new to magento but just attempting this now, i have no app/code/local/Mage/Page/etc/ folder just to be sure do i have to create this or should i have this folder already?


  7. loonytoons says:

    Hi James,

    if you don’t have an app/code/local/Mage/Page/etc folder then you need to create one.
    Unless you’ve had cause to already modify this section of code then you won’t already have this in the local folder.

    Using this local folder allows us to modify sections of the core code or add to it without worrying that it’ll get overwritten during any core updates.

    Hope that helps!

  8. James says:

    Thanks for the fast help loonytoons,

    This is now working as expected, helped me out with a project and a deadline!

    Really useful post, thanks again

  9. John Natoli says:

    Thanks for this post man. I have a problem though. I followed all the steps and copied and pasted the xml exactly as you have it into a file in the modules folder, but now when i click the dropdown in the backend to assign a template, the dropdown is blank. i see //tell which folder to look in, but which folder are you referring to? Thanks!

  10. John Natoli says:

    nevermind, i figured it out. i can’t figure out how to attached stylesheets and all that via a layout now though. i had been using local.xml, but since switching templates it no longer works.

  11. Pat says:

    Thanks for the post, just what I needed, I’ve looked at a few tuts for this and none showed how to put it in local folder.

    I had caching preventing the new template showing in the backend dropdowns so deleted everything from var/cache – I’m sure there’s a much better way to do this but it worked for me.

    Thanks again.

  12. Eric says:

    Tried as indicated. When I went back to the page that I’d switched, the entire page was blank. If I delete certain portions of the file changes, I can get the page to show but not as the new template. Also, the instructions here direct me to create a layout in config.xml that references a handle, don’t we need to create a handle to match. I tried that too but that didn’t fix it either.

  13. ajay kumar jain says:


    Great post for magento developers!


  14. madzacky says:

    How to call left sidebar contents within this template?

  15. Eric says:

    I just migrated from localhost to live server and I had a page named Hompage and Product-Page, they worked on localhost server..

    Since I’ve migrated it doesn’t work? I have all the files uploaded correctly.

    Much appreciation!

  16. Hi, Can we use this code in local.xml for individual themes? I have been trying to add custom layout depends on the customer groups. Need something exact code to add in local.xml. Can anybody help me?

  17. loonytoons says:

    Sorry for the delay in approving the last few comments, I’ve been manically busy so have sadly neglected my blog for a while.

    I am also not actively working with Magento at the moment so I don’t have a working copy to look at or try things out on.

    Looking at a demo though it doesn’t appear that you can set a different layout or design in the admin based on customer group. But you might be able to do something like this in your template. Maybe try a layout handle as described here?

  18. loonytoons says:

    @eric I’m guessing you’ve figured out what the issue was by now, but that sounds like a file permissions maybe? Depends exactly what you mean when you say it doesn’t work. Let me know how you solved it though, might be useful to someone else

  19. Lalene says:

    Hi this post works on my end but I figured out the settings on the admin panel -> Design -> HTML Head -> change logo, footer, welcome msg, etc were missing after uploading Mage_Local.xml on etc/modules.

    If I will remove this file, the settings mentioned above will show.

    Do you have possible fix for this? thanks.

  20. loonytoons says:

    @Lalene Magento has moved on a lot since I last looked at it so I can’t offer you any specific advice.
    However the Mage_Local.xml file itself only registers your local module, so there must be something missing from your local module.
    Check your local config.xml and the template files to see if there’s something in the core files that should be in these files to activate those admin sections

  21. I am having a slight issue getting my page layout to appear in the cms design drop down as detailed here:

    I have all the elements detailed in your post, but not sure whats missing as everything looks to be in place and marked up correctly.

  22. loonytoons says:

    Looks like you sorted your issue. It’s always the little things 🙂

  23. Calvin says:

    I wanted to let you know this method is currently working on my 1.9.0 store. I cleared the cache, and my new layout .phtml file is working!

  24. loonytoons says:

    Awesome 🙂 Really glad this it still useful!

Leave a Reply

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