Trying to make sense of theme inheritance in Magento, I have started to put a simple script together to help navigate the themes installed on a shop. When I say simple, I mean very simple. Jump straight in and have a browse:

This script is installed in the root directory of our 1.4 test installation.

What it gives you is a layered approach. First you select the interface, then the theme within that interface (try default->modern for example).

The script will then list all the layout files that make up that theme, and show you where those layout files come from, i.e. which parent themes they are inherited from. A complex theme may consist mostly of its own layout files (the iPhone theme for example). A simpler theme may override just a few layout files, choosing to fall back to the default theme, or the new “base” theme in Magento 1.4.

For each layout file, the handles are listed. Each handle provides some unit of functionality in the theme – usually a block or a widget – some simple, some very complex. The next step will be to document what all these handles do, and how they get called up. Some are invoked from the Magento core, some from modules, and some from other templates in the theme, so it can all get very complex very quickly, leaving the average themer lost when they only wanted to change a few aspects of a theme.

It is the content of the handles that are the really important part of a theme. The layout files just provide a convenient way to package together a number of handles in one place. The same handle can appear in multiple layout files, and they are simply chained together in alphabetic order (of the name of the layout file).

What the layout files do is allow a module to keep all its handle-based theme functionality in one place. A theme developer could also use it to keep all their theme additions in one place too – there is no point spreading that functionality all over a custom theme by overriding dozens of layout files if all you want to do is tweak menus and blocks.

By clicking on the “handle” link in the script, the table gets inverted – now you get to see all the layout files that each handle is included in.

Selecting a handle will list the contents of each instance of those handles – the XML instructions to the theme engine.

To take this script further, it would make sense to interpret the content of the handles. Ultimately it should then be possible to do searches on those interpreted instructions to find, say, where a particular block or image is displayed from.

Feedback is welcomed – is this any use? Should I publish the script? Does anyone want to expand on it, perhaps packaging it into a module to help theme developers?

Download the script here: (contains theme.php, to be copied to your Magento root directory).