Magento Layout Files Reference

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

<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>

label Attributes

Examples

<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>

mode Attributes

Examples

<action method="addPagerLimit">
<mode>list</mode>
<limit>2</limit>
</action>

limit Attributes

Examples

<action method="addPagerLimit">
<mode>list</mode>
<limit>2</limit>
</action>

title Attributes

Examples

<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>

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

<action method="setColumnCount">
<columns>4</columns>
</action>

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

<remove name="right.newsletter" />

Examples

update Attributes

handle

<update handle="checkout_multishipping"/>

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

<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>

name Attributes

Examples

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

mode Values

remove | save Attributes

Examples

<action method="setSaveMode">
<mode>save</mode>
</action>

flag Values true | false

Attributes
Examples

<reference name="google_analytics">
<action method="setGoogleCheckout"><flag>true</flag></action>
</reference>

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"/>
<block type="catalog/navigation" name="catalog.leftnav" after="currency" template="catalog/navigation/left.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

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

<?php echo $this->getChildHtml('header')?>

in the a skeleton template correlates to ).

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>

Refer: http://magsvento.se/magento-references/magento-layout-files-reference

Customize your Magento with local.xml

./app/design/frontend/default/default/layout/local.xml

<?xml version="1.0"?>
<layout version="0.1.0">
 
<default>
 
	<reference name="head">
		<!-- Magento looks in /skin/frontend/<INTERFACE>/<THEME>/js/buyprinting.js
		for this file -->
		<action method="addItem"><type>skin_js</type><name>js/buyprinting.js</name></action>
 
		<!-- This removes the item that was set in the page.xml file -->
		<action method="removeItem"><type>skin_js</type><name>js/iehover-fix.js</name></action>
 
		<!-- Magento looks in /js/prototype/element.storage.js for this file -->
		<action method="addJs"><name>prototype/element.storage.js</name></action>
 
		<action method="addCss">
<stylesheet>css/buyprinting.css</stylesheet></action>
	</reference>
 
	<reference name="header">
		<!-- This adds a CMS block that can be called from the template file
		associated with the header block. -->
		<block type="cms/block" name="cms_quick_help">
			<action method="setBlockId"><block_id>quick_help</block_id></action>
		</block>
 
		<!-- The remove tag removes the blocks with the specified name from the layout -->
		<remove name="top.menu"/>
		<remove name="store_language"/>
		<remove name="breadcrumbs"/>
	</reference>
 
	<reference name="top.nav">
		<remove name="catalog.topnav"/>
	</reference>
 
	<reference name="left">
		<remove name="left.newsletter"/>
		<remove name="left.permanent.callout"/>
		<remove name="catalogsearch.leftnav"/>
 
		<!-- When you use the remove tag, it removes any blocks with the specified name from
			the entire layout, regardless of the context. So, if I remove right.newsletter in
			the <default> context and that name is used in say the <catalog_product_view> context,
			then both blocks will be removed.  Because remove operates on the global context,
			you can only remove an element once.  Since <remove name="right.newsletter" /> is
			being called in catalogsearch.xml, we have to unset it, or else we'll get an error.
 
			The line below only unsets the block from the parent's context, not the global
			layout context -->
		<action method="unsetChild"><name>right.newsletter</name></action>
	</reference>
 
	<reference name="right">
		<!-- Some blocks have to be removed using remove, others via unsetChild.
			I've not spent the time digging into the code to figure out why -->
		<remove name="right.permanent.callout"/>
		<remove name="catalog.compare.sidebar"/>
		<remove name="left.reports.product.viewed"/>
		<action method="unsetChild"><name>sale.reorder.sidebar</name></action>
		<action method="unsetChild"><name>wishlist_sidebar</name></action>
		<action method="unsetChild"><name>right.reports.product.viewed</name></action>
		<remove name="cart_sidebar"/>
	</reference>
 
</default>
 
