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.
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
Sometimes, the same namespace also occurs in XML but than lowercase. We will there for also use names like
koala_emu. If you choose your own namespace and module-name, make sure it is kind of unique. A module name like
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:
Creating the module subfolders
Next, we are going to create the necessary folders. Create the following folder-structure within the
Sometimes, a module also contains extra folders like
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
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.
We will not discuss the entire syntax of this XML, but in general this code is doing 4 things:
- It defines a version number
- It defines a namespace
- It defines a namespace
- It defines a XML layout update file
The last thing was actually the goal of this tutorial.
The XML layout
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:
<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
contacts) you should see the custom title.
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!