The Magento theme uses two very powerful elements, with which you can modify most of the HTML-output of the Magento system: XML layouts and PHTML templates. Core hacks are very bad, so Magento allows you to override each file within your own Magento theme.

While this is no problem with PHTML templates, XML layouts contain many times complicated structures. If you could add your own custom XML layout file, you allow have to manage this file - separating your own changes from the core files. This tutorial shows you how to build a custom Magento module, that only adds its own XML layout file - so you can safely add XML updates to it.


This tutorial assumes you have already a solid understanding of what XML layouts can do. You don't have to be an expert, but you have to grasp the general concept of XML layouts and XML updates. The Magento Designers Guide explains this matter in more detail.

Our namespace

We're going to create a module, so we also need to pick a namespace and a module name. As namespace we pick a virtual company-name Koala, and as module-name we will pick the name Emu. The full module name there for becomes Koala_Emu.

Sometimes, the same namespace also occurs in XML but than lowercase. We will there for also use names like koala, emu and koala_emu. If you choose your own namespace and module-name, make sure it is kind of unique. A module name like Site or Core is in general a bad idea.

Defining the module

First of all, we're going to define our module within Magento. For this, we need to create a file called Koala_Emu.xml within the Magento folder app/etc/modules with the following contents:

<?xml version="1.0"?>

Creating the module subfolders

Next, we are going to create the necessary folders. Create the following folder-structure within the app/code/local directory:

  • Koala
  • Koala/Emu
  • Koala/Emu/etc
  • Koala/Emu/Helper

Sometimes, a module also contains extra folders like Block, Model and controllers, but we are going to skip that within this example.

Defining a helper

When working with modules, Magento expects sometimes to find a helper-class. The class doesn't have to do anything, but to avoid future problems, we're just going to create it anyway. Create a new file Koala/Emu/Helper/Data.php and add the following content to it:

class Koala_Emu_Helper_Data extends Mage_Core_Helper_Abstract

That's it.

The XML configuration

Now comes the big stuff: We are creating a configuration file Koala/Emu/etc/config.xml which contains XML code you might not yet understand. In this case, the XML will only define those parts that are needed to add your own custom XML layout file in the theming directories. It doesn't do anything else.

<?xml version="1.0"?>

We will not discuss the entire syntax of this XML, but in general this code is doing 4 things:

  • It defines a version number 0.0.1 (whatever)
  • It defines a namespace emu for block-classes
  • It defines a namespace emu for helper-classes
  • It defines a XML layout update file emu.xml

The last thing was actually the goal of this tutorial.

The XML layout

The config.xml now points towards an emu.xml file, which should be located in the layout directory. By default, this layout directory is app/design/frontend/base/default/layout/ but it could also be a custom folder (if you have configured to do so within the Magento backend).

The point of using a custom XML layout file might not be appearant, but once you dive into custom theming, having a custom XML layout file in place might save you a lot of time. For now, we are just going to create some dummy content in it:

<?xml version="1.0"?>
        <reference name="head">
            <action method="setTitle"><string>Hello World</string></action>

This references the HTML head-section of every page (<default>) and sets the page title to Hello World. If you browse through your Magento site, you might notice that this is not the actual page title - this is because other modules can set the page-title dynamically. But if you would browse to a page without default title (for instance catalogsearch/term/popular or contacts) you should see the custom title.

What's next?

This tutorial gives you a very powerful tool: Your own XML layout file with which you can do what you want. In upcoming tutorials we will put this to use. Stay tuned!

Posted on July 5, 2010

About the author

Author Jisse Reitsma

Jisse Reitsma is the founder of Yireo, extension developer, developer trainer and 3x Magento Master. His passion is for technology and open source. And he loves talking as well.

Sponsor Yireo

Looking for a training in-house?

Let's get to it!

We don't write too commercial stuff, we focus on the technology (which we love) and we regularly come up with innovative solutions. Via our newsletter, you can keep yourself up to date on all of this coolness. Subscribing only takes seconds.

Do not miss out on what we say

This will be the most interesting spam you have ever read

We don't write too commercial stuff, we focus on the technology (which we love) and we regularly come up with innovative solutions. Via our newsletter, you can keep yourself up to date on all of this coolness. Subscribing only takes seconds.