Custom Magento CMS page layout

Custom Magento CMS page layout

Last week I had a request to add new custom layout for few cms pages in one Magento shop. It’s really useful for different static pages of your shop. First create extension with only config file in it: app/code/local/Inchoo/AdditionalCmsPageLayouts/etc/config.xml

<?xml version="1.0"?>
     <label>Custom static page 1</label>

Then activate it: app/etc/modules/Inchoo_AdditionalCmsPageLayouts.xml

<?xml version="1.0"?>

Clear cache, add your page/custom-static-page-1.phtml template file (or copy some default one for start) to your current theme and you’re done 😉 There is also tutorial about this on Magento Wiki. And yes, default Magento page layouts can be overridden the same way. Default layouts config can be found in app/code/core/Mage/Page/etc/config.xml along with used xml code structure, so check it out. Thank you for listening!

You made it all the way down here so you must have enjoyed this post! You may also like:

How to keep your CMS blocks organized (and not go insane) Adrian Bece
Adrian Bece, | 10

How to keep your CMS blocks organized (and not go insane)

Injecting Variables into a Magento CMS static block Thomas Spigel
Thomas Spigel, | 9

Injecting Variables into a Magento CMS static block

Magento CMS syntax – part2 Ivan Weiler
Ivan Weiler, | 16

