Magento Layout XML Action Method Reference List

Magento’s layout and template system is where the framework truly shines and demonstrates the true beauty of its modular nature. One of the most powerful pieces of functionality with layout files is the action handle. I’ll give you a brief overview of how action handlers work and provide you with a reference list of action methods that come pre-packed with Magento’s core.

What does the Magento action layout handle do?

The action handle is used to control client-facing functionality. An action handle must be a child of a or handle. Presence of an action handle in your layout tells Magento that you want to call a block function referenced in the action’s method property.

How does Magento know which block your action method is in?

Magento will look at the type of the parent or referenced block, and will attempt to call the action method in there.

Related: [Mini Tutorial] Adding Custom Links with local.xml

How do you pass parameters into a Magento action method?

If the block function you are reference takes parameters, you can specify child nodes in your action. The names of the nodes is not important, but should be named something meaningful. The value inside these nodes is what is important, as they are the values that Magento will pass into the function that it calls.

Can I call my own block functions using the layout.xml action handle?

Yes. All the action parameter does is look at the parent block or reference and try to call the function you specify inside the method="" property. If the action handle has child nodes, their values will be passed to the function as parameters.

Example of Magento Layout XML Action Method Usage

To better grasp the concepts that I am talking, let us consider the following example of some XML that could be placed in your themes local.xml:

<!-- Found in: /app/design/frontend/base/default/layout/page.xml -->
<block type="page/html_head" name="head" as="head">...</block>
<catalog_product_view>
     <reference name=”head”>
         <action method=”addJs”>
              <script>customScript.js</script>
         </action>
     </reference>
</catalog_product_view>

I mentioned that Action methods must be a child of or nodes. Note that in this example, I am referencing a block with an alias of head.

If you look at the declaration for the head block, you will notice that its type is “page/html_head”. This is the block that Magento will try to call your action method in. To take this a little further, Magento will look for the following block:

[local|community|core]/Mage/Page/Block/Html/Head.php

The action method we have described is addJs. You may have noticed that the action handle also has a child handle. This means that when Magento tries to call addJs(), it will pass in the child of the action a parameter.

Ultimately magento will call addJs(‘customScript.js’);

Related: [Mini Tutorial] Changing the order of layout XML blocks in local.xml

Action Method Reference List

Mage_Core_Block_Abstract

Mage_Core_Block_Template

Mage_Page_Block_Html

Mage_Page_Block_Html_Head

Mage_Catalog_Block_Product_View_Options

Mage_Catalog_Block_Seo_Sitemap_Abstract

Mage_Page_Block_Template_Links

Mage_CatalogSearch_Block_Result

Mage_Catalog_Block_Product_List_Upsell

Below is a list of these methods with a bit more details.

Mage_Core_Block_Abstract

unsetChild

Unset child block.

Parameter Name Default Value Description
Alias N/A Alias of the child block that is to be unset.

unsetChildren

Unset all children blocks.

append

Append child block.

This function calls insert($block, ‘’, true, $alias)

Parameter Name Default Value Description
Block N/A Name of the block that is too be inserted.
Alias (optional) ‘’ Alias that is to be given to the block

Insert

Insert child block.

Parameter Name Default Value Description
Block N/A Name of the block that is too be inserted.
Sibling Name (optional) ‘’ Inserts block before or after this child (if found). Before or after is dependent on the value of <after /> parameter
After (optional) False If a sibling name is set, this controls whether the block is inserted before or after the sibling.

If no sibling is set, this controls whether the block is added to the very start or very end of the list of children.

Alias (optional) ‘’ Sets an alias for the block

addToParentGroup

Add self to the specified group of parent block.

Parameter Name Default Value Description
Group Name N/A

Mage_Core_Block_Template

setTemplate

Set path to template used for generating block’s output.

Parameter Name Default Value Description
Template N/A Path to the template file.

Mage_Page_Block_Html

setHeaderTitle

Parameter Name Default Value Description
Title N/A Sets the title of the page.

Mage_Page_Block_Html_Head

addCss

Add CSS file to HEAD entity.

This function calls addItem(‘skin_css’, $name, $params)

Parameter Name Default Value Description
Name N/A Location of the CSS file to be added within the skin directory.
Params (optional) ‘’

addJs

Add Javascript file to HEAD entity.

This function calls addItem(‘js’, $name, $params)

Parameter Name Default Value Description
Name N/A Location of the javascript file to be added within the js directory.
Params (optional) ‘’

addCSSIe

Add CSS file for Internet Explorer only to HEAD entity.

This function calls addItem(‘skin_css’, $name, $params, ‘IE’)

Parameter Name Default Value Description
Name N/A Location of the CSS file to be added within the skin directory.
Params (optional) ‘’

addJsIe

Add JavaScript file for Internet Explorer only to HEAD entity.

This function calls addItem(‘js’, $name, $params, ‘IE’)

Parameter Name Default Value Description
Name N/A Location of the javascript file to be added within the js directory.
Params (optional) ‘’

Add Link element to HEAD entity.

This function calls addItem(‘link_rel’, $href, ‘rel=”‘ . $rel . ‘”‘)

Parameter Name Default Value Description
Rel N/A
Href N/A

addItem

Add HEAD Item.

Parameter Name Default Value Description
Type N/A Allowed types: js, js_css, skin_js, skin_css, rss
Name N/A
Params (optional) null
If (optional) null If set, this is will be used to wrap around your file. Good for including files for certain browsers only.

Example: lt IE 7

Cond (optional) null

removeItem

Remove Item from HEAD entity.

Parameter Name Default Value Description
Type N/A Allowed types: js, js_css, skin_js, skin_css, rss
Name N/A

setTitle

Set title element text.

Parameter Name Default Value Description
Title N/A

Mage_Catalog_Block_Product_View_Options

addOptionRenderer

Add option renderer to renderers array.

Parameter Name Default Value Description
Type N/A Type of option being added.

Example Types: text, file, select

Block N/A
Template N/A

Mage_Catalog_Block_Seo_Sitemap_Abstract

bindPager

Init pager.

Parameter Name Default Value Description
Pager Name N/A

Mage_Page_Block_Template_Links

Add link to the list.

Parameter Name Default Value Description
Label N/A
Url (optional) ‘’
Title (optional) ‘’
Prepare (optional) False
urlParams (optional) Array()
Position (optional) Null
liParams (optional) Null
aParams (optional) Null
beforeText (optional) ‘’
afterText (optional) ‘’

Mage_CatalogSearch_Block_Result

setListOrders

Set search available list orders.

setListModes

Set available view mode.

setListCollection

Set Search Result collection.

Mage_Catalog_Block_Product_List_Upsell

setColumnCount

Parameter Name Default Value Description
Columns N/A

setItemLimit

Set how many items we need to show in upsell block

Notice: this parameter will be also applied

Parameter Name Default Value Description
Type N/A
Limit N/A

Related: Code Quality in the Magento Ecosystem