Introduction to the Magento page structure: layout, block, templates, themes and packages

If you are developer or web designer, you have been face to face with the Magento page structure. This is not difficult to update design, but you must know how the Magento pages are built


Before describing the Magento page structure, I’ll explain what is a package and a theme, and how they are linked with Magento file system, and what is their interest

Definition: the Package and theme concepts

With a fresh install of Magento, all pages are ready to use. But I suppose that you want to customize the design to provide your own design, and packages and themes will help us


A package defines the global structure of your website: how they are structured: where is located your footer, …

Even if Magento comes with a default one, you should define your own package

The base package embedded in a native Magento is called (for frontend), base


A theme is a variant of your package: in december you would define a design based on christmas, or for the february 14th your marketing service would perhaps make a special version for the valentine’s day: your website will keep its structure, but some elements will be updated to provide a specific but temporary design: these updates will be made with a new theme of your website

Magento come with a default theme called default

Configure your frontend design: define the package and the theme

Frontend design is configured through the administrative admin panel available through the menu

System > Configuration > Design

Location context: different page structures for front-office, back-office and installation process

As you can see, page structure is different between front-office and back-office: Package and theme are dependant on one of the following context:

  • frontend: for all front-office available pages
  • adminhtml: for the administrative panel pages
  • install: for the pages displayed during the installation process

According to the context, it will be able to find the required elements which define your website structure

Magento design and directory tree

Design and themes are strongly linked with the package and theme specified and configuration values will help Magento to find how to load your page structure and content:

Page structure are defined in the folder : app/design/%context%/%package%/%theme%

For exemple, the folder app/design/adminhtml/base/default define the folder where to look for the files of the default pages embedded in the Magento back-office

Is package and theme folder case senstive? Yes. So be sure in unix locations to use (by convention) the lowercase

Magento page structure

Now you know where Magento will look for the required files to define how the page is built. We will see now what comprises a Magento page

Magento page structure content: the couple block / template

Homepage content on a Magento with a sample data package: some container can be identified
Category page content on a Magento with a sample data package: the same container can also be identified

As you can see on a default page structure, some elements can be found in many pages: this is each time the same “content”, the couple block / template: Each unitary element defined in layout is a couple block / template: these elements are part of the MVC (Model View Controller) “design pattern” embedded in Magento.

Each couple block/template define the unitary elements of your layout: the breadcrumb, the code pool, the product sheet price display, have specific rules managements to work, and are relatively independant of the others ones: do you need to know how code pool works to display the breadcrumb? does the footer has specific rules related to product sheet displayed? no; they are independant and do not need to know themselves

Templates manage only differents marketing output (christmas, summer, sales, ...) and technical output (html, xhtml, mobile, etc)

The block in the couple block/template: the logic

Block are PHP classes which define all the management rules for the display embedded in the couple block/template.

A block should not build output string: it must only prepare required values used in template

To display HTML, Blocks class should be an instance of Mage_Core_Block_Template

Templates: the design part in the couple block / template

Ok, you have defined your rules management in the block, now we must display the output: this is the template role. Template is a PHP file responsible for generating the content to send (often some HTML). It’ll only fetch from the block whose data it must manage, and process them in: no loading, no calc, this is only display

Templates files are located in the template subfolder of the current theme applied

Display the couple block template usage in our pages

If you want to display the couple block / template usage, you can enable the developper option in the system > configuration > developper > debug hint location (context other than global): this will highlight you which block class and templates are used with your layout

Magento Page structure is managed though layouts

Now that we know what is the content of a Magento page, we’ll see how they are arranged

Each page of a Magento is loaded with a layout: layout defines how the page will be built: this is a reference of how the page will be built: each update will update the page structure

For each theme you can define a layout, and so, update the page content. All used layouts are located in the layout subfolder of your couple package/theme design folder

Magento design folder will contain layouts and templates subfolders

Layout files are XML files. The root node of the XML file is <layout> to have the minimal following structure

<xml version="1.0' encoding="UTF-8"?>

Don’t forget roles of each elements in a page structure!

