Creating a Magento theme from scratch

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:
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
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
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.
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
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:
- app/design/frontend/MyPackage/MyTheme/template/page/1column.phtml
- app/design/frontend/MyPackage/default/template/page/1column.phtml
- 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 regarding Magento development, feel free to get in touch – we would be happy to assess your site and get you on the right track with our Magento Technical Audit.
Thanks for reading. 🙂
19 comments
thanks for the information
really helpful for beginners
It’s a great article. Found it helpful.
Would like to suggest another way of creating responsive Magento theme using theme builder software like TemplateToaster, a tool allowing you to work with other major CMSs also. I use it and it’s a hands down tool both for beginners and experts.
in this scheme as our new custom theme should have the files which only needed to be edited and rest of the files will magento fallback system will call, by this fallback overhead included by magento and site performance will be low or remain the same as all the files of our theme should have in which some are edited according to custom need and rest of all just files just duplicate from base/default package just avoid magento fallback overhead just for site performance. Please clear my point with reason as i’m struck in this confusion.
Nice guide. Also please provide a demo theme, and add guidelines to customize the theme, it will help freshers for hands on practice on Magento. Thanks and regards
Hello Sir thanks for useful tutorial but i need next tutorial please provide me the link.
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!
I am newbie to Magento, which is used as backbone to manage our e-commerce site. but this article has helped me lot in understanding Conventions of the framework. Thanks keep going.
where’s the next tutorial?? its just the starting please write further articles. Thanks in advance
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
> 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.
I simply mean can you add info on the use of a theme.xml file? 🙂
Can you add info on a child/parent theme setup?
I’ve been reading guidance in the use of a theme.xml configuration file.
This is a good article:
http://www.coderblog.de/magento-1-9-infinite-theme-inheritance-hickups/
Great tutorial, I have already made a start on creating a new theme for our website from scratch – keep up the good work
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
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 🙂
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 🙂
This article is very easy to learn. Thanks to give us this easy article.
Woohoo! Congratulations Nenad on your first article. You set a promise today. Let’s check in 7 months:
