Magento Layout Files Reference

This reference documents Magento’s layout files, i.e. the XML files in a app/design/frontend/<your interface>/<your theme>/layout folder. There’s a complete list of layout handles, e.g. default, for every layout file, e.g. page.xml. More importantly, this reference covers all of the XML elements, including their attributes and common values. If possible, examples are given for each element or attribute to further clarify their usage.

Please Note: This is a work in progress and is currently missing descriptions for the XML elements and attributes.

Layout handles for each layout file

bundle.xml

default

catalog_category_default

catalog_category_view

catalog_category_layered

catalog_product_compare_index

catalogsearch_result_index

catalogsearch_advanced_result

tag_product_list

wishlist_index_index

wishlist_shared_index

catalog_product_view

PRODUCT_TYPE_simple

customer_account

checkout_cart_index

checkout_onepage_review

checkout_multishipping_addresses

checkout_multishipping_shipping

checkout_multishipping_overview

PRODUCT_TYPE_bundle

sales_order_view

sales_order_invoice

sales_order_shipment

sales_order_creditmemo

sales_order_print

sales_order_printinvoice

sales_order_printshipment

sales_order_printcreditmemo

sales_email_order_items

sales_email_order_invoice_items

sales_email_order_shipment_items

sales_email_order_creditmemo_items

catalog.xml

default

catalog_category_default

catalog_category_layered

catalog_category_layered_nochildren

catalog_product_compare_index

customer_account_index

catalog_product_view

PRODUCT_TYPE_simple

PRODUCT_TYPE_configurable

PRODUCT_TYPE_grouped

PRODUCT_TYPE_virtual

catalog_product_send

catalog_product_gallery

catalog_seo_sitemap

catalog_seo_sitemap_category

catalog_seo_sitemap_product

catalog_seo_searchterm_popular

catalogsearch.xml

default

catalogsearch_result_index

catalogsearch_advanced_index

catalogsearch_advanced_result

catalogsearch_term_popular

checkout.xml

default

checkout_cart_index

checkout_multishipping

checkout_multishipping_login

checkout_multishipping_address_select

checkout_multishipping_address_selectbilling

checkout_multishipping_address_newshipping

checkout_multishipping_address_newbilling

checkout_multishipping_address_editshipping

checkout_multishipping_address_editaddress

checkout_multishipping_address_editbilling

checkout_multishipping_customer_address

checkout_multishipping_addresses

checkout_multishipping_shipping

checkout_multishipping_billing

checkout_multishipping_overview

checkout_multishipping_success

checkout_onepage_index

checkout_onepage_progress

checkout_onepage_paymentmethod

checkout_onepage_shippingmethod

checkout_onepage_additional

checkout_onepage_review

checkout_onepage_success

checkout_onepage_failure

cms.xml

default

cms_page

cms_index_defaultindex

cms_index_defaultnoroute

contacts.xml

default

contacts_index_index

core.xml

default

customer.xml

default

customer_logged_in

customer_logged_out

customer_account_login

customer_account_logoutsuccess

customer_account_create

customer_account_forgotpassword

customer_account_confirmation

customer_account_edit

customer_account

customer_account_index

customer_address_index

customer_address_form

directory.xml

catalog_category_default

catalog_category_layered

catalogsearch_advanced_index

catalogsearch_result_index

catalogsearch_advanced_result

downloadable.xml

customer_account

downloadable_customer_products

checkout_cart_index

checkout_onepage_review

checkout_onepage_success

checkout_multishipping_addresses

checkout_multishipping_shipping

checkout_multishipping_overview

checkout_multishipping_success

sales_order_view

sales_order_invoice

sales_order_creditmemo

sales_order_print

sales_order_printinvoice

sales_order_printcreditmemo

sales_email_order_items

sales_email_order_invoice_items

sales_email_order_creditmemo_items

PRODUCT_TYPE_downloadable

giftmessage.xml

giftmessage_index_edit

giftmessage_index_save

giftmessage_index_remove

googleanalytics.xml

default

googlecheckout.xml

checkout_cart_index

googlecheckout_redirect_redirect

googleoptimizer.xml

catalog_product_view

catalog_category_default