<!-- CATALOG PAGES -->
	<catalog_product_view><!-- 2columns-right -->
		<reference name="root">
			<action method="setTemplate"><template>page/2columns-left.phtml</template></action>
		</reference>
		<reference name="content">
			<reference name="product.info">
				<block type="cms/block" name="cms_product_info_tabs">
					<action method="setBlockId"><block_id>product_info_tabs</block_id></action>
				</block>
				<block type="catalog/product_view" name="product.clone_prices" as="prices" template="catalog/product/view/price_clone.phtml"/>
				<action method="unsetChild"><name>tierprices</name></action>
				<action method="unsetChild"><name>addto</name></action>
				<remove name="addto"/>
				<reference name="product.info.options.wrapper.bottom">
					<action method="unsetChild"><name>product.tierprices</name></action>
				</reference>
			</reference>
		</reference>
	</catalog_product_view>
 
</layout>

# Links
http://classyllama.com/development/magento-development/the-better-way-to-modify-magento-layout/

The Better Way to Modify Magento Layouts

Author: ehansen

In this article, I’m going to be covering what I believe to be a very effective way of modifying the layout of any Magento theme.

For several of the first Magento themes I built, I copied the layout files from the default or blank theme into the custom theme layout folder. I would then modify the layout files directly, editing or commenting out content in files like: catalog.xml, page.xml, checkout.xml, etc… I never liked editing these files directly, as I knew that when it came time to upgrade to a newer version of Magento that had upgraded the layout files, I’d have to merge the changes into the new layout files.

One day, I was digging through the Magento code relating to layout files and discovered a bit of code that made me realize that it was possible to just place a local.xml file in my custom theme’s layout folder and have it loaded automatically by Magento. (this code is on line 283 in /app/code/core/Mage/Core/Model/Layout/Update.php in the fetchFileLayoutUpdates() method).

Due to Magento’s brilliant tags, it’s possible to do just about anything you want without having to edit any of the default layout files.

Before delving into the code, let’s look at the advantages/disadvantages of this method:

Advantages

  • Allows you to upgrade themes without having to merge in changes
  • All custom layout changes are centralized, allowing developers to more easily make changes to custom theme elements

Disadvantages

  • At first, it’s slower to use this method than hacking up the standard layout files directly
  • You will have one more place to look where the site might be pulling code (template phtmls, standard layout files, admin layout updates, AND local.xml)

Here is the slimmed down, commented local.xml from one of our recent projects:

<?xml version="1.0"?>
<layout version="0.1.0">

<default>

	<reference name="head">
		<!-- Magento looks in /skin/frontend/<INTERFACE>/<THEME>/js/buyprinting.js
		for this file -->
		<action method="addItem"><type>skin_js</type><name>js/buyprinting.js</name></action>

		<!-- This removes the item that was set in the page.xml file -->
		<action method="removeItem"><type>skin_js</type><name>js/iehover-fix.js</name></action>

		<!-- Magento looks in /js/prototype/element.storage.js for this file -->
		<action method="addJs"><name>prototype/element.storage.js</name></action>

		<action method="addCss">
