Building Your Theme

Magento is built on a fully modular model that transfers to unlimited scalability and flexibility for your store. By nature of the application, this approach to programming is mirrored in the way you will develop themes for your store. In this chapter, we will explore what that means for you and exactly how to go about developing a theme for your store with Magento.

Back to TopIntroducing Blocks and Layout

You’ve most likely worked with other eCommerce applications before arriving at Magento—with such experience we know you probably have a few sets of things that have become second nature to you when developing a theme for your store. Before you begin this documentation, we’d like to make sure you gather those expectations you may have and mercilessly throw them out the window. No, no, this doesn’t mean you need to learn a whole new language. It doesn’t even mean much will change with regards to your workflow, actually. All this really means is that there’re a couple of new tricks you will need to learn and along with it new tools we’d now like to introduce to you. Marry these tools, keep them at your side at all times and make sure you pay them lots and lots of attention—You do all this, and we promise you, you will love yourself for it. Are you ready? Here they are:

  1. Structural Blocks
  2. Content Blocks
  3. Layout

Creating the Mental Note

In order to give you a clear understanding of what blocks and layouts are, here’s a mental picture you can draw for yourself:

  1. Imagine an outline of a block (like in Diagram 1 -- Don’t reference the picture the whole time. Imagine it and follow along).
  2. Now imagine the outline of a block filled with one block.
  3. Now imagine two blocks and the outline growing with the blocks.
  4. Now imagine three blocks and the outline growing with the blocks.
  5. Now imagine four and the outline growing with the blocks.

    Diagram 1

  6. Now look at this snapshot of the category landing page in Magento:

    Diagram 2

  7. And now look at the break-down of the above snapshot into two types.

    Diagram 3

    Diagram 4

The mental picture you just created serves to give you a parallel comparison between concept and actual realization of blocks. I know you’re probably completely lost. Let us explain.

In concept, the outlines in Diagram 3 are the structural blocks. They are the parent blocks of content blocks and in realization, serve to position its content blocks within a store page context (as in Diagram 4). These structural blocks exist in the forms of the header area, left column area, right column…etc. which serve to create the visual structure for a store page.

A content block on the other hand, in concept, is the individual-colored blocks that make up a structural block. In a store context, they are the true meat of a store page. They are representations of each functionalities featured in a page (such as category list, callout and product tags…etc.), and employs template files to generate (X)HTML to be inserted into its parent structural block.

Layout is the tool with which you can assign content blocks to each structural block you create. Layout exists in the form of XML text-file and by modifying the layout you are able to move blocks around in a page and assign templates to the content blocks to produce markup for the structural blocks. In fact, with the help of a few layout files alone, you are able to modify the visual layout of every page in your store. Read further about layouts in Intro to Layouts.

With Magento, you will no longer have a template file called left_column.ext and in it have the never-ending spaghetti of markups that must be manually managed depending on each functionality needed for the page. Instead, your templates are managed on a per-functionality basis and you can load and unload functionalities in your store page by the virtue of a couple of layout commands alone.

Back to TopStep by Step Guide to Building a Theme

Here’re the full list of tools Magento gives you to build your themes:

  1. Templates
  2. Layouts
  3. Blocks
  4. Skins (images, CSS and block-specific Javascript)

In order to build a theme for your store, your work flow will consist of the following steps:

ONE: Disable your system cache