catalog_category_layered

cms_page

checkout_cart_index

checkout_onepage_index

checkout_onepage_success

checkout_multishipping_success

checkout_multishipping

customer_account_create

newsletter.xml

default

customer_account

customer_account_index

newsletter_manage_index

page.xml

default

print

paypal.xml

checkout_cart_index

paypal_express_review

paypal_express_review_details

paypaluk.xml

checkout_cart_index

paypaluk_express_review

paypaluk_express_review_details

poll.xml

default

customer_account_index

productalert.xml

catalog_product_view

reports.xml

default

review.xml

customer_account

customer_account_index

reviews

review_product_list

review_product_view

review_customer_index

review_customer_view

rss.xml

default

rss_index_index

rss_index_nofeed

rss_index_wishlist

rss_catalog_new

rss_catalog_special

rss_catalog_salesrule

rss_catalog_tag

rss_catalog_notifystock

rss_catalog_review

rss_catalog_category

rss_order_new

rss_order_status

sales.xml

customer_logged_in

checkout_onepage_index

checkout_onepage_reorder

customer_account

customer_account_index

sales_order_history

sales_order_view

sales_order_invoice

sales_order_shipment

sales_order_creditmemo

sales_order_reorder

sales_order_print

sales_order_printinvoice

sales_order_printshipment

sales_order_printcreditmemo

sales_email_order_items

sales_email_order_invoice_items

sales_email_order_shipment_items

sales_email_order_creditmemo_items

sendfriend.xml

sendfriend_product_send

shipping.xml

shipping_tracking_ajax

shipping_tracking_popup

tag.xml

default

customer_account

customer_account_index

catalog_product_view

tag_list_index

tag_product_list

tag_customer_index

tag_customer_view

tag_customer_edit

weee.xml

checkout_cart_index

checkout_onepage_index

checkout_multishipping

customer_logged_in

wishlist.xml

default

customer_account

customer_account_index

wishlist_index_index

wishlist_index_share

wishlist_shared_index

General XML elements and attributes

reference

Attributes

name

Example

<reference name=”cart_sidebar”> <action method=”addItemRender”> <type>bundle</type> <block>bundle/checkout_cart_item_renderer</block> <template>checkout/cart/sidebar/default.phtml</template> </action> </reference>

action

Attributes

method

addPriceBlockType: <action method="addPriceBlockType"><type>bundle</type><block>bundle/catalog_product_price</block><template>bundle/catalog/product/price.phtml</template></action>

addItemRender: <action method="addItemRender"><type>bundle</type><block>bundle/checkout_cart_item_renderer</block><template>checkout/cart/sidebar/default.phtml</template></action>

addItem: <action method="addItem"><type>skin_js</type><name>js/bundle.js</name></action>

insert: <action method=”insert”><block>product.info.bundle.options</block></action>

setItemLimit: <action method="setItemLimit"><type>bundle</type><limit>4</limit></action>

setImgSrc: <action method=”setImgSrc”><src>images/media/col_left_callout.jpg</src></action>

setImgAlt: <action method=”setImgAlt” translate=”alt” module=”catalog”><alt>Our customer service is available 24/7. Call us at (800) DEMO-NUMBER.</alt></action>

setLinkUrl: <action method=”setLinkUrl”><url>checkout/cart</url></action>

addLink: <action method=”addLink” translate=”label title” module=”catalog” ifconfig=”catalog/seo/site_map”><label>Site Map</label><url helper=”catalog/map/getCategoryUrl” /><title>Site Map</title></action>

setDefaultListPerPage: <action method=”setDefaultListPerPage”><limit>4</limit></action>

setDefaultGridPerPage: <action method=”setDefaultGridPerPage”><limit>9</limit></action>

addPagerLimit: <action method=”addPagerLimit”><mode>list</mode><limit>6</limit></action>

setToolbarBlockName: <action method=”setToolbarBlockName”><name>product_list_toolbar</name></action>

addReviewSummaryTemplate: <action method=”addReviewSummaryTemplate”><type>default</type><template>review/helper/su.phtml</template></action>

setTemplate: <action method=”setTemplate”><template>page/one-column.phtml</template></action>