<stylesheet>css/buyprinting.css</stylesheet></action>
	</reference>

	<reference name="header">
        <!-- This adds a CMS block that can be called from the template file
        associated with the header block. -->
		<block type="cms/block" name="cms_quick_help">
			<action method="setBlockId"><block_id>quick_help</block_id></action>
		</block>

        <!-- The remove tag removes the blocks with the specified name from the layout -->
		<remove name="top.menu"/>
		<remove name="store_language"/>
		<remove name="breadcrumbs"/>
	</reference>

	<reference name="top.nav">
		<remove name="catalog.topnav"/>
	</reference>

	<reference name="left">
		<remove name="left.newsletter"/>
		<remove name="left.permanent.callout"/>
		<remove name="catalogsearch.leftnav"/>

        <!-- When you use the remove tag, it removes any blocks with the specified name from
            the entire layout, regardless of the context. So, if I remove right.newsletter in
            the <default> context and that name is used in say the <catalog_product_view> context,
            then both blocks will be removed.  Because remove operates on the global context,
            you can only remove an element once.  Since <remove name="right.newsletter" /> is
            being called in catalogsearch.xml, we have to unset it, or else we'll get an error.

            The line below only unsets the block from the parent's context, not the global
            layout context -->
		<action method="unsetChild"><name>right.newsletter</name></action>
	</reference>

	<reference name="right">
        <!-- Some blocks have to be removed using remove, others via unsetChild.
            I've not spent the time digging into the code to figure out why -->
		<remove name="right.permanent.callout"/>
		<remove name="catalog.compare.sidebar"/>
		<remove name="left.reports.product.viewed"/>
		<action method="unsetChild"><name>sale.reorder.sidebar</name></action>
		<action method="unsetChild"><name>wishlist_sidebar</name></action>
		<action method="unsetChild"><name>right.reports.product.viewed</name></action>
		<remove name="cart_sidebar"/>
	</reference>

</default>

<!-- CATALOG PAGES -->
	<catalog_product_view><!-- 2columns-right -->
		<reference name="root">
			<action method="setTemplate"><template>page/2columns-left.phtml</template></action>
		</reference>
		<reference name="content">
			<reference name="product.info">
				<block type="cms/block" name="cms_product_info_tabs">
					<action method="setBlockId"><block_id>product_info_tabs</block_id></action>
				</block>
				<block type="catalog/product_view" name="product.clone_prices" as="prices" template="catalog/product/view/price_clone.phtml"/>
				<action method="unsetChild"><name>tierprices</name></action>
				<action method="unsetChild"><name>addto</name></action>
				<remove name="addto"/>
				<reference name="product.info.options.wrapper.bottom">
					<action method="unsetChild"><name>product.tierprices</name></action>
				</reference>
			</reference>
		</reference>
	</catalog_product_view>

</layout>

I hope with article has given you some direction as to how you can improve you Magento theming skills. If you have any additional tips/comments on coding layouts, please suggest them in the comments section.

Refer: http://classyllama.com/development/magento-development/the-better-way-to-modify-magento-layout/

5 Useful Tricks For Your Magento local.xml

By Robert Popovic

We have covered a lot about Magento’s layout XML in our past 2 articles [1] [2]. We saw that Magento will read the layout XML files in a specific order and that the local.xml file is read at the very end of the sequence. This allows us to approach the implementation of new theme designs in a very modular and tidy way.

Most of the time, we would use one of the Magento supplied themes as a starting point for a new theme. The base default theme gives us all the standard theme features and implements the complete Magento layout and phtml files but the theme is almost completely unstyled. We can get a kick start from either the Magento default or modern themes,

tidy Magento layout

tidy Magento layout

or if you installed a third party Magento design.

A minimalist layout folder

So we end up with a setup that we can work with but, often, we don’t want to use all the features, rearrange some of the features we want to keep and, most likely, add some of or own.

We know that we can just copy the selected starting design into a new design package and start modifying all the layout XML and phtml files but what if the original theme is updated with the next release or the theme designer (if using a third party theme) releases an update? To reduce the need to retrofit updates, we can plan our theme modifications better by putting all our layout modifications into our own local.xml file. As you can see from the example on the right, our layout folder is really minimalist and tidy. This way almost all of the original layout files are kept intact and, the added bonus is that you can see in one file what you have modified as opposed to hunting for your modifications in numerous layout files.

Working with local.xml is really no different to modifying the existing layout files, once you realize that any Magento layout file can target any layout handle. This means that we are really not going to tell you anything new if you are already familiar with modifying layout XML. Nevertheless, for the novice, these tricks may be useful and we hope that the more advanced will be able to take away some ideas too.

A general local.xml file will have the standard layout root element under which all the other layout handles will be nested:

<?xml version="1.0" encoding="UTF-8"?>
<!--
/**
 * local.xml
 *
 * Local layout modifications for our local theme
 *
 * @category    design
 * @package     my_theme_default
 * @copyright   Copyright (c) 2011 Magebase.
 */
-->
<layout version="0.1.0">
...
</layout>

1. Adding and removing scripts and stylesheets

One of the things I find doing quite often is adding and removing JavaScript and CSS includes. For example, some third party extensions install their own CSS with, maybe a few lines of styling. I prefer to move this into the main stylesheet and just not include the original. Similarly, sometimes I don’t want some JavaScript included on all or some pages. Also, if I develop some of my own JS, I need to include it. Clearly, for functionality you develop via a custom module, you may have already created a module specific layout XML file that will handle your custom includes, but if it’s a theme specific JS feature, you may want to be able to include it in your theme’s layout XML.

To include an arbitrary file, you need to decide whether it is going to be included on every page of your site or just on some. This will determine the layout handle you need to specify.

We will work with the <default> handle to include our example script my_js.js and style my_styles.css on every page. We’ll use the standard addItem action method for adding files and target all this in the "head" block reference since that’s where the files are included.

<default>
    <reference name="head">
        <action method="addItem">
            <type>skin_js</type>
            <name>js/my_js.js</name>
            <params/>
        </action>
        <action method="addItem">
            <type>skin_css</type>
            <name>css/my_styles.css</name>
        </action>
    </reference>
</default>

Similarly, to remove styles or scripts, use the removeItem action method:

<default>
    <reference name="head">
        <action method="removeItem">
            <type>skin_css</type>
            <name>css/brandext/slider.css</name>
        </action>
        <action method="removeItem">
            <type>js</type>
            <name>some_ext/jquery-1.4.2.js</name>
        </action>
    </reference>
</default>

Note that the second removeItem element targets a JavaScript file that was included by some extension under the Magento js folder rather than the theme folder.

2. Replacing a local jQuery include with one from the Google CDN

We saw how we can easily include/exclude JavaScript files in the previous section. We removed a locally included jQuery library with the goal to replace it with the same library file loaded from the Google CDN. This will hopefully improve our site’s performance a little.

<default>
    <reference name="head">
        <block type="core/text" name="google.cdn.jquery">
            <action method="setText">
                <text><![CDATA[<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script><script type="text/javascript">jQuery.noConflict();</script>]]>
                </text>
            </action>
        </block>
    </reference>
</default>

In case you are wondering what’s going on here, closer inspection of the original included jQuery file showed that thejQuery.noConflict() call was added at the end of the file. This is required in order to avoid jQuery conflicting with the Magento built in Prototype library. Additionally, since the JavaScript file is being included from an external source, we can’t use the addItem action method.

To solve these problems in our replacement, we created a block of type core/text and added our script tag as a text node. The core/text block will automatically output the CDATA content into the head of our page since the default head.phtml has a call to: $this->getChildHtml().

3. Changing default block parameters

This somewhat cryptic section title refers to changing some default values in Magento template blocks such as the number of columns in the category grid or the number of upsell/crosssell products in their respective blocks.

Let’s start with changing the category grid:

<catalog_category_default>
    <reference name="product_list">
        <action method="setColumnCount">
            <count>3</count>
        </action>
    </reference>
</catalog_category_default>
<catalog_category_layered>
    <reference name="product_list">
        <action method="setColumnCount">
            <count>3</count>
        </action>
    </reference>
</catalog_category_layered>
<catalogsearch_result_index>
    <reference name="search_result_list">
        <action method="setColumnCount">
            <count>3</count>
        </action>
    </reference>
</catalogsearch_result_index>

Note that we have to find all the pages that show a product grid and change the column count otherwise, they will use the Magento default values.

Changing the upsell grid on the product view, for example, is also very simple:

<catalog_product_view>
    <reference name="upsell_products">
        <action method="setItemLimit">
            <type>upsell</type>
            <limit>3</limit>
        </action>
        <action method="setColumnCount">
            <columns>3</columns>
        </action>
    </reference>
