Build your own Magento override-module

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.

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 Designer 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 theapp/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 fileKoala/Emu/Helper/Data.php and add the following content to it:

<?phpclass KoalaEmu_Helper_DataextendsMage_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>

<referencename=“head”>

<actionmethod=“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.