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:
- Allow our theme to fall back to base/default
- 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.
Below you should see a screenshot of how to correctly setup your custom package and custom theme in Magento.
Enabling Your Custom Package and Custom Theme in Magento 1.4
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.
|
1
2
|
<?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.
