Creating a Magento theme from scratch

creatingmagentotheme

Powerful fallback system, organized folder structure and tons of functionality is what makes Magento one of the most flexible and powerful eCommerce platforms out there. By default, Magento offers a lot, but as eCommerce evolved during the years, there is always additional work required to fit client needs.

Probably the first thing you will do when starting a new Magento project will be to create a Magento theme that will have custom styling and functionality. Although creating a Magento theme is a pretty simple thing to do (just ask any certified frontend developer), by not following Magento recommendations and rules you can easily make your life a bit complicated.

So, how to do it properly? Read on…

If you are new to Magento, be sure to read Magento Designer’s Guide, where the Magento design terminology is explained in a PDF document.

Magento Theme fundamentals

Magento themes are placed in design packages. Each package can have multiple themes.

When You install Magento, there are 3 packages available:

1-creating-magento-theme

In Base package, there is a “Default” Magento theme with all the files necessary for Magento to work properly. You should NEVER delete or edit files in “Base” package. I will explain why later.

Default package is legacy from < 1.4CE where it was the original base package. This package can be found only in CE edition of Magento, not in EE. You can safely remove that package from your installation. However, it may be restored during a Magento upgrade.

RWD is a new package which holds a new responsive Magento theme.

Magento has two main folders which correspond with each other:
“app” directory contains files that control how page templates are rendered.
“skin” directory contains files that control the site’s appearance.

  • Template files
    app/design/frontend/package/theme

2-creating-magento-theme

Layout folder contains XML files which are used to define and control structural and content blocks of your theme.

Template folder contains .phtml files – they hold the markup for each Magento blocks that are being displayed in the frontend.

  • Skin files
    app/skin/frontend/package/theme

3-creating-magento-theme

Skin folder contains all of your assets such as CSS, images, js, Sass etc.

NOTE: Package and theme names should be the same in both design and skin folders.

For example:
app/design/frontend/MyPackage/MyTheme
app/skin/frontend/MyPackage/MyTheme

Creating your theme

First, you need to create a new design package, in both “design” and “skin” folders.

Let’s call it “MyPackage”.

In your design package, create a new folder which will hold your theme. Let’s call it “MyTheme”.

Create two new folders in your theme folder – “layout” and “template”.

In the skin folder, open your theme folder and create folders – css, js, images.

5-creating-magento-theme    4-creating-magento-theme

Next, you should create “local.xml” and place it in “layout” folder.

That’s all you need!

Working with the theme

Next step would be to tell Magento which package and theme will be used as default.

To do this, go to
system > configuration > design

6-creating-magento-theme

First, we need to tell Magento which package we will use. We are using “MyPackage” design package.

As you can see, we can use assets from multiple themes. Templates can be called from one theme, skin files from another. Yet another cool thing about Magento and its fallback system which will be explained in the next paragraph.

Now, insert your theme name in all fields except “default” field – leave that blank.

Et voilà! Your theme is all set and ready.

You are probably eager to start with theme styling and editing. Since you don’t have any files in your folders, you are probably asking yourself “what now?” Now we will talk about Magento’s fallback system and then you will be ready to start with work. 🙂

Magento fallback system

The fallback system in Magento is very powerful. It allows you to edit your theme without duplicating unchanged files.

So, how does the fallback system work?

Like any other modern framework, Magento consists of many small blocks which are rendered and combined before they are outputted to one html file which is served to client.

If some of those files are missing, you will probably get a render error and the site will be broken.

Basically, what Magento does is this:

it looks for specific file in your theme folder

  • if found – outputs it
  • if not found, it searches for “default” theme in custom design package
  • if “default” theme exists in a custom package, it searches for the file there
  • if “default” theme does not exist in a custom package or file is not found in “default theme”, it fallbacks to “base” package and searches for file in “default” theme
  • if file is not found, Magento outputs rendering error

For example, when 1column.phtml is required, this is where Magento will look for it:

  1. app/design/frontend/MyPackage/MyTheme/template/page/1column.phtml
  2. app/design/frontend/MyPackage/default/template/page/1column.phtml
  3. app/design/frontend/base/default/template/page/1column.phtml

Now that you know how fallback system works, you understand why you should never edit or delete files in “base” package. If you delete some file by accident, Magento has nowhere to fallback and will generate a rendering error. Also, during a Magento upgrade, “base” package can be overwritten, therefore your changes would be lost.

3 rules to rule them all

To sum up, try to stick with these 3 simple rules and your Magento career will be less painful.

  • You should always create your own Design package and the theme inside it.
  • Duplicate files from base/default but only the ones that will be edited.
  • Your theme should hold only the files that were changed. Magento will fallback and look for the rest of the files in base/default theme.

I hope that article was useful to some of you. If you have any questions, post them in the comments section below.

Thanks for reading. 🙂


About Nenad Andrakovic

Team leader/Frontend Developer

Nenad works at Inchoo as Frontend Developer. He trained kick boxing recreationally and enjoys combat sports and martial arts.

Read more posts by Nenad / Visit Nenad's profile

14 comments

  1. I followed your tutorial but after creating local.xml, my frontend is not loading css file and thus things are breaking.. Can you suggest why!

  2. Hi,
    I think the path made some confusion ie the second path not exists.

    Given :
    “NOTE: Package and theme names should be the same in both design and skin folders.
    For example:
    app/design/frontend/MyPackage/MyTheme
    app/skin/frontend/MyPackage/MyTheme ”

    correct is :
    “NOTE: Package and theme names should be the same in both design and skin folders.
    For example:
    app/design/frontend/MyPackage/MyTheme
    skin/frontend/MyPackage/MyTheme ”

    Good Luck

  3. > Now, insert your theme name in all fields except “default” field – leave that blank.

    Why would you recommend this? Moreover, why would you recommend this given that you’re applying the same theme variation to every other input? The whole purpose of the “Default” input is so that all the others will use that single theme variation. Should you want, for example, to use another theme variation’s skin, you would then, AND ONLY THEN, define one of those other inputs, like skin.

    Page 22 of Magento’s official “Designer’s Guide to Magento” explicitly states this.

  4. I am working on multi store magento setup. I want separate 1column.phtml file for each store.I used fallback mechanism.
    I made the folder as per mechanism but it is not working.Please have a look may be i misunderstood something.
    My folder structure is:-
    app/design/frontend/stores/store1/template/page/1column.phtml

    stores is my package
    store1 is my theme

    Next, i created “local.xml” and place it in “layout” folder.

    And i set Current Package Name = stores and Templates = store1

  5. Thanks for the guide.

    For those of us that would like a Magento site with all the modern functionality commonly expected (AJAX, responsive etc), we’re left with the option of either expanding on rwd with cusomisations and extensions, or buying a ready made theme from a theme site. Building a theme from scratch is just unrealistic and not at all cost effective compared to the above two options.

    With that in mind, I’d like to ask how you normally approach client’s sites? Do you customise from rwd, do you choose an appropriate ready made theme and cusomise from there, or do you build from scratch?

    Thanks 🙂

    1. In two of the project i have accomplished, first one was i purchased premium theme that somehow matches to client’s need and for the second one i customized rwd/default theme. 🙂 And now i’m planning to build a new theme but building from scratch looks much work, like you said it’s not cost effective, if it’s for a single client.

      Good day 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <blockquote cite=""> <code> <del datetime=""> <em> <s> <strike> <strong>. You may use following syntax for source code: <pre><code>$current = "Inchoo";</code></pre>.