addJs: <action method=”addJs”><script>scriptaculous/scriptaculous.js</script></action>

unsetChild: <action method=”unsetChild”><name>catalog_compare_sidebar</name></action>

setTierPriceTemplate: <action method=”setTierPriceTemplate”><template>catalog/product/view/tierprices.phtml</template></action>

setColumnCount: <action method=”setColumnCount”><columns>4</columns></action>

setItemLimit: <action method=”setItemLimit”><type>upsell</type><limit>4</limit></action>

addOptionRenderer: <action method=”addOptionRenderer”><type>text</type><block>catalog/product_view_options_type_text</block><template>catalog/product/view/options/type/text.phtml</template></action>

insert: <action method=”insert”><block>product.tierprices</block></action>

append: <action method=”append”><block>product.info.addtocart</block></action>

setDataByKey: <action method=”setDataByKey”><key>alias_in_layout</key><value>container2</value></action>

setDataByKeyFromRegistry: <action method=”setDataByKeyFromRegistry”><key>options_container</key><key_in_registry>product</key_in_registry></action>

unsetCallChild: <action method=”unsetCallChild”><child>container1</child><call>ifEquals</call><if>0</if><key>alias_in_layout</key><key>options_container</key></action>

setTitle: <action method=”setTitle” translate=”title” module=”catalog”><title>Categories</title></action>

bindPager: <action method=”bindPager”><pager>seo.sitemap.pager.top</pager></action>

setItemsTitle: <action method=”setItemsTitle” translate=”title” module=”catalog”><title>categories</title></action>

setListOrders: <action method=”setListOrders”/>

setListModes: <action method=”setListModes”/>

setListCollection: <action method=”setListCollection”/>

addCartLink: <action method=”addCartLink”></action>

addCheckoutLink: <action method=”addCheckoutLink”></action>

setCartTemplate: <action method=”setCartTemplate”><value>checkout/cart.phtml</value></action>

setEmptyTemplate: <action method=”setEmptyTemplate”><value>checkout/cart/noItems.phtml</value></action>

chooseTemplate: <action method=”chooseTemplate”/>

setMethodFormTemplate: <action method=”setMethodFormTemplate”><method>purchaseorder</method><template>payment/form/purchaseorder.phtml</template></action>

setInfoTemplate: <action method=”setInfoTemplate”><method></method><template></template></action>

setDontDisplayContainer: <action method=”setDontDisplayContainer”><param>1</param></action>

setBlockId: <action method=”setBlockId”><block_id>footer_links</block_id></action>

setHeaderTitle: <action method=”setHeaderTitle” translate=”title” module=”contacts”><title>Contact Us</title></action>

setSaveMode: <action method=”setSaveMode”><mode>save</mode></action>

setGoogleCheckout: <action method=”setGoogleCheckout”><flag>true</flag></action>

setScriptType: <action method=”setScriptType”><scriptType>control_script</scriptType></action>

addCss: <action method=”addCss”><stylesheet>css/reset.css</stylesheet></action>

setPollTemplate: <action method=”setPollTemplate”><template>poll/active.phtml</template><type>poll</type></action>

addWishlistLink: <action method=”addWishlistLink”></action>

translate

alt: <action method=”setImgAlt” translate=”alt” module=”catalog”><alt>Our customer service is available 24/7. Call us at (800) DEMO-NUMBER.</alt></action>

label: <action method=”addPagerLimit” translate=”label”><mode>list</mode><limit>all</limit><label>All</label></action>

module

catalog: <action method=”setImgAlt” translate=”alt” module=”catalog”><alt>Our customer service is available 24/7. Call us at (800) DEMO-NUMBER.</alt></action>

ifconfig

<path>: <action method=”setImgAlt” translate=”alt” module=”catalog”><alt>Our customer service is available 24/7. Call us at (800) DEMO-NUMBER.</alt></action>

Examples

<action method=”addItemRender”> <type>bundle</type> <block>bundle/sales_order_items_renderer</block> <template>bundle/sales/order/items/renderer.phtml</template> </action>

type

Attributes

Examples

