This is part of a series on Magento Best Practices. Click here to read more.
Themes are used in Magento to customize the look and feel of your site. They are comprised of multiple files across the Magento application. They are organized and grouped by package and theme. In the scope of the MVC pattern, they are the “V” or view of the application.
Themes are part of the three component view inside of Magento. The three component view is the combination of layout xml, block classes, and template files. Themes handle layout xml and template files, (as well as skin files). We will cover each of these in more detail in subsequent articles. In this article, we will cover theming and structure best practices.
The principles you follow are:
- Don’t Edit Theme Files Directly
- Leverage Fallbacks Correctly
- Use Only Local Layout XML
- Only Override What You Change
- Don’t Collide With Skin Files
How Fallbacks Work
The fallback system in Magento is very powerful. It allows you to make customizations to a theme without having to duplicate any unchanged files.
The Magento fallback system looks for files in a series of locations. The fallback system looks in the following locations: your custom theme, a “soft” default, a “hard” default, then inside of the base/default package and theme, (in the scope of the frontend, of course).
First, Magento will look inside of your custom theme under the package you’ve defined inside of your admin panel. In the example below, it will look in rwd/custom first.
Next, it will look into what’s called a “soft” default. This is a configured default folder you specify in the admin panel. (It’s the default setting in the above image).
Next, it will look into a “hard” default. This is a folder specifically named default.
Finally, it will leave your package and look inside the base/default package and theme.
If it cannot find it, an error will trigger.
Don’t Edit Theme Files Directly
In the same vein as “don’t edit the core”, Magento allows you to leverage the fallback system in order to make changes to the theme files. If you edit theme files directly, you are now responsible for maintaining their upgrades. This would essentially break upgrade paths on your system.
As a general rule, don’t edit theme files if they are located in any folder named default. Create a custom theme and leverage the fallback system. This ensures a smooth upgrade path for not only the Magento core, but any custom themes purchased.
Below is an example of the areas you should not touch (as well as my expert Microsoft paint skills):
Leverage Fallbacks Correctly
The important thing to know about fallbacks is the moment Magento find the file, IT STOPS. This means it will not attempt to resolve the “best” file suited for the job, it will simply resolve the first. This means if you name any of your theme files the same name as any in your parent themes, it will find yours first. It will not load any of the others.
This means that if any file is found that is also considered a core file, it will return that one and not the one written by the core team.
There are many instances where this is perfectly ok. If you need to alter a template file, you should overwrite it with your changes, (instead of editing core ones, like mentioned above).
Instances where it is NOT ok is when speaking in reference to layout xml files. These files hold the instructions for the structure of a page. They are not merged with any sort of parent theme xml, so the first one found is the first one used. If you override an xml file, you are now responsible for it. This means you are freezing that layout file in place, so upgrades will break. If all you are doing is customizing layout xml of a particular section in your own custom theme, stay out of those files.
There are exceptions where overriding layout files is OK. Those are instances where you create your own package. If creating a package, you can override xml files. Just make sure to keep your package up to date!
Custom Themes Should Only Use a Local Layout File
So how do you make changes to layout without overriding xml files? When creating a custom theme, you can specify a layout xml file to hold the changes necessary for your theme. This file is called local.xml and is located under the layout directory in your theme. It is the last file merged and therefore the last set of instructions to parse for a theme.
This should be the only file from inside your layout folder. All other layout files should use the fallback system to find their appropriate files.
Only Override What You Change
A common practice I see when working with clients is that they copy over every file from other themes when creating a custom theme. This is not necessary and now you are responsible for maintaining all the upgrades.
Instead of doing this, only override the files you actually change. This way, all the other files will leverage the fallback and you can maintain easier upgradeability. Normally, in a typical custom theme, there should be only around 10-20 changed files. This is much easier to maintain instead of hundreds of files every time an upgrade is needed.
Below is an example of a custom theme inside the rwd package. It only changes a few template files, adds a local.xml file, and lets everything else fallback to rwd/default.
Don’t Collide With Skin Files
Skin files also follow the same fallback system. Due to this, the same rule applies as with layout xml files. Do not name any sort of skin file, (such as css styles) as the same name as ones in your default folders. Add custom css with your own file and add it via the local.xml layout file.
Now, with these practices, your themes will be lightweight, easy to maintain, and super simple to upgrade. Happy theming!