If you have something to remember from this topic is the role of each element which compose a magento page: very often we can see that roles used of each composant are not the expected one and shortcuts taken to build the page can make harder it’s maintenance

This structure is available for all versions on Magento 1.x. Magento 2 seems to update how will be organized the code content. We wait and see a stable release 🙂

How Magento load your modules configuration? the activation files located in app/etc/module folder

This post will be the first part of two topics based on the Magento configuration and on how this configuration is cached. If you are already experimented in Magento, this topic is probably something you already know, but I hope it would be helpfull for those who start with Magento

Magento is based on a module architecture. Each module can define its own components, blocks, scripts, models, databases connections, etc. Each module can embed multiples configurations files, but the main one is the config.xml file located in the module etc subfolder. To avoid reading each configuration file each time, every module configuration is saved in cache. Here’s how it works

First, Magento requires to know which scripts must be played: Magento load each XML files in app/etc/modules folder to find which are the modules we want to declare

Module activation file: the files list in app/etc/modules

For a quick reminder, files located in app/etc/modules folder should have the following structure:

<?xml version="1.0" encoding="UTF-8"?>
                   <active>true</active><!--true or false -->
                   <codePool>local</codePool><!-- local / core or community -->
                      <!-- list of %Module_Identifier% prerequise to make our module works fine -->

active node in Magento XML activation file

This node informs Magento that we want to use this module. Expected values are case sensitives and should be true or false. If you set false, there will be no output, no override, no functionnalities, no layout updates

Magento bootstrap will only take care of the modules which are active true. Yhe Other ones are ignored.

codePool node in XML activation file

Codepool values are the subfolders located in app/code folder. As I mentionned before in my post on the loading APIs, changing codePool can modify how your classes are loaded, and so, if they can be overloaded or not

CodePool value provided in the activation XML file will help Magento to know where to look for our module configuration file

Module identifier

Module identifier allow Magento to link the configuration file with the module folder: The expected value for the Module identifier is based on %Namespace%_%ModulePath%: with this value and the codePool, magento is able to determine where to look for our module etc/config.xml file

XML identifier

I’ve noticed that encoding and version are attributes required for the XML files header. Truly, only version is required. But take the habitude to also note your encoding, and normalize your XML version as UTF-8

After browsing the app/etc/modules and read all XML files in, Magento knows which modules must be activated and loaded in our Magento

Dependancy tree between modules: the depends node in Magento XML module activation file

This node is not also required. But it can modify how setups are played: without dependancies, modules identifiers are sorted in alphabetical order. If your namespace starts with a character before M (for Mage namespace), do not define the dependancies and deploy all your data without an existing magento database, your setup will be runned before the Magento’s one, and so, there is a big risk that it fails if you call some Magento entities. So take also the habitude to define at least Mage_Core in your module dependancies.

Sometimes we can see that dependancies are defined in your module configuration file (config.xml). because dependancy tree is built before config.xml has been read, it has no interest

Merge configurations files

After reading the activations files, Magento knows which modules it must load (he knows namespace_module path, and codePool). So it can now go reading each modules configurations defined in module configuration file, the config.xml file: all config.xml files for active modules will be merged in a single one XML structure which will serve as global configuration

Now magento can save all data in cache

How to organize your modules definition in activation files?

Because it’s a XML structure and they are merged, you have two choices for your modules

  • Define each module location in a dedicated file
  • Define all yours modules locations in an only file

Magento chooses to use only one file to define all its modules: the file app/etc/modules/Mage_All.xml

If you work without versionning system (like git or subversion), there is no risk to work with only one file

But if you are numerous to work on the same project, you should prefer to use one file per module for the following reasons:

  • You can reduce conflicts risks (the less developpers work on the same file, the less risk you have to get conflicts)
  • If you want to publish some modules on Magento connect, you should make reworks in a single file usage


Is there a way to check that my module is well loaded?

The quickest way to check if your activation file is well read by Magento is in the Administrative panel available through System > Configuration > Advanced: If your module identifier is listed there, all is fine. In other cases, be sure to check its syntax

Thank you for this topic. When will be the second part published?

some suggested me to publish more often 🙂 Next part should be post quicker