In order to prepare your Magento for production, you need to first disable system cache by going to the Administration Panel ( and navigating to System -> Cache Management. Select 'Disable' from the 'All Cache' select box and click on save. Doing this will ensure that you see a faithful reflection of your store front as you make the changes.

TWO: Determine all the possibilities of structure types for your store

Before you even start creating the markup for the store, you will first need to ask yourself the type of page structure you’d like to have for each of your store pages. Make yourself a list that looks something like this:

  • Home page will use the three column structure.
  • Category listing page will use the two column structure that includes a right column.
  • Customer pages will use the two column structure that includes a left column.
Skeleton template

Once your list is complete, you will create the (X)HTML markups for each structure type and save them as skeleton templates into app/design/frontend/your_interface/your_theme/template/page/. A skeleton template is called such due to the nature of its purpose—all it really contains (aside from the <head> elements), is the presentational markups that serve to position each structural block into according markup areas.

Sample skeleton template

Upon scanning through the sample skeleton template above, you will notice a PHP method called <?=$this->getChildHtml()?> inside each presentational markup. This is the way Magento loads structural blocks into skeleton templates and hence is able to position all the contents of the structural blocks within a store page.

Each getChildHtml calls on a name as in <div class="header"><?=$this->getChildHtml('header')?></div>, and these names are ways by which each structural block is identified in the layout. Skeleton templates are assigned to the store through the layout.

THREE: Cut up your (X)HTML according to functionality

Once you’ve created your skeleton templates, you will now need to create the template for each content block.

Magento likes meaningful templates

You will need to cut up the (X)HTML markup built for your page and supply the according markup to each functionality of the page. For instance, if you have a mini-cart area in your design, the markup for this area alone will become its own template file. Same for your product tags, newsletter sign up…etc. All these functionalities already come with Magento, so you can reference the existing template tags to build your mark-up logic.

Where to save the templates

Diagram 5

The full markup for any page in your store is introduced via an array of templates that each represents a functionality of a module. In order to find out what templates are being called to a page you'd like to modify, you can turn on the Template Path hints. In order to enable it:
1. Go to the admin and navigate to System -> Configuration
2. Select your store in the top left website/store selector
3. When the page reloads, select the 'Developer' tab and select 'Yes' for Template Path Hints.
When you're done, go back to the store front, reload your page and you will see the path to all the templates listed according to the block. In order to modify the markup, all you have to do is follow the path written out for you and modify the according template(s).

FOUR: Change the layout to reflect your design

Once you’ve distributed some of the markups, you probably would like to now move the templates around in a page to see how you’re progressing along.

Where to find layouts

In order to access the layout files, go to app/design/frontend/your_interface/your_theme/layout/. Just like the templates, layouts are saved on a per-module basis therefore you can easily locate the layout file to modify with the help of the Template Hints. First, enable Template Hints, reload the the page you want to modify, and look at the path of the template file(s) that the Template Hints will provide you with. If you want to (for instance) move the mini cart, reference the template path (ex:app/design/frontend/default/default/checkout/cart/sidebar.phtml) and use the first folder name inside the theme folder (indicated in bold, which is the module name) to find the according layout file. So in the case of the mini cart, you know to look in 'checkout.xml' to modify the mini cart positioning. Each layout file(should it be necessary) further sections into per-page basis layout command. Each area of per-page layout is clearly marked with comments reflecting its usage, but the application itself recognizes the layout separation by the handles of each layout.

Default layout versus Layout Updates

There are two types of layouts--default and updates. A default layout (page.xml) is the layout that by default applies itself to almost every page in the store. All other layout files are Layout Updates that simply updates the default layout on a per-page basis.

Let’s take for example your skeleton template:
In the default layout, you have it set to three columns, which means by default most all of the page in your store will have the three column page structure. But it’s not the three column structure you need for your product page. For it, you want a two-column structure that includes a right column. To accommodate this, you will leave the default layout alone and open catalog.xml in which you can place some layout commands that tells the application to load the two-column structure to your product page instead of the default three. This is called the process of updating a layout.

Example way of assigning skeleton template

<reference name="root">
<action method="setTemplate"><template>page/2columns-right.phtml</template></action>

Let’s take another example:
Say by default you want a newsletter sign-up box in your right column, but in customer account pages you want to exclude it. In this case, you would leave your default layout alone and open up customer.xml, into which you will place a command that unsets the newsletter content block, excluding the newsletter functionality from the page.

:: In this chapter we walked through the steps of modifying a theme. In the next chapter we'll get into the details of how to modify layouts.