Best practice tips for Magento theme development

seasoned Magento consultants, one of the things we see often is poorly implemented Magento themes.

After running a Magento training course for web developers recently, a discussion with them lead to creating a list of best practices for Magento 1.x theme development.

So, here are a list of tips for newcomers to Magento and Magento theming:

1. Keep your text translatable

One of the many features of Magento is support for multilingual store fronts to cater for different languages your customers may speak. Badly built Magento themes can break this functionality, but it’s easy to maintain it in your own themes.

To ensure text used within your Magento templates can be translated, simply wrap it within the translate function:

<button><?php echo __('Click me'); ?></button>

Product descriptions and page contents are still controlled via the Magento administration panel.

2. Let Magento help you!

Magento’s templates are pretty extensive, and it can be hard to know which template you need to edit to change a specific block within Magento. Luckily, Magento has tools available for this! Log in to your store’s administration panel and navigate to:

System > Configuration > Developer > Template Path Hints

You will then need to change your Configuration Scope from the default scope to see the options to enable this tool. Once enabled, you should see your Magento theme is highlighted by red borders and boxes telling you which directories each template is being pulled from – knowing this makes them much easier to overwrite!

Magento theme development - Template path hints example

You can restrict this via IP address, so that only you are able to see these (though you shouldn’t use them on a production Magento website!).

3. Use Magento’s local.xml

When overwriting layout XML from a parent theme in your child Magento theme (Magento 1.9+), don’t overwrite an entire file: make the changes in your Magento theme’s local.xml file – e.g. /app/design/­frontend/your-custom-theme/­default/layout/­local.xml.

This means future updates to the parent theme are less likely to break your Magento theme, and that you’re only overwriting what you need to overwrite (see #5).

4. Never edit core Magento themes

If you want to make the use of a core Magento theme as your parent theme, that’s fine (many themes on Magento 1.9 are based on the rwd theme) – but never edit core Magento themes!

An update will likely overwrite core Magento themes in the future, and you’ll lose customisations you’ve made; make the changes in your custom child theme, and you will avoid this problem.

Plus, it upsets Ben Marks.

5. Only overwrite what you need

A very common mistake we see in Magento themes is that all of the base theme’s files are copied in to the child theme. This negates the benefits of using child themes, as when updates occur to the parent theme, unchanged templates are still being overwritten at the child theme level, potentially leaving a security hole behind or breaking functionality, and definitely creating more work for the Magento developer!

It’s best practice for your Magento theme to copy only the template and other files you specifically want to overwrite in to the child theme. For more information on parent/child themes in Magento 1, see this article by the brilliant Alan Storm.

Another great resource for other Magento tips is