Create A Custom Theme in Magento

Since Magento 1.3.2.4, there are have been significant improvements to the Magento template system. While these improvements make creating templates much more efficient, developers are struggling to understand the changes and therefore, to create new themes. Rather than explaining these changes one by one, I will go through each step to creating a theme and discuss each point as it arises.

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!

To summarise, a package contains 1 or more themes. The themes the package contains should be similar and if they are not, they should be separated into separate packages. Online, people talk about creating Magento themes, but what they actually mean is creating a Magento package - it just doesn't sound as good!

The Directory Structure in Magento 1.4

Now that we understand themes and packages, let's look at the new 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.

What about the 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.

Enough talk, let's create our directory structure!

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.

Enabling our Package/Theme in Magento 1.4

To enable your new theme, login to your Magento admin section and go to System > Configuration > Design. When the page has loaded, notice that the first 2 sections of the page are titled Package and Themes. In the top section, set your package as fishpig and in the second section, set all input boxes (except the 1 titled Default) to be fish-theme. Once you have done this, save the page and refresh the Magento cache.

It should be pointed out, that if you ever encounter any problems with your custom theme, you can always switch back to the default theme by emptying the input boxes under Packages and Themes in the Magento configuration.

Now that our new theme is being used by Magento, let's add some code and test whether or not it has worked.

Creating a template file

Earlier on we used the example of the product view template (catalog/product/view.phtml), so let us continue with this example. Using your favourite FTP program (Transmit <3), create the following files/folders:

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

Although view.phtml is empty, you have successfully created your first template file. Open your browser and browse to a product page in Magento. You should notice that the content section of the page is now totally empty. Can you think why this is?

To understand what has just happened, let's discuss fall back again. So you don't have to scroll up, I've included the file locations Magento checks for view.phtml before it throws an exception.

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

Before we created view.phtml in fish-theme, Magento would check each location until it finally found the file in the base/default theme; no exception would be thrown and the product page would be displayed successfully. Now though, we have created view.phtml in the first place that Magento looks. Now that Magento has found the file, it stops checking the other directories and parses and renders the content inside our custom template!

Adding code to the template file

So far we have a custom template file, however, we don't have any code in it! To prove that this is working, let's add some code.

<?php $_product = $this->getProduct() ?>
<h2><?php echo $_product->getName() ?></h2>

The above code is simple but should prove that your custom theme is working and is successfully over riding core template files.

Customising the default Magento theme

So far what we have done has been more of a learning exercise. Now let us look how to make some useful changes to the default template, before finally learning how to build a totally custom theme.

In this example, rather than re-code view.phtml, we will copy across the default contents and modify them slightly. To do this, copy the contents from base/default/catalog/product/view.phtml to the custom view.phtml you have created. Save this file and reload the product page. You should notice that product page has returned to it's original state. You can now modify any of this code to customise the product page as you wish. You can do this knowing that you haven't modified any core template files and if needs be, you can always revert back to the old files knowing no damage has been done. This can be done for ANY template file in Magento and not just your product page.

The beauty of this system is that you can create a great looking theme without having to write a lot of code. Using the base/default files, some customisations in your own theme folder and some pretty CSS, it possible to create great looking themes in a matter of hours.

Creating a totally custom theme in Magento 1.4

The above examples have shown us how to create themes based on the default theme. For a lot of developers, this is more than useful, however, sometimes pure customisation is the only thing that will satisfy a client. To create a totally custom theme, simply follow the above steps. The only difference is that with a totally customised theme, the majority of files wouldn't fall back to base/default and would instead, exist in your theme folder. A great way to ensure that your theme doesn't fall back to base/default is to copy the contents of base/default to fishpig/default. If you do this and a file isn't present in fishpig/fish-theme, Magento will fall back to fishpig/default. The benefit of this is that you can modify the files in fishpig/default without worrying about breaking any other themes or having to modify core code!

Conclusion

Hopefully this article will help developers to start creating their own custom themes. If there are any bits of this article that aren't clear, please let me know and I will do my best to clarify.

