Building your own custom Magento Theme

In this article I will be showing you how to create your own custom theme for Magento 1.4. Rather than creating a totally bespoke theme, we will create a theme based on the default theme. However, by doing this, you will have all of the information needed to create your own totally bespoke Magento 1.4 custom theme.

Directory Structure

The first part of creating your custom theme is to create your directory structure. To understand this, first we need to learn about themes and packages.

Package & Theme: What's the difference?

Look at the directory structure below and see whether you recognise it.

• app/design/frontend/default
• app/design/frontend/default/default
• app/design/frontend/default/default/layout
• app/design/frontend/default/default/template

• app/design/frontend/custom-theme/default
• app/design/frontend/custom-theme/default/layout
• app/design/frontend/custom-theme/default/template

The above directory tree is the template structure used in Magento 1.3.2.4. Notice the folder default has a sub-directory also called default? In this scenario, the first folder called default is the package being used while the sub-directory called default is the theme. Also notice that the default package has another sub-directory called custom-theme. This is where the majority of developers would previously put their new theme. While this works, this is not the correct way to structure your themes.

In the above scenario, the default package houses 2 separate themes. In theory, a package can contain as many themes as you like. The beauty of this system is that as well as having your base theme, you can create new themes which simply enhance your base theme. This allows you to reduce the amount of code you need to write and maintain!

The Directory Structure in Magento 1.4

• app/design/frontend/base
• app/design/frontend/base/default
• app/design/frontend/base/default/etc
• app/design/frontend/base/default/layout
• app/design/frontend/base/default/template

• app/design/frontend/default
• app/design/frontend/default/default

• app/design/frontend/fishpig/default
• app/design/frontend/fishpig/default/layout
• app/design/frontend/fishpig/default/template
• app/design/frontend/fishpig/fish-theme
• app/design/frontend/fishpig/fish-theme/layout
• app/design/frontend/fishpig/fish-theme/template

You'll notice that the directory structure is identical apart from the addition of the folder called base. This package contains a theme named default, which contains all of the base template files needed for a Magento theme. The base package serves as the final fall back package. Let's discuss fall back so we can understand exactly how to structure our package.

Template Fall Back in Magento 1.4

This subject almost deserves an article of it's own, however, I will try and condense it here without stripping too much out. In the above directory structure, there are 3 packages:

• base - contains the theme default
• default - contains the theme default
• fishpig - contains the themes default and fish-theme

Using the above structure, let's pretend we have configured Magento to use the fish-theme in the fishpig package. If we were to navigate to a product page, Magento would attempt to load the file package/theme/catalog/product/view.phtml. In our scenario, Magento would first look in the fish-theme theme. If the file could not be found here, it would next check the default theme inside the fishpig package. If the file wasn't found here it would then look inside the default theme inside the base package. If this file could not be found Magento would throw an exception saying it could not find the template file needed and execution would stop.

When trying to access view.phtml, Magento would access the following files until either the page was found or an exception was thrown.

• app/design/frontend/fishpig/fish-theme/catalog/template/product/view.phtml
• app/design/frontend/fishpig/default/catalog/template/product/view.phtml
• app/design/frontend/base/default/catalog/template/product/view.phtml

What the above basically means is that to create a new theme, you don't have to recode the whole of Magento!

We are now presented with two options:

1. Allow our theme to fall back to base/default
2. Copy over base/default files to fishpig/default and use that as our fall back

Both options are valid and each have their own advantages and disadvantages. For this tutorial, I will be leaving all of the core files in base/default and falling back to that. I will be doing this mainly because it will be easier and require less work from you at this point.

Skin folders

Just like the template and layout folders, the skin folders operate using base/default as a fall back. While templates can be vary similar cross-theme, CSS will most likely be entirely different. Because of this, the default CSS and JS are stored in default/default rather than base/default.

For this example I'm going to create a package called fishpig and a theme called fish-theme. Start by creating the following folders:

• app/design/frontend/fishpig
• app/design/frontend/fishpig/default
• app/design/frontend/fishpig/default/layout
• app/design/frontend/fishpig/default/template
• app/design/frontend/fishpig/fish-theme
• app/design/frontend/fishpig/fish-theme/layout
• app/design/frontend/fishpig/fish-theme/template

• skin/frontend/fishpig
• skin/frontend/fishpig/default
• skin/frontend/fishpig/fish-theme

Now that you have created the necessary folders, copy over the contents of skin/frontend/default/default to skin/frontend/fishpig/fish-theme.

Now that we have created a custom theme, it is time to enable it in Magento.

In my next post I will explain about the following things

1. How to Enabling our Package/Theme in Magento 1.4?
2. How to Creating a template file?
3. How Customising the default Magento theme?