How to Use XML Layout in Magento

In Magento, layouts determine which content blocks are placed within Magento framework patterns (.phtml files), that in their turn determine the complete structure of a store’s template. Magento layout XML files are located in the app/design/frontend/your_interface/your_theme/layout/ Magento installation directory.

To figure out which interface or template is used in your store see System-> Configuration->General->Design. Current Package Name is an interface name for a particular web site or store. In default Magento default theme and interface are used (layout file path app/design/frontend/default/default/layout/).

Default Magento Layout

Magento layout is comprised of default layout and layout updates.

Default layout indicates a structure unit (footer, header or left column) that contains smaller units (for example, Catalog Search, Shopping Cart, RSS subscription form) and is defined in main Magento Template.

Layout update rewrites standard layout for a particular view in Magento, for example, Checkout or product page.


Layout structure

Layouts are tied to a particular application or module. After you create a new layout you should indicate which module activates it. You should add the following code into your extension’s config.xml (app/local/you_name_group/you_name_module/etc/config.xml)





                < you_layout >


                </ you_layout >




Frontend indicates that your layout is used on Magento front end. Change it with adminhtml, and it will be used on the back end.

Minimal requirements to the layout file:

<?xml version="1.0" encoding="UTF-8"?>






First tag points out xml version and layout file encoding.

Layouts contain blocks and blocks’ operations.

Now let’s see how to work with layouts and take Search bar as an example.

Let’s disable Search bar on Magento front end.

Disabling search bar on Magento front end Disabling search bar on Magento front end


        <remove name=""/>


The tag “Remove” removes search block from displaying. “Name” indicates which block we are removing. The Search bar in default Magento template is defined as “” in a layout system.

Default indicates that we remove Search bar from any page of the given template. In order to remove the bar from a specific page, use other tags.  Such tags are called descriptors. Descriptor is a reference name that is used in Magento to refer to a specific representation(s).


Now let’s see how to remove Search bar from a particular store view (French in this example).


        <remove name=""/>


The descriptor STORE_french indicates that all the actions within this block apply only to French store view. To find the code of a particular store please go System-> Configuration->Manage Stores on the back end.

If you need to apply the action to a particular web page, use module_controller_action descriptor. To see how it works, let’s remove Search bar from the customer login page.


        <remove name=""/>


You can use URL to get the address and tag name of the necessary web page.

Particular web page layout

There are some exceptions to this rule. For example, the main page has cms_index_index descriptor. Below you may find a few descriptors that may come in handy for your Magento web pages:

  • catalog_category_default -  default front end catalog page;
  • customer_account – customer’s account;
  • catalog_product_view – product page;
  • cms_page – web pages that were created with Content Management System;
  • checkout_cart_index – default checkout page;
  • cms_index_defaultnoroute – default 404 error page;
  • cms_index_defaultindex – Magento homepage.



“Reference” command applies to the block so you can set necessary actions or add sub-blocks. It is used with “name” attribute. To apply to a particular block you should indicate its title in the reference command. All the blocks have unique names. To see how this command works, let’s change Magento default template:



        <reference name="root">

            <action method="setTemplate"><template>page/new_template.phtml</template></action>




Here we applied the command to the root block and changed a template with the new one. new_template.phtml file should be stored in app/design/default/defult/template/page/new_template.phtml.

The tag Action allows applying to any method of the block. You can see examples of default methods in Mage_Core_Block_Abstract class and in its ancestor class -  Varien_Object.   The arguments keep same order in the method as they were addressed in xml file. Each block may have its own methods. For example the block “head” (html <head></head>) has addItem, addJs and addCss methods.

        <reference name="head">

            <action method="addJs"><script>aitoc/aitcg/colorset.js</script></action>

            <action method="addCss"><stylesheet>aitoc/aitcg/css/colorset.css</stylesheet></action>

            <action method="addItem"><type>js_css</type><name>aitoc/aitcg/aitcg.css</name></action>


