Magento – Action elements and helpers in layout

This is relevant for Magento 1.4.1.1.

I have been unable to find any decent documentation on how Magento handles the <action method=”…”> element and helpers within the arguments. After some debugging I found the method responsible for handling these elements. Take a look at app/code/core/Mage/Core/Model/Layout.php on line 289 at the _generateAction method. This method takes the <action> element as $node. It loops through all the child nodes (what would be the method arguments) and turns them into an associative array. If any child node has the “helper” attribute specified it will use that helper to get the value. You can pass arguments to the helper method with further child nodes. This is better illustrated through an example:

<reference name="breadcrumbs">
    <action method="addLink">
        <label>New Link</label>
        <url helper="core/url/getUrl"><page>new-page</page></url>
    </action>
</reference>

This has the effect of making the following calls:

Mage_Page_Block_Html_Breadcrumbs::addLink(
    'Add Link',
    Mage_Core_Helper_Url::getUrl('new-page')
);

The above is merely an example the addLink and getUrl methods do not exist. As far as I’ve found there’s no way to get a generic URL through any helper. In addition the element names for the arguments are only by convention. They are passed in order and the names do not matter.

So in summary:

  • The <action> element calls the “method” attribute on the parent block’s class. Mage_Page_Block_Html_Breadcrumbs::addLink.
  • The child elements are passed as arguments in order. <label> and <url>.
  • Any child elements specifying the “helper” attribute will use that class and method to determine their value. Mage_Core_Helper_Url::getUrl.
  • Any child elements of an element specifying the “helper”attribute will be passed as arguments to the helper method. <page>.

Unfortunately you cannot use helper methods any further down the chain. For example a call to the addCrumb method might look like this:

<reference name="breadcrumbs">
    <action method="addCrumb">
        <crumbName>newlink</crumbName>
        <crumbInfo>
            <label>New Link</label>
            <link>new-link</link>
        </crumbInfo>
    </action>
</reference>

The crumbInfo argument is an associative array. While Magento will construct the array correctly you cannot use a helper on the <link> element where it would be quite useful.

4 Comments

  1. Aaron

    Thanks for this. The lack of documentation on the action tag, and a fair few other areas, is shocking.

  2. Taras

    Hi, nice post, but I’m stuck with such an issue: I need to pass through an associative array with numbers: array(2=>2,5=>5,10=>10). The problem is that I can’t make tags from numbers, how they be passed in other way?
    Thanks!

  3. You could append a string to the front of each index:
    array('t_2'=>2,'t_5'=>5,'t_10'=>10)
    Then strip that out later on if you need to.

Leave a Reply

Your email address will not be published. Required fields are marked *