<default> <reference name="wishlist_sidebar"> <action method="addPriceBlockType"> <type>bundle</type> <block>bundle/catalog_product_price</block> <template>bundle/catalog/product/price.phtml</template> </action> </reference> </default>

name

Attributes

Examples

<PRODUCT_TYPE_bundle> <reference name="head"> <action method="addItem"> <type>skin_js</type> <name>js/bundle.js</name> </action> </reference> </PRODUCT_TYPE_bundle>

src

Attributes

Examples

<block type="core/template" name="left.permanent.callout" template="callouts/left_col.phtml"> <action method="setImgSrc"><src>images/media/col_left_callout.jpg</src></action> <action method=”setImgAlt” translate=”alt” module=”catalog”><alt>Our customer service is available 24/7. Call us at (800) DEMO-NUMBER.</alt></action> <action method=”setLinkUrl”><url>checkout/cart</url></action> </block>

alt

Attributes

Examples

<block type=”core/template” name=”left.permanent.callout” template=”callouts/left_col.phtml”>
<action method=”setImgSrc”><src>images/media/col_left_callout.jpg</src></action>
<action method=”setImgAlt” translate=”alt” module=”catalog”><alt>Our customer service is available 24/7. Call us at (800) DEMO-NUMBER.</alt></action>
<action method=”setLinkUrl”><url>checkout/cart</url></action>
</block>

url

Attributes

helper

<action method=”addLink” translate=”label title” module=”catalog”><label>Products Sitemap</label><url helper=”catalog/map/getProductUrl”/><title>Products Sitemap</title></action>

Examples

label

Attributes

Examples

mode

Attributes

Examples

limit

Attributes

Examples

title

Attributes

Examples

script

Attributes

Examples

<reference name=”head”>
<action method=”addJs”><script>scriptaculous/scriptaculous.js</script></action>
<action method=”addJs”><script>varien/product.js</script></action>
</reference>

params

Attributes

Examples

if

Attributes

Examples

<action method=”unsetCallChild”>
<child>container1</child>
<call>ifEquals</call>
<if>0</if>
<key>alias_in_layout</key>
<key>options_container</key>
</action>

<action method=”addItem”>
<type>js</type>
<name>lib/ds-sleight.js</name>
<params/>
<if>lt IE 7</if>
</action>

condition

Attributes

Examples

<condition>can_load_calendar_js</condition>

columns

Attributes

Examples

key

Attributes

Examples

<action method=”setDataByKey”>
<key>alias_in_layout</key>
<value>container2</value>
</action>

value

Attributes

Examples

<action method=”setDataByKey”>
<key>alias_in_layout</key>
<value>container2</value>
</action>

key_in_registry

Attributes

Examples

<action method=”setDataByKeyFromRegistry”>
<key>options_container</key>
<key_in_registry>product</key_in_registry>
</action>

child

Attributes

Examples

<action method=”unsetCallChild”>
<child>container1</child>
<call>ifEquals</call>
<if>0</if>
<key>alias_in_layout</key>
<key>options_container</key>
</action>

call

Attributes

Examples

<action method=”unsetCallChild”>
<child>container1</child>
<call>ifEquals</call>
<if>0</if>
<key>alias_in_layout</key>
<key>options_container</key>
</action>

pager

Attributes

Examples

<action method=”bindPager”>
<pager>seo.sitemap.pager.top</pager>
</action>

remove

Attributes

name

Examples

update

Attributes

handle

Examples

method

Attributes

Examples

<action method=”setMethodFormTemplate”><method>purchaseorder</method><template>payment/form/purchaseorder.phtml</template></action>

template

Attributes

Examples

<action method=”setMethodFormTemplate”><method>purchaseorder</method><template>payment/form/purchaseorder.phtml</template></action>

block_id

Attributes

Examples

<action method=”setBlockId”><block_id>footer_links</block_id></action>

prepare

Attributes

Examples

<action method=”addLink” translate=”label title” module=”contacts” ifconfig=”contacts/contacts/enabled”>
<label>Contact Us</label>
<url>contacts</url>
<title>Contact Us</title>
<prepare>true</prepare>
</action>

urlParams

Attributes

Examples

