Top Useful Tricks For Your Magento local.xml
single,single-post,postid-15966,single-format-standard,ajax_fade,page_not_loaded,,qode-theme-ver-5.9,wpb-js-composer js-comp-ver-4.3.4,vc_responsive

5 Useful Tricks For Your Magento local.xml

15 Jul 5 Useful Tricks For Your Magento local.xml

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, or if you installed a third party Magento design.

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 useful tricks for your Magento local.xml 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:


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.

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


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


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.


In case you are wondering what’s going on here, closer inspection of the original included jQuery file showed that the jQuery.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:


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:

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

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

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:


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:

Use unsetChild to move or rearrange blocks in your layout:

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

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


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

Jenny Tran
No Comments

Post A Comment