Magento CMS syntax – part2


  1. Matt W, and everyone,

    Your summary is great; however there are so many things which are IMPLICIT, that I still find a workable path thru it.
    Like so many others, I need to make a new base template (and later a set of them). I need the ENTIRE, EXPLICIT set of instructions, with the DETAILS made fully explicit too. While it is certainly not your responsibility to create this explicit explanation, it sure would be good if someone could do so – referencing the most modern versions of Magento, with everything tested.


  2. @Everyone who this doesn’t work for:

    Try this:
    1. Install Module
    2. Log out of Admin panel
    3. Log back into Admin panel
    4. Go to System -> Cache Management
    5. Flush BOTH caches (and I can’t stress this enough)
    6. Check if module is working

    If it IS now working:
    You’re done. Don’t forget to flush the cache next time you add a module.

    If it is STILL NOT working:
    1. Go to System -> Index Management
    2. Re-Index all of the indexes
    3. Check it again

    If STILL NOT working:
    1. Make sure your module is recognized
    – System -> Configuration -> Advanced Section in left menu -> Advanced
    2. Look for your module in the list
    3. If it is on the list and is still doesn’t show your custom layout:
    Make sure you have all of your files named correctly and that your XML files are placed in the proper places at app/etc/modules/Namespace_Module.xml and app/code/local/Namespace/Module/etc/config.xml

    If it’s not on the list:
    Make sure you are uploading everything to the correct locations.

    NOTE: If you are using a custom theme, you will need to place any layout files and any template files in the proper directories inside the theme you are using.

    Normal location: MagentoRoot/app/design/frontend/default/default/template/template-location-from-config-xml.phtml
    Custom theme location:

    The template location you specified in config.xml will always be relative to the template folder inside your active theme. This is also the same for any layout.xml files you may have in this or other modules.

    Hopefully something I have suggested here will fix your problem.

  3. Add me to the list of people where this is working locally but failing on a live site. I cannot see any of the custom layouts in the drop down menu, however everything is working fine locally. These are identical magento versions with identical themes and databases…grrrr

  4. FYI, you can add the above code in CMS > Design > “Layout Update XML” field and select any template from the dropdown.
    No need to edit any file or create an unnecessary module just to get an option in the dropdown.

  5. In the later version, you need mark the page block know you’ve applied the new template.

    Here’s the new code:

    <reference name="root">
    <action method="setTemplate">
    <action method="setIsHandle">
  6. It is not working in case of Magento ver. .
    I can see it in the admin panel and chose the layout but the page uses the 3columns.phtml template.
    Any idea?

  7. There’s any way of adding new page layouts using exclusively local.xml in design folder? If yes, how?!…

    Thank you!

  8. Even when this post helped me a lot to understand the process, I even refined it here: I explain the “why” for some things and also, the code is visible (I don’t know what happened on the code section on this post, but for me it’s very hard to read the light font color over light background).

  9. Hi, thanks for your article, it’s very helpful.
    Maybe this post is not the right place, but I have a question.
    I want to put in cms page a few div ‘s with toggle button to show/hide the div (this works with javascript). When save the cms page and test it works, then i go back and let’s say just edit the div text and save again the cms page, and now when I test the page, it does not work anymore.
    any sugestion???

  10. Just wanted to give a shout out and say that your solutions worked perfectly in under two minutes.

    Two copy pastes, create folder structure, upload, done.


  11. Perhaps this example is outdated. I’m working on the current version of magento and nothing shows when I try this.

  12. I had few problems with Magento Enterprise

    The config.xml file had to have a config module included

         <label>Custom static page 1</label>

    Now I was trying to have it being disabled in the System Advance configurations and when I turn it off it does not work. Is there a way to have it disabled when picking a different website. I have multiple website on single install and i just want to enable the Module for the site that it was build for.

  13. Plz help me………..
    I have 1 index.html file which contains link to css and js files in section and page layout .
    my css,js and images are placed in skin folder new package/new theme/….
    but its not working so any body tell me where and how can i put my html file so that i can get correct result….and the type of thing i’m creating should look like this
    go to :
    thank you

  14. D’oh! put that wrapper on wrong. Sorry, here’s the right code:

         Custom static page 1

    Sorry ’bout that.

  15. Hey, I just wanted to give you a quick heads up because there’s a slight bug with this method as you have it right now.

    You need to add a line in config.xml for “layout_handle” (it holds the id used for layout caching). Otherwise, you’re likely to get an error that says,
    “Invalid id or tag: must use only [a-zA-Z0-9_]”
    if layout caching is turned on.

    Here’s an example:

    Custom static page 1


    Ta, and thanks for the great resource, inchoo!

  16. if any one is interested, i solved this by doing the following :
    In the edit cms page, i chose the default “Empty” layout and added the following the Layout Update XML:


    my home.phtml now works exactly like it should work in Ivan’s article above.

  17. Ivan (and anybody else)

    Opps… spoke too soon.

    It works great on my local dev environment (Win7, Apache 2.2, PHP 5.2) however the same code won’t run on a staging server (Linux, Apache 1.3.33,PHP 5.2). I’ve done the following:

    – Checked permissions on the files and dirs. (set to 755 but changed to 777)
    – Disabled and re-enabled in “advanced”
    – Tried different names, and encodings (default is UTF-8)
    – Made sure all files are present.

    Ok.. now I’m stumped any thoughts?

    Thanks again.

  18. I have created custom template and done all the neccessary changes in Config.xml and module.xml file but my layout is not lising in cms page.

    anyone can help me out

  19. Thanks for the info !!

    Yes i just checked, <cms> is replaced with <page> in newer versions. I’m sorry your example got stripped 🙁

  20. @Ivan Weiler
    On my local machine (XP), its working but surprisingly its not working onto server (Linux). I have uploaded files properly. Not showing new layout at admin panel.

    Any idea?

    Thanks in advance!

  21. Hello and thank you for reporting this. I got some troubles while publishing xml in this post.

    Anyway, i just updated tag “codepool” to “codePool” in post. I think that may be the problem.

    @regges: Sorry, but there is no official Magento documentation. Many things can be found on Magento wiki and forum. My co-worker blog is also nice tutorial resource.

  22. I tried this as well with Magento v1.2.1.2 and my new template did not show up either using your details described above.

    I verified the syntax of my xml files and phtml – no errors.

  23. Hi,
    Sorry but it doesn’t seems to work for me. I run the 1.3 version. Could I ask for some description (docuemntation?!) of the config.xml file and how to work with them.

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> <s> <strike> <strong>. You may use following syntax for source code: <pre><code>$current = "Inchoo";</code></pre>.

Tell us about your project

Drop us a line. We'd love to know more about your project.