Use a Local.xml File

January 30, 2014 / Posted in Certification, Magento by Tatiana Kozyreva
Download PDF

Is it possible to update or change a theme layout so that all default files would remain unchanged, yet all changes you make would be listed in a single file?Also, is it possible to optimize the working process in such a way so that you would not need to search for multiple changes in the template files?  One would say that this is impossible, however the solution lies in the local.xml file.

What is local.xml?

The best way to update a theme layout is to create a local.xml file.

Using a single local.xml file, located in your theme folder, it is possible to override or update all XML blocks of that theme. All you need to do is to create one file inside your theme folder and to write your own XML.  Mаgentо reads XML files in a specific order so the file local.xml will be read at the very end of the xml sequence. When all XML files are read, Mаgentо will search for changes inside local.xml and then will correspondingly override an update your theme layout.

This method allows us to conveniently implement new changes in our theme layout.

How to set up your local.xml?

  1. Create a local.xml file inside your theme layout folder app/design/frontend/<your_package>/<your_theme>/layout/local.xml
  2. Add basic XML structure

Adding and deleting script and stylesheet through local.xml 

Quite often it is necessary to add or delete a js or css file. For example, some third-party extensions install their own CSS styles. The same way sometimes you may need to add some javascripts so that they are available either on all pages or just some of them.  Besides, you can add a JS and your own styles to any of your modules.
To add a file you first need to decide whether it should be available on every page of your site or just on some of them. Because the type of layout handle will depend on that choice.

Let’s show an example:

In this example we added a  new CSS file new_stylesheet.css into local.xml. We also added JQuery into the library  using the method attribute addJs.  All these files will be added into the head of our template and will be available on all pages of the theme, since they are located inlayout handle <default>.

How to delete, move or replace a block in Mаgentо via local. xml?

Quite often we need to delete some blocks or to replace them with our own modified versions, as well as to change or move them.

There are two ways to remove blocks in XML layout:

  1. <remove name=”” />
  2. <action method=”unsetChild”>

It is important to understand that the main difference between these two methods is that they operate in different contexts.

<remove name=”” />  operates in global context.  When finished with all layouts,  Magento will completely delete the block with indicated name=””, regardless of which layout  handle it has been added to. Using this method  it is impossible to remove a block from one location and then add it to another.

A simple example how to delete a block through local.xml using the remove tag. For example, take the blocks  “products compare” and “related products”: using the method remove we can delete blocks with such names from the context.

<action method=”unsetChild”> operates only in the context where it is being used. unsetChild is created for moving existing blocks from one place to another. You need to use this method if you want to remove a specific block from a specific layout handle and then insert it to another position or layout handle.

In this example the block “Newsletter” and “tаgs_pоpulаr” were deleted from the block “left” and now we can move them to a different location.

As you can see, the difference between these two methods lets you  understand how to move and change the template layout.

In the below local.xml file you can see how to delete other blocks as well as to see the structure of the file.  I would also like to point out the importance of dividing the file into structural units and adding comments. Local.xml can contain various blocks, that is why it is better to add necessary comments to avoid confusion in future when more and more blocks will be added.

For example:

You can also indicate your main steps and actions so that other developers would not get confused in your file.

An example of local.xml:

So now we know how to use local.xml layout file, manipulate, update and modify layout in a Mаgentо theme.

This useful 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.

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


  1. Thank you Tatiana, well explained.
    would you please tell me the difference between addItem and addcss for a stylesheet? is the additem just more general that can use js and css types or they have more important difference?

  2. Good Explanation ….Thanks a lot for your hard work.. well done and keep continue knowledge sharing..:)

  3. Brilliant, very helpful on one of the most powerful -yet strangely undocumented- features of Magento.

    Thank you!

Post a new comment