Magento Module Development Series – Part2 – Layouts

In this blog, we will learn the basic of magento layout xml files.

Magento layouts are very important for theme development. Layout are xml files located in your theme/layout folder. Layout are very power magento tools, initially tricky to understand but once you get familiar, it becomes very powerful tool. As the name suggests, layout files are responsible for setting positions of various elements on the page and determining which phtml is loaded on which page and placed where.

Layout Basics

Layout files are located in your theme inside the layout folder. catalog.xml, page.xml , checkout.xml ,etc are layout files.

Magento uses 3 things to display its pages

  1. Block Classes
  2. PHTML files
  3. Layout XML

Magento is based on MVC architecture. PHTML file contain all html(view) codes and Block classes contain all view related logic. Layout XML are the ones that relate block classes and phtml files, and define which phtml file will be used on which page and at which location.
When a page is loaded in magento, it read all the magento layout xml files in your theme, combines it and then processes it to create the view of a page.

Now we will look into the details of layout xml files

Block Basics

Layouts are basically xml files, which are divided into blocks and xml tags. Lets start of by taking an example, open the layout file catalog.xml
A basic layout block looks like

<block type="catalog/navigation" name="catalog.topnav" template="catalog/navigation/top.phtml"/><br />


  1. type = magento php file where all functions used in top.phtml are location. This the block class. For eg. In the current case it is Mage_Catalog_Block_Navigation
  2. name = any unique name given for the block
  3. template = path of the phtml file used

In the template file, we using various php function $this object.  The $this object is basically the object of the block type we defined. To see the significance of block type , open the file catalog/navigation/top.phtml
There you will find a code

<?php $_menu = $this->renderCategoriesMenuHtml(0,'level-top') ?>

So the function $this->renderCategoriesMenuHtml is a class function, which is defined in class Mage_Catalog_Block_Navigation located at app/core/Mage/Catalog/Block/Navigation.php. So if block type is wrong, then a block doesn’t work.

Child Blocks

Put one block tag inside another to make a child block for e.g

<block type='core/template' name='parent' template='parent.phtml'/>
     <block type='core/template' name='child' template='child.phtml'/>

In the phtml file parent.phtml you can access the child block by

echo $this->getChildHtml(‘child');

$this->getChildHtml function is used in various phtml in magento. It is basically used to the get the content of the its child block. Making child blocks, divides your view logic into separate files, and make reading of code simpler.

Default Tag and URL Tags

Another important aspect of layouts is how does magento to know which block to read for a particular page. For example, when opening home page, how does magneto know which blocks to display.
If you see layout files, all block declarations are placed in parent tags like


The default tag means,  all blocks inside this tag are to be shown in all the pages. So blocks like header, footer, menu etc are placed inside tag, so that they are shown in all pages.
Other tags like , are used to display block specific to pages. Like if we want to place a block on the cart page or product page then we use such tags. These tags are based on the URLs on the page.
Each url inside magento is broken down into 3 parts
For example

  1. Customer login page url is:
  2. Checkout page url is:

So the layout tag for login page would be <customer_account_login> and that for checkout page is <checkout_onepage_index>. Inside the layout files you will xml tags like <customer_account_login> and <checkout_onepage_index>,this is to specific, that block inside such tags are read on those pages and not other pages.

The Root Block and Default Root Templates

Magento default theme has 5 different type of page structures. These are 1column layout, 2 column left , 2 column right ,3 column layout and empty layout. If you open the files of your theme ‘page/1column.phtml’ , ‘page/2columns-left.php’, ‘page/2columns-right.php’, etc you will see HTML skeleton structure which has divided the page into header, footer, left column, right column, main body etc, these files make the basic skeleton of the pages in magento. You will find many $this->getChildHtml function in these templates.
The block xml tags for these pages are defined in page.xml with names ,< page_one_column>,< page_two_columns_left>,< page_two_columns_right>,< page_three_columns>

page.xml layout file, also contains an important block i.e the root block.  This block is defined inside the tag as

<block type="page/html" name="root" output="toHtml" template="page/3columns.phtml">

The root block is like the top most parent block, this block defines the structure of a page and all other block comes as children of the root block.
So, suppose if you want to set the structure of a page as 3columns, the do the below inside the page’s url tag.

<reference name="root">
<action method="setTemplate"><template>page/3columns.phtml</template></action>

Basically, this calls a function setTemplate in the root block. For example if you want the magento login page to have 3column layout. Then you need to do this

  <reference name="root">
     <action method="setTemplate">

There are few blocks which are important in magento and widely used. For example, the content block, left, right, head (these are block name), all these blocks are defined in page.xml.
Content block is used to display the main content area. Left and Right are used in 1column-left layout and 1column-right layout respectively. Head is used to add css, javascript and other html tag related work.
The important thing to know about these blocks is that, which ever child you add to these block, they automatically get displayed in them. You don’t need to call getChildHtml(‘childname’); ?> for these blocks.

Reference Basics

As we know magento layout is divided in many xml files. But there are many blocks that we want to use, lets say in catalog.xml but it is are defined in a different file like page.xml. For example the head, content, root block are all defined in page.xml but we want to use them in other layout files as well.
To do this, magento has setup the reference tag. Using this tag, we can take a reference of another block and add child elements to it or do other operations on it. For example, if I want to add a block in the left column, from the catalog.xml file. I will take reference of block left, and add a child block to it.

<reference name='left'>
    <block type='core/template' template='catalog/test.phtml' />

So, taken reference can be correlated, to make a copy of that block in your own xml file and doing operations on it.

Adding Javascript and CSS using layout xml

If you want to add javascript or css to a specific page, say you want to add it to customer login page, then this would be the way to do it.

 <reference name='head'>
  <action method="addCss"><stylesheet>css/styles.css</stylesheet></action>
  <action method="addJs"><script>varien/js.js</script></action>

You can many other ways to add js and css files in page.xml layout file.

Tutorial to do after reading above:

  • By default in magento theme, the customer login page has, 1column layout. Change this to 3column layout.
  • Create a new phtml  file called test.phtml. With the text “Hello World” in it.   This text, should come in all pages in magento. On the left column.
  • Add a new css file in the skin folder called new.css, this css should be included on the checkout page and should come in no other page.
  • Adl46652

    Great tutorial, all of these. Thanks a lot.One suggestion from me.Please add few more useful articles.thanks again!

  • Gaurang

    Give Respect Take Respect…Thats Good

  • Andrea

    Hello Manish!
    WOW, great article, you made it really understandable now.

    I need to change some links in my Magento Store, but I can`t understand how the “AddLink” action works… Do you have any article that explains how Magento inserts URL`s in Links?

    If you can explain by taking this example:
    My shopping cart link is:
    I changed the URL in control pannel, “Catalog > Rewrite URL” to:

    The next step, is to change this in the XML template files of my theme…
    Tried to change it in: app/code/core/Mage/Checkout/Block/Links.php
    But nothing happened… I didn`t understand what I was doing actually,rs

    I haven`t found any XML with function addCartLink, just this php file.

    Thank you very much.

  • bhavesh

    Excellent ……Thanks you very much for share your idea and it is perfect for beginners ….each and every topics explained step by step with example…….Cool 🙂

  • Dhayalan


    Now poll is in left side on category pages. I want to display the community polls on footer. I tried to change left to footer in local.xml file but no use. Please advice me..


  • Hoang Vuong

    Thank you for posting, very useful 🙂

  • Excellent explained! Easy to understand for anybody. Thanks!

  • Waqas Saeed

    Great article…thanks alot

  • chenthu

    This article well suited for magento beginners like me…thanks a lot…

  • Chris

    Thanks for the great article. It really shows the deeper relationship between block, layout and template files. You did a great job explaining this. Thanks!

  • gourav

    Very nice tutorial.
    I learn many basic thing form this tutorial.

  • Er Ashish Madankar

    very nice tutorials, if you provide solution on your exercise then it will be more suitable for those who have some mistakes.