The Truth About Local.xml

When I first began working with Magento, I began some heavy Googling and learned about controlling the Magento layout through the local.xml file. I read plenty of articles that you’ve probably seen out there on the web about how you can do all these magic things through this file. In fact, you can do all of those things through this file. However, the more I read and my being new to Magento, I thought you could and should update everything through the local.xml file. After several years of working in good and bad Magento developer’s code, taking projects on from scratch, and working with several nightmares of 3rd party dominant integrations, I believe I know local.xml and when and where it has its place.

Common Beliefs and Practice of Magento Local.xml

Beginning in Magneto was hard. HARD. It sucked. Deep down, I knew Magento was the next “IT” platform, but I was ready to quit. Maybe I was beyond ready – but one day I got a call from a a friend of mine named Andy. Andy is a successful entrepreneur focusing on marketing and social media over at and his timing was pretty much perfect. He was able to put me in touch with a client who needed several Magento stores under one codebase and so I decided to stay the course.

Setting up Magento was tough enough, but I knew I had to properly override files, controllers, and what is known as blocks in order to maintain proper code. Like WordPress, Drupal, or any CMS, Magento has its core code and then the ability to override it by using your own theme and extensions or modules. In any case, heavy Googling and reading through the Magento forums all I saw was the news about local.xml and how messing with catalog.xml or page.xml was now incorrect, after version 1.3.

In cases like this, I’m a stickler for doing it the right way because I want the next developer to come behind me and not bad-mouth my name. That being said, I’ll admit I’ll throw a *hack in occasionally to fix an IE7 problem on the fly on occasion. :-). Anyway, I digress. The point is, I became passionate about never touching catalog.xml or page.xml or anything else in the layout directory.

I’m here today to say that I believe this point of view is wrong.

Basing a Magento Theme Around Local.xml

I believe the local.xml file is to be used like the WordPress functions.php. Not in the degree that it’s going to hold all of your overrides, but to the extent that it is your Magento theme’s common functions. If you work in WordPress more often than not , like myself, you have (or should have) a codebase that you repeatedly use. These days I have my own theme that I pull in with a lot of functions, but in the beginning and for more simple sites, I used the functions.php file some basic things. In short, it gave me quick access to manipulate an excerpt, it removed a ton of garbage from the <head> tag, was ready to register jQuery and other things. Now, I use local.xml the same way.

When I pull in a new Magento website, my local.xml file removes lots of stuff that I NEVER use. It also adds a custom CSS file to the head tag, adds the jQuery library, and sets me up like you want to be, in a comfortable environment.

A Few Things Local.xml IS and ISN’T Good For

Local.xml IS the place for grabbing custom page handles. If you have created a new CMS page and you need to add a few things to it then your in the right place.

It ISN’T the place to completely layout the catalog/product/view.phtml page, or pages of the like. Doing so may save you a few minutes of upgrade time in the future, but can cause a world of heartache trying to override all the other XML files in place.

It IS good for setting page templates. More often than not, you have 2-3 pages templates per website. Local.xml is a great place to keep all of your templates stored, as opposed to individual files and putting custom layout options in the admin. What if you changed a layout? Would you want to edit that XML in 15 different CMS pages?

It ISN’T good for adjusting your top.links (login, logout, etc.). That may be a controversial point because it can be done. I’ve never built a website where the top.links where not complicated, where items were not rearranged and where additional classes were not needed. I almost always override my header.phtml file and physically adjust the top.links. If Magento adjusts the HTML to where your header.phtml is in a bind, you can bet your XML would be in a bind too. Why wouldn’t they add features up there that mess up your “priority” links? Who knows. And in any case, the upgrade is an easy fix to port over Magento’s new code IF they ever update this file.

Local.xml Is Your Friend, Not the Savior

Magento’s Local.xml is a great asset and has tons of uses. It is not, however, the lifeblood and savior of Magento. The main reason local.xml file is so highly sought after and researched is because it is powerful and can help with upgrades, which makes it seem always proper.

One thing I’ve had to learn is Magento is not WordPress. There are several tips and tricks to upgrading that make the local.xml file much less relevant in that it doesn’t have to completely replace both HTML for a product view page and completely override a catalog.xml page. I had to learn to use Git’s DIFF command when upgrading. Most times if you visit the active theme’s layout folder, you’ll be able to see the overridden XML files and can quickly do a diff to see if they are causing problems in your upgrade.


Don’t get me wrong – the file is great. It should be used when appropriate. But don’t get bogged down. Do it correctly and cleanly in your theme and you will be fine. Just be careful and don’t fret about it too much.