The code calls addJs method in the “head” (reference name="head") block. This method  has  “aitoc/aitcg/colorset.js”  parameter. Here are the methods that the code can call: addJs(‘aitoc/aitcg/colorset.js’), addCss(‘aitoc/aitcg/css/colorset.css’), addItem(‘js_css’, ‘aitoc/aitcg/aitcg.css’). They all add new js file and a new stylesheet. With addItem you can add any other styles.

Some useful action attributes:

  • <action method="setTemplate"><template>page/new_template.phtml</template></action> - identifies new template for your blocks.
  • <action method="addLink"><name>account_edit</name><path>customer/account/edit/</path><label>Account Information</label></action> - adds a new link. This attribute is used in Magento menu.
  • <action method="setData"><key>category_id</key><value>99</value></action> - identifies a particular parameter (in this code it is category_id) that will be used to call the block.
  • <action method="setChild"><name>totals</name><block>totals</block></action> - add the block totals into the sub-blocks array where it is applied.
  • <action method="setFrameTags "><openTag>div</openTag></action> - adds a tag frame into the block (here, tag “div”).



The results of the actions performed by using the tag “action” depend on your store’s settings (or store view settings). Have a look at ifconfig/unlessconfig parameters. The first one allows to perform an action when the particular parameter is switched on, the second allows, when the parameter is switched off (i.e. vice versa). Let’s connect the new CSS file (new.css) when we have dev/log/active switched on.

        <reference name="head">

            <action method="addJs" ifconfig=’dev/log/active’ ><script>new/ new.css</script></action>



New blocks

New blocks can be created by means of the tag called block.

<reference name="content">

    <block type="core/template" name="contactForm" template="contacts/form.phtml"/>



This code adds the new block called contactForm into the content block by means of contacts/form.phtml template. contactForm is a block with a core/template (a default type, that displays the template as it is with no additional actions, Mage_Core_Block_Template block class).


    <block type="core/template" name="contactForm">

                <action method="setTemplate"><template> contacts/form.phtml </template></action>



    <block type="core/template" name="contactForm">

                <action method="setData"><key>template</key><value>contacts/form.phtml </value></action>


Both these codes apply same changes.

This code allows inserting the block into the very end of the content block. To set a specific position for this block, use before/after.

<reference name="content">

    <block type="core/template" name="contactForm" template="contacts/form.phtml" after=’-‘/>



This code indicates that we add the block into the very beginning (before=’-‘(dash) indicates that there are no preceding blocks, it is the very first one). If you need to specify the block after which the particular block is displayed, insert the name of the block after the parameter after.

     <reference name="footer">
<block type="cms/template" name="cms_footer_links" after="footer_links" template="contacts/form.phtml" />


This code adds a new block into footer under the footer_links block.

Static blocks

In Magento you can create static blocks that are stored in the database.  You can create them in the Magento Admin panel: CMS->Static Blocks.

Let’s create a new block for test and name it new_block_for_test.

New block creation

And add it to the header under the menu bar.


        <reference name="">

            <block type="cms/block" name="new_block_for_test" after="-">

                <action method="setBlockId" ><block_id>new_block_for_test</block_id></action>




Here  new_block_for_test is the name of the created block and cms/block is the block’s type.


Here is what we’ve got:

New block creation

Here are a few blocks that may come in use:

  1. core/template: displays Magento template as it is.
  2. page/html: is a template for separate Magento page.
  3. page/html_head: html head.
  4. page/html_header: Magento header.
  5. page/template_links: the block of links’ list. You can use it as a menu.
  6. page/html_breadcrumbs: breadcrumbs of the current page.
  7. page/html_footer: the footer.
  8. core/messages: the block contains error/success/notice messages.
  9. page/switch: changes store language or a store view.


We hope you’ve enjoyed our tutorial. If you want to show us your results, leave a link of your web site and a short description in the comments below.

3 Great Magento Solutions for mCommerce Previous Post
Magento and PayPal Sandbox Setup Next Post