The directive <update> in the Magento Layout

The update tag is used to combine a particular layout handle into other. Let’s see an example:

<my_custom_handle>
  <reference name="content">
    <block type="core/template" name="myblock" template="myblock.phtml" />
  </reference>
</my_custom_handle>
<other_hanlde>
  <update handle="my_custom_handle" />
  <reference name="content">
    <block type="core/template" name="otherblock" template="otherblock.phtml" />
  </reference>
</other_handle>

The previous fragment would be in fact, as if we would put all togheter:

<other_hanlde>
  <reference name="content">
    <block type="core/template" name="myblock" template="myblock.phtml" />
    <block type="core/template" name="otherblock" template="otherblock.phtml" />
  </reference>
</other_handle>

So, why to make it so complex. Well, this is only an example, but it’s a way of make layout files modular. You can define a piece of layout in a custom handle, and the re-use it in multiple real Magento handles.

Imagine, for example, that you need to add some links in the user account menu. You should add it to a number of page handles or you can do than the previous way.

The directive <block> in the Magento Layout

The tag block is probably the best known and most used tag in the layout files. It allows to create new blocks and nest them to create the full page contents for a particular handle.

Parameters of the block tag depends on the type of block, but the main ones are the following:

type="core/template"

type defines the kind of block we are creating. It takes a proper value to be used by the factory Magento methods, so, the previous block corresponds to Core module and Template block. Or in other words, we are creating a block of class Mage_Core_Block_Template

name="blockname"

In this case, name defines the name of the block. This name must by unique in the page being renderer, so be care, and it’s used to reference this block in the rest of the code. For example, when you want to render this block, you’ll need to call:

  echo $this->getChildHtml("blockname");

as="blockalias"

The parameter as defines an alias for the block name. This must be only unique within the block it belongs to.

You can use the alias to render the block as well as the name, but if you need to reference the block from outside of its parent block, you must used the full name instead.

An alias is also useful to change a block type or parameters without the need of altering the template files. For example:

<block type="catalog/product_view" name="product.info.addtocart" as="addtocart" template="catalog/product/view/addtocart.phtml"/>
. . .
<remove name="product.info.addtocart">
<block type="catalog/other_type" name="product.info.addtocart.alternative" as="addtocart" template="catalog/product/view/addtocartalternative.phtml"/>

template="templatefile.phtml"

This is not valid parameter for all kind of blocks, but it is used for the most common block type, Mage_Core_Block_Template, so its worth to explain.

Template parameter defines the template file to be used during the rendering phase of the page generation. So for this particular block, templatefile.phtml in the current theme will be used.

The directive <action> in the Magento Layout

This directive is always present inside a block directive, and it allows to call methods defined in the block being created to set data or parameters to be used later during the page creation.

For example you can set any variable by doing some like this:

<block type="checkout/links" name="checkout_cart_link">
  <action method="setData"><name>myvariable</name><value>myvalue</value></action>
</block>

This will set a data myvariable with value myvalue, as it we would call in code:

  $block->setMyvariable('myvalue');

Also you can call whatever method defined as not private in your block, not only those magic methods to set data. For example:

<block type="checkout/links" name="checkout_cart_link">
  <action method="whateverMethod"><firstparam>somevalue</firstparam><secondparam>somevalue</secondparam></action>
</block>

As you may guessed, the values inside the action directive are the parameters to be passed to the method. As a convention, firstparam and secondparam should be replaced by the actual parameter names. This names are not really used, but it improves readability.

The directive <remove> in the Magento Layout

This directive, as its name means, removes a block from the layout. This block will be marked as ignored and it won’t be created nor output, even if there is a explicit call to getChildHtml() in some template file.

The directive <reference> in the Magento Layout

This directive is used to reference a previously created block and then doing some of the previous actions: call an action, add a child block, and so on. For example:

<reference name="my_previously_defined_block">
  <action method="whateverMethod"><firstparam>somevalue</firstparam><secondparam>somevalue</secondparam></action>
</reference>