20 thoughts on “Create A Custom Theme in Magento”

  • Roberto XSM

    Well done! This is the articole that i've been looking for the last week!

    Reply
  • Roberto XSM

    I want to report an error in your tutorial. These paths to catalog directory
    * app/design/frontend/fishpig/fish-theme/catalog
    * app/design/frontend/fishpig/fish-theme/catalog/product
    * app/design/frontend/fishpig/fish-theme/catalog/product/view.phtml
    are wrong.

    They are:
    * app/design/frontend/fishpig/fish-theme/template/catalog
    * app/design/frontend/fishpig/fish-theme/template/catalog/product
    * app/design/frontend/fishpig/fish-theme/template/catalog/product/view.phtml

    And it's the same when you speak about fallback. Hope you don't hate me for correcting!

    Reply
  • BT

    Hi Roberto,

    Thanks for the corrections! I will make the changes to the article now.

    Thanks again buddy

    Reply
  • giovanni

    thank you very much! I really appreciated your post

    Reply
  • Bubu

    Very great ! Thank you fishpig

    Reply
  • Alcides

    thanks for this one!
    though in my testing environment the whole fallback system doesn't seem to work...
    After the step of enabling the new package/theme I get an unstyled frontpage as well.
    Where can I start with troubleshooting my problem.

    Reply
  • Mike

    Hi there - thanks for this very clear article. I am trying to understand the best approach to building a new theme, and it seems there is basically this approach, or another method involving local.xml to hold instructions about how to modify the base theme (documented here: http://www.magentocommerce.com/wiki/4_-_themes_and_template_customization/0_-_theming_in_magento/designing-for-magento#understanding_layout_xml_files)

    Am I missing the point or are there two different schools of thought? Is there a preferred approach? Are there pros and cons?

    Thanks for helping to move this forward!

    Mike

    Reply
  • Ashraful Abedein

    This is simple and very nice tutorial for beginner like, I found your article is better then the main mage site. I want to know about layout files, where to ... help

    Reply
  • Bas

    First of all i want to thank you for this article. It's very clear!

    I do run into a problem tho. My default language store view English keeps falling back to the base templates.

    The other language store views use the correct templates from my new theme. You have any idea what's the problem here?

    Reply
  • oliyide

    This is simply awesome. I have not seen a magento tutorial as straight forward as this to talk less of addresseing magento 1.4 .. Thanks man.

    Reply
  • Amel

    After many hours of search! I found this article, it's simple and clear. Thanks.

    Reply
  • Amel

    Hi all,
    I need to setup a purchase form.
    Any body knows how we can create forms in Magento?

    Thanks.

    Reply
  • Anthony

    Just spent an hour following this lesson. My first intro into Magento. Very well structure lesson, i feel i have a good understanding how it all fits together. Nice work.

    Reply
  • Alex

    Same as everyone else, Thank you very much. Very clear explanation of the folder structures and the overrides!

    Peace.

    Reply
  • Mayank Sharma

    This is very good article but it seems to be incomplete. It would be great if you can also explain us about 'Layout' folder, how to/where to upload images and css, I guess skin folder? etc....

    Reply
  • Ian Gallimore
    Ian Gallimore May 17, 2011 at 5:02 pm

    Hi Ben,

    How's it going?

    I may be wrong here but from reading the Magento designer's guide (page 19 & 20) isnt this approach whereby you have a package (i.e directory) called 'fishpig' with a theme (sub directory) called 'fishpig_theme' only applicable to the professional and enterprise editions?
    I was playing around with creating themes this morning and managed to get the normal way to work (i.e when you put your new theme directly under the 'default' directory) but just couldnt get this package/theme version to work - well certainly not the local.xml part...
    I could be wrong and the designers guide could be confusing me, but....if I'm not then you've been spoilt with your Dev box! :)

    Cheers,
    Ian

    Reply
  • Dhanapal

    Hi very very thank you for your valuable tutorial to create the template. This reduce the more time to study to create magento template. Hereafter you are a good teacher for me in magento. With your help i starting to develop/customize the magento theme

    Reply
  • Aruna

    This article is very helpful and simple!! Thanks for the article

    Reply
  • wazid

    thanks for your great tutorial. I am newer in a mgento and this content is very useful. Thanks again

    Reply
  • Gavin Wun

    Awesome stuff, well explained to get me started on adding new theme to Magento :) Thanks!

    Reply
Leave a Reply
Post your comment

FishPig Ltd