Beginner—layout.xml

Question

I am new to Magento, but I have seen a lot of stuff about the layout.xml and managed the first steps of understanding the »way it works«, resulting in a module which printed magento's configuration xml on the page when I navigated to /configviewer (from within a block, not just »echoed« inside the controller).

So now I would like to get productive and I am searching for a reference of the layout.xml. All I could find so far is a reference for <block> and <reference> but there are more and where can I find the explanation?

Answer 1

So I will put together what I think is the basic knowledge you need about layout xml files. Note I may have got somethings missing but I am sure someone will add some more detail if needed.

A layout file is made up for the following section.

1. Layout Handle,
2. Blocks,

Layout Handle

The layout handle basically tells Magento when to use the xml that it surrounds. They are normally built up from the following:

1. Unique router defined in your config.xml,
2. The controller name,
3. The action taking place,

Lets take the customer my account page under the url /customer/account/index/ for an example:

First place to look is the file /app/code/core/Mage/Customer/etc/config.xml here you will find the following code:

<routers>
    <customer>
        <use>standard</use>
        <args>
            <module>Mage_Customer</module>
            <frontName>customer</frontName>
        </args>
    </customer>
</routers>

This defines that the router "customer" will use the module "Mage_Customer". So we have our router 'customer'. The controller is then the second part of the url, so in our case it is 'account'. Finally our action is the index action as stated in our url, note if it is not set then both the controller and action default to index.

So our layout handle is <customer_account_index>. You can see the default layout handle in the body of the but with - and not _.

Blocks

So to add a block it is fairly simple. Inside your layout handle add the following code.

<block type="sample/customer_example" name="sample" />

Here you will need the blocks section of your confg.xml setup as follows, where the <sample> node matches the section of the type before the /.

<global>
    -----
    <blocks>
        <sample>
            <class>Sample_Code_Block</class>
        </sample>
    </blocks>
</global>

For our example to work we would need a block file under Sample/Code/Block/Customer/Example.php

As well as the type you can specify a name this must be unique and will used later to update or remove this block. You can also specify a template here which is useful.

So say we have added our block on the customer_account_index handle and we decide in another extension that we want to remove it well we can use the remove tag at this point. Again we specify the layout handle but then we can call remove on the unique name.

<customer_account_index>
    <remove name="sample" />
</customer_account_index>

You can also call methods on blocks, the best example of this would be to change the template of a block. If we wanted to do this we would need again the layout handle, then the reference with the unique name of the block we want to change and finally the action.

<customer_account_index>
    <reference name="sample">
        <action method="setTemplate"><template>new/template/file.phtml</template></action>
    </reference>
</customer_account_index>

Finally the update tag. This allows you to include the complete layout from another handle. This is useful when you do not want to duplicate your code, perfect example is the customer_account handle which covers the basic information. You can see the following almost all the other layout handles for customer.

<customer_address_form translate="label">
    <update handle="customer_account"/>

All this is saying is please include the layout for the handle "X" in our case customer_account in my layout.