Tips For Using Magento Layout XML

Magento’s layout XML can be intimidating for a developer, new developers in particular. Because there is so much flexibility with XML inside of the Magento framework, there is a lot to learn. One of the most powerful functions you should master when in the layout XML is the ability to group, focus, and/or segment your XML code with Layout Update Handles.

Layout update handles are Magento’s way of associating a group of XML instructions to the specific page or pages that need to receive those instructions. By default, Magento has many, many, many handles already built into the system. Things like product pages, category pages, and CMS pages all have their own handles. Some handles are associated to a large group of pages; the <default> handle, for instance, is associated to every page on your instance! There are also some, more abstract, handles like the <customer_logged_in> handle which is applied to all pages when a user is logged in. The best part about handles is that any page can have any number of handles associated to it, and each handle can have different layout XML instructions.

Where are these handles and how do I use them?

Well let’s start off with a snippet of code and identify the handles.

page/3columns.phtml
css/cms.css

The code in the previous snippet is a very rudimentary block of Magento layout XML. You will notice that we have our primary <layout> node in which all of our layout XML will be placed. The next level of nodes,<checkout_cart_index> and <cms_page>, are handles. If you placed this snippet inside of a local.xml document in your theme, you would see your shopping cart page update from one column to three and ALL of your CMS pages would now have a new stylesheet associated to them named “cms.css”. Magento followed the instructions we wrote in the layout XML only on pages that had those handles associated.

For the sake of example, lets swap out the <cms_page> handle for the <default> handle:

css/cms.css

Like I said earlier, the default handle is associated to every page on your install. This means where we once had the “cms.css” file associated only to CMS pages, we now have this CSS file associated to every page on our site. It is easy to see how useful handles can be for updating large numbers of pages all at once without sacrificing the ability to target pages very granularly.

How are layout update handles created?

There are several ways that layout update handles can be created:
• You can add your handle to a page manually through a custom module. By setting up an observer on the <controller_action_layout_load_before> event and using the addHandle method, you can add any handle you like and give it any number of conditions.

• You can use the <update> node inside of another handle. The <update> node allows you to copy the XML instructions from one handle to another. One thing to note, however, is that you can use the <update> node to pull the instructions from an arbitrary handle that isn’t being created by Magento. By creating this arbitrary handle, and using the <update> node, Magento will associated your arbitrary handle, and any instructions associated with it, to the scope of the handle to which it was associated.

• You can create a custom module with a frontend router. When you create a frontend router for a custom module, Magento will programmatically create a new handle for you. The method by which the handle is created is by merging your modules frontname, action controller name, and action method with an underscore delimiter. So, for instance, if your route is www.website.com/osh/kosh/bgosh the handle that will be created will be &l;tosh_kosh_bgosh>. Many of Magento’s core modules follow this structure since many of them have their own route.

Why are handles so important?

The use of handles in parsing the layout XML is profoundly important. When Magento loads a page, before any of the layout instructions are followed, Magento will look at the available handles for the page about to be loaded. It will then traverse the tremendous XML document and strip out any handles that are not being used on the page. Since there would be no reason to parse XML that isn’t useful, Magento can cut huge amounts of overhead by using this method.

Although Magento layout XML might be a bit intimidating at first, with a little insight on how handles and other systems work, you may find that it’s not as bad as you think!

Have questions? Drop us a line!