<action method=”addLink” translate=”label title” module=”customer”>
<label>My Account</label>
<url helper=”customer/getAccountUrl”/>
<title>My Account</title>
<prepare/>
<urlParams/>
<position>10</position>
</action>

position

Attributes

Examples

name

Attributes

Examples

<action method=”unsetChild”>
<name>left.permanent.callout</name>
</action>

mode

Values

remove | save

Attributes

Examples

flag

Values

true | false

Attributes

Examples

scriptType

Values

control_script | tracking_script | conversion_script

Attributes

Examples

<action method=”setScriptType”>
<scriptType>tracking_script</scriptType>
</action>

pageType

Values

Attributes

Examples

<action method=”setPageType”>
<pageType>checkout_onepage</pageType>
</action>

stylesheet

Values

Attributes

Examples

<action method=”addCss”>
<stylesheet>css/print.css</stylesheet>
<params>media=”print”</params>
</action>

block

Attributes

type

This is the identifier of the module class that defines the functionality of the block. This attribute must not be modified.

Values: -

Example: <block type=”checkout/links” name=”checkout_cart_link”>
<action method=”addCartLink”></action>
<action method=”addCheckoutLink”></action>
</block>

name

This is the name by which other blocks can make reference to the block in which this attribute is assigned (see diagram 3).

Values: -

Example: <block type=”checkout/links” name=”checkout_cart_link”>
<action method=”addCartLink”></action>
<action method=”addCheckoutLink”></action>
</block>

before (and) after

These are two ways to position a content block within a structural block. before=”-” and after=”-” are commands used to position the block accordingly at the very top or very bottom of a structural block.

Values: -

Example: <block type=”checkout/onepage_progress” name=”checkout.progress” before=”-” template=”checkout/onepage/progress.phtml”/>

template

This attribute determines the template that will represent the functionality of the block in which this attribute is assigned. For instance, if this attributes is assigned ‘catalog/category/view.phtml’, the application will load the ‘app/design/frontend/template/catalog/category/view.phtml template file.In order to learn about how layout works with templates to bring markup to your store, read Step by Step Guide to Building a Theme.

Values: -

Example: <block type=”checkout/multishipping_address_select” name=”checkout_address_select” template=”checkout/multishipping/address/select.phtml”/>

action

<action> is used to control store-front functionalities such as loading or unloading of a Javascript. A full list of action methods will soon become available, but in the mean time the best way to learn about the different action methods is by playing around with them in the currently available layout updates.

Values: -

Example:

as

This is the name by which a template calls the block in which this attribute is assigned. When you see the getChildHtml(’block_name’) PHP method called from a template, you can be sure it is referring to the block whose attribute ‘as’ is assigned the name ‘block_name’. (ie. The method <?=$this->getChildHtml(’header’)?> in the a skeleton template correlates to <block as=“header”>).

Values: -

Example: <block type=”core/text_list” name=”checkout.cart.top_methods” as=”top_methods”>
<block type=”checkout/onepage_link” name=”checkout.cart.methods.onepage” template=”checkout/onepage/link.phtml”/>
</block>

output

Values: toHtml

Example: <block type=”checkout/onepage_progress” name=”root” output=”toHtml” template=”checkout/onepage/progress.phtml”>
<block type=”checkout/onepage_payment_info” name=”payment_info”>
<action method=”setInfoTemplate”>
<method></method>
<template></template>
</action>
</block>
</block>

Examples

<reference name="product.info"> <block type=”bundle/catalog_product_view_type_bundle” name=”product.info.bundle” as=”product_type_data” template=”bundle/catalog/product/view/type/bundle.phtml”> <action method=”addPriceBlockType”> <type>bundle</type> <block>bundle/catalog_product_price</block> <template>bundle/catalog/product/price.phtml</template> </action> <block type=”bundle/catalog_product_price” name=”bundle.prices” as=”bundle_prices” template=”bundle/catalog/product/view/price.phtml” /> </block> </reference>

template

<sales_email_order_items> <reference name="items"> <action method="addItemRender"> <type>bundle</type> <block>bundle/sales_order_items_renderer</block> <template>bundle/email/order/items/order/default.phtml</template> </action> </reference> </sales_email_order_items>