</catalog_product_view>

Essentially, we are taking advantage of the fact that local.xml is processed at the end and the values set here will override any values set in other XML layout files.

4. Doing different things for logged in vs. not logged in users

Magento provides us with two interesting layout handles: <customer_logged_out> and <customer_logged_in>. We can be really creative in the way we can use these handles to affect our template depending on whether a customer is logged in or not. This also takes the logic out of the phtml files since we can include different content for the same layout block using this approach.

Let’s take the Magento built in stock alert functionality as an example. The default, if enabled, is to provide customers with a way to be alerted when a product comes back in stock by presenting the customer with a link, which when clicked, will add the logged in customer to a notification database. However, the usability of this feature suffers since when a customer is not logged in, they will be redirected to the standard Log In/Create an Account page. The wording on the notification link doesn’t indicate what a customer can expect when they click on it leading to potential frustration.

So, to improve usability, we want to display slightly different wording depending on whether the customer is already logged in or not. For this, we created a new phtml template block we are going to display instead of the default link. Since Magento will not show a Add to Cart button, we also want to show this block in the space of the button:

<catalog_product_view>
    <!-- remove the original alert URL block; we will put it back into the add to cart block below -->
    <reference name="alert.urls">
        <action method="unsetChild">
            <name>productalert.stock</name>
        </action>
    </reference>
    <!-- create our new block as a child block of the addtocart block -->
    <reference name="product.info.addtocart">
        <!-- Block comes from the original stock alert block in productalert.xml -->
        <block type="productalert/product_view" name="productalert.stock" as="productalert_stock" template="magebase/productalert.phtml">
            <action method="prepareStockAlertData"/>
            <action method="setHtmlClass">
                <value>alert-stock link-stock-alert</value>
            </action>
        </block>
    </reference>
</catalog_product_view>

We introduced our own phtml template in template/magebase/productalert.phtml. It contains:

<p class="<?php echo $this->getHtmlClass() ?>">
<?php if ($this->getSignupDesc()) : ?>
    <span class="alert-description"><?php echo $this->getSignupDesc() ?></span>
<?php endif; ?>
    <button type="button" title="<?php echo $this->escapeHtml($this->__($this->getSignupLabel())); ?>" class="button btn-alert" onclick="setLocation('<?php echo $this->escapeHtml($this->getSignupUrl()) ?>')"><span><span><?php echo $this->escapeHtml($this->__($this->getSignupText())); ?></span></span></button>
</p>

We added some more descriptive elements here in addition to the link (we turned it into a button to make it a clear call to action) so the customer can be clear as to what will happen. So, to make this work for the logged out and logged in states, we just need to add the following to our XML:

<customer_logged_out>
    <reference name="product.info.addtocart">
        <reference name="productalert.stock">
            <action method="setSignupLabel" translate="value">
                <value>Sign up to get notified when this product is back in stock</value>
            </action>
            <action method="setSignupText" translate="value">
                <value>Sign Up For Alerts</value>
            </action>
            <action method="setSignupDesc" translate="value">
                <value>Log in or create an account to be notified when this product is back in stock.</value>
            </action>
        </reference>
    </reference>
</customer_logged_out>
<customer_logged_in>
    <reference name="product.info.addtocart">
        <reference name="productalert.stock">
            <action method="setSignupLabel" translate="value">
                <value>Click to get notified when this product is back in stock</value>
            </action>
            <action method="setSignupText" translate="value">
                <value>Alert Me When In Stock</value>
            </action>
            <action method="setSignupDesc" translate="value">
                <value>You can sign up to be notified when this product is back in stock.</value>
            </action>
        </reference>
    </reference>
</customer_logged_in>

5. Removing, rearranging and replacing template blocks

Often we want to remove some blocks and replace them with our own modified ones as well as rearrange existing blocks.

There are two ways to remove blocks in layout XML:

  1. by using: <remove name="" />
  2. by using: <action method="unsetChild">

It is important that we understand what the difference between the two methods is. Essentially, the main difference is that the two methods operate on different contexts.

<remove name="" /> will operate on a global context, after all the layouts are processed which means that it will remove the named layout block completely, regardless of which layout handle added it. By using this approach, you can’t remove a block from one place and then add it in another.

<action method="unsetChild"> operates on a localized context, specifically, in the context where you use it. So, if you want to remove a specific block from a specific layout handle and possibly insert it at another position or layout handle, you need to use this approach.

As you can see, the difference between the two removal methods will give you a clue as to how you can go about rearranging your template layout. Use remove to get rid of unwanted blocks on a global level:

<default>
    <!-- remove the language and store switcher and footer links blocks, we won't use them -->
    <remove name="store_language" />
    <remove name="store_switcher"/>
    <remove name="footer_links" />
</default>

Use unsetChild to move or rearrange blocks in your layout:

<default>
        <!-- move the breadcrumb block from the top.bar child block back to the template root
(this overrides the modern theme breadcrumb positioning) -->
        <reference name="top.bar">
            <action method="unsetChild">
                <name>breadcrumbs</name>
            </action>
        </reference>
        <reference name="root">
            <block type="page/html_breadcrumbs" name="breadcrumbs" as="breadcrumbs"/>
        </reference>
    </default>

This example will replace the default product tabs block from the modern theme with our own tabs:

<catalog_product_view>
    <reference name="product.info">
        <action method="unsetChild">
            <name>info_tabs</name>
        </action>
        <block type="catalog/product_view_tabs" name="product.info.tabs" as="info_tabs" template="catalog/product/view/tabs.phtml" >
            <action method="addTab" translate="title" module="catalog">
                <alias>upsell_products</alias>
                <title>You may also like</title>
                <block>catalog/product_list_upsell</block>
                <template>catalog/product/list/upsell.phtml</template>
            </action>
            <action method="addTab" translate="title" module="catalog">
                <alias>description</alias>
                <title>Details</title>
                <block>catalog/product_view_description</block>
                <template>catalog/product/view/description.phtml</template>
            </action>
            <!-- neat trick to include a CMS Static block directly in the tab -->
            <action method="addTab" translate="title" module="catalog">
                <alias>shipping</alias>
                <title>Shipping Costs</title>
                <block>cms/block</block>
                <template>null</template>
            </action>
            <!-- define the CMS block ID for the shipping info tab -->
            <block type="cms/block" name="product.info.tabs.shipping" as="shipping">
                <action method="setBlockId"><block_id>tab-product-shipping</block_id></action>
            </block>
        </block>
    </reference>
</catalog_product_view>

Here, I also showed a nice little trick to include a static CMS block directly in the product tab all via layout XML only.

Conclusion

We saw how to utilize a local.xml layout file to manipulate and change the layout of a Magento theme. This powerful approach keeps all your template layout modifications in one single file thus making your modifications easy to find and also ensure an easier upgrade path if and when there is a theme update.

We can change almost all layout aspects of the standard Magento layout however there are some situations when this approach fails. Notably, this manifests itself the minute you want to modify the top.links block. Items in this block are added using the addLink action method so if you are wondering how to remove some links from the default set, the answer is, you can’t! Unfortunately, the page/template_links block class doesn’t implement a 'removeLink'action method so the resort is to remove the whole block using the unsetChild approach and add the links block back with our own links added to it in local.xml.

Another scenario is if you want to remove some of the navigation links from the My Account navigation. The easiest approach is probably to override the layout XML files that add the unwanted links. That’s why my screen shot of the layout folder at the start of this tutorial has some other layout files in it.

If you have any interesting local.xml tips and tricks, by all means share them in the comments section.

Refer: http://magebase.com/magento-tutorials/5-useful-tricks-for-your-magento-local-xml/