Assumptions

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"?>
<config>
    <modules>
        <Koala_Emu>
            <active>true</active>
            <codePool>local</codePool>
        </Koala_Emu>
    </modules>
</config>

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:

<?php
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"?>
<config>
    <modules>
        <Koala_Emu>
            <version>0.0.1</version>
        </Koala_Emu>
    </modules>
    <global>
        <blocks>
            <emu>
                <class>Koala_Emu_Block</class>
            </emu>
        </blocks>
        <helpers>
            <emu>
                <class>Koala_Emu_Helper</class>
            </emu>
        </helpers>
    </global>
    <frontend>
        <layout>
            <updates>
                <emc>
                    <file>emu.xml</file>
                </emc>
            </updates>
        </layout>
    </frontend>
</config>

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"?>
<layout>
    <default>
        <reference name="head">
            <action method="setTitle"><string>Hello World</string></action>
        </reference>
    </default>
</layout>

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!