We have covered a lot about Magento’s layout XML in our past 2 articles  . 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 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 xml version="1.0" encoding="UTF-8"
1. Adding and removing scripts and stylesheets
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
1 2 3 4 5 6 7 8 9 10 11 12 13
1 2 3 4 5 6 7 8 9 10 11 12
2. Replacing a local jQuery include with one from the Google CDN
1 2 3 4 5 6 7 8 9 10
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
Changing the upsell grid on the product view, for example, is also very simple:
1 2 3 4 5 6 7 8 9 10 11
4. Doing different things for logged in vs. not logged in users
Magento provides us with two interesting layout handles:
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
1 2 3 4 5 6 getHtmlClass() ">
getHtmlClass() ">if ($this->getSignupDesc()) : echo $this->getSignupDesc() endif;
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
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:
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:
1 2 3 4 5 6
1 2 3 4 5 6 7 8 9 10 11 12 13
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
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.