The basic guide to Magento layout development

Structure of layout

Layout definitions are always connected to a given extension. They can be set in the extension’s config.xml file on the customer page as the following:

<aionmodul module=”Aion_Modul”>

And also on the admin page:


The tag within the <updates> tag should be a unique name.

You can see in both cases that the name of the layout file should be defined in the <file> tag. The layout files are to be found in the app/design/frontend/[package name]/[theme name]/layout, and the app/design/adminhtml/[package name]/[theme name]/layout directories.

In the XML file, it should be defined between the following tags which layout handler the command (tag) should consider.

<layout version=”0.1.0″> 





Function of layout handle

Block definitions are always located within a well defined handle. A layout handle designates a collection of more blocks with a name. The default layout handle is added to every page in the given scope. The main page is built up according to the following layout handles:

  1. default
  2. cms_page
  3. STORE_default
  4. THEME_frontend_rwd_default
  5. cms_index_index
  6. page_two_columns_right
  7. customer_logged_out
  8. cms_menu


Indeed, the default handle has also been given to this page. The cms_page, cms_index_index and cms_menu handle also loads which means that the main page is a CMS page too. The same list looks like this on a login page:

  1. default
  2. STORE_default
  3. THEME_frontend_rwd_default
  4. customer_account_login
  5. customer_logged_out


The 4th handle defines that at the moment customer front name, account controller and login action serve the page. In the case of the main page, these are cms front name, index controller and index action.


layout magento


Function of blocks

In the above examples we have touched on blocks marginally, but now let us see in more detail what blocks mean in Magento. Below you can see a list of the different types of Magento blocks:

  • core/template: This type of block is responsible for rendering templates. The majority of blocks belong to the core/template type.
  • page/html: This block type is derived from a core/template block. It defines the parent block. Every other block is a child block of page/html block.
  • page/html_head: This block type is responsible for the HEAD section of an HTML page. Thanks to it, we can define JavaScript, CSS etc. items.
  • page/html_header: It is in charge of displaying the header of the page. Here we find the logo of the ecommerce store, top links etc.
  • page/template_links: This block type is used for creating link lists. Links are displayed in the header and footer by default with the help of the page/template_links
  • core/text_list: Some page elements (content, left sidebar, right sidebar) are displayed with the core/text_list block. When these block types are rendered, all their child blocks are rendered automatically. An important feature of core/text_list block types is that they do not have templates.
  • page/html_wrapper: This block type can be used for wrapping other elements. It uses <div> tag by default.
  • page/html_breadcrumbs: This block type displays breadcrumbs on the page.
  • page/html_footer: This block type displays the footer where you can find copyright details, footer links etc. by default.
  • core/messages: This block type shows the messages. A message can be an error, success or warning type message.
  • page/switch: This block type displays the drop down language selection options.


Of course, these block types are only the default types. There can be others created according to the custom design theme or extension requirements.

Each block must have a type and name. Block template and alias are not necessary.

With a reference tag you can refer to existing blocks. If you already have a larger block and you want to display elements in it from several layout files, then you need to implement a reference tag. Here is an example:

 <reference name=”right”>
<block type=”core/text” name=”right.text”>Bal oldalt megjelenő szöveg</block>


We gave a new block, named right.text, to the block called “right”.

This is a very useful method when you would like to modify an existing page in your own extension. We can also remove an already added block. Here is an example:

 <reference name=”right”>
<remove name=”right.text” />


We removed the “right.text” block, created in the above example, with the remove tag.

If we don’t know the name of the given block or which template manages displaying, then it is very useful to switch on “template path hint”. You can do this by setting the System -> Configuration -> Developer -> Template Path Hints option to YES. Please note that this setting cannot be set “globally”, it can only be set in website view. If you want to see the classes of the blocks, then in the same menu set the Add Block Names to Hints option to YES. If your website is live, be careful because your visitors may be taken aback seeing your page like this:


magento layout Template Path Hints



You can see the template path on the left and the block’s name on the right.

It is also possible to have the template path hints shown only to you. In this case you insert your computer’s IP address in the Allowed IPs field in the System -> Configuration -> Developer menu.


Management of CSS and JavaScript files from layout

Many times it is needed to implement external resources (CSS and JavaScript) on your page. This can be easily done from layout XML with the following tag:

 <block type=”page/html_head” name=”head” as=”head”>
<action method=”addJs”><script>prototype/prototype.js</script></action>

<block type=”page/html_head” name=”head” as=”head”>
<action method=”addCss”><stylesheet>css/widgets.css</stylesheet></action>


In the first example we insert prototype.js from the js directory, in the second example we insert the widgets.css file from the skin directory.



Using layout update

You can add a new handle to an existing one with the update XML tag. Let’s suppose we’d like to add a hello layout handle to the content block of the cms_index_index layout handle. This can be done the following way:


<update handle=”hello” />


Here, all modifications of <hello> handle can be valid for the main page (<cms_index_index> handle). This comes in handy if you want to display a contact form on several pages, since you don’t have to insert the block definition of every contact form on each of the pages. It is enough to insert it in a new handle and load that handle on the specific pages with the update command (tag).


Typically, in case of new design themes, developers do not refer to existing layout files in the local.xml, but copy and paste them, as they are, to their design theme directory. This “improper” method is not recommended at all, because if an update is issued which would affect the layout files as well, this update will fail, as the files will not be overwritten in the new design template.

I admit that the solution I recommend is a little more complex and may not be applicable to every case in this field, but it still is more advanced, especially in the long term.


SUMMARYAs we could see from the examples, layout XML is an essential part of Magento. That is why it is important to know it thoroughly. I hope this short guide will be useful for many Magento developers. Should you have any questions, we will be happy to give you an answer.



1 reply

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published.