photo credit: Building Blocks via photopin (license)

How to keep your Magento themes organized

When is the last time you heard someone say: “Geez! Magento templates are really the bomb!”?
If you’re still letting that question sink in, don’t worry, you’re not the only one. Magento templates are known for their overwhelming complexity and ugliness. Once you get the grasp of how the templating system with the local.xml  and the many, many phtml -files work and how amazingly flexible it is, it still remains a very big soup of unstructured code, even for the Magento veterans under us. (And if you don’t believe it, just take a look at the template to render a single price block).
But don’t worry… There are some tricks that you as a Magento developer can do to make at least your templates a bit more… nicer to look at.

Keep it simple

It is actually a convention from Magento to keep the use of PHP logic in your templates as minimal as possible. It’s only too bad, that not much of Magentos’ core developers use these simple rules. But a simple rule of thumb is: “Someone with basic PHP skills should be able to write templates”. This means that you should limit the use of PHP-functions in your phtml -files to the following:

  • if: / else: / endif; if you need to make a simple check in order to do or don’t do stuff, use a simple if/then statement.
  • echo if you need to put something on the page.
  • Block-specific methods, like getChildHtml() , __()  and the many, many different magic getter methods that come with every block.
  • Write variables in templates with dollar-underscore ($_product , $_helper , etc).

I’ve seen many template file that have a lot more PHP-logic in them, I’ve even seen phtml -templates that output not a single character of HTML or that create complete ad-hoc SQL-queries. This is completely out of the question and it brings me to my next point:

No complex logic in your template

I said it before, but I’ll say it again: Someone with basic PHP skills should be able to write templates. Think about a team with a Magento frontend developer with basic Magento templating skills and a veteran Magento backend developer. You want to keep these two worlds separated (you must!). Business logic should never be processed in the presentation layer! So instead of doing something like this in your template:

Even though this might be considered simple, it makes your template ugly as can be. And not every basic PHP programmer knows how to use a switch-case. But more importantly: you’re handling business logic in your template here! A more proper solution would be to generate a helper in a custom module (you most likely need to create a custom module for every Magento shop you create anyway) and derive the business logic to there:

Even though this template might seem cumbersome, we derived the business logic to our helper so we don’t have to do the actual check in our template. This way of working is also very flexible and extensible in case attributes change or get added or deleted.

Define variables at the top

The previous example was very short, but in your days as a Magento developer you might have come across templates that look like this:

This example is completely nonsense of course, but it shows a pattern that many phtml-files share: defining global variables (variables that can be accessed from anywhere within the template) ad-hoc in the code. It is as if the developer thought: “Oh yeah, I need this variable as well, let’s define it right here, right now!”. When you’re writing your own templates, you can be organize your theme by defining these global scope variables at the top of your document:

Needless to say, this cannot be done in foreach() -loops of course, but if you take the ‘no complex logic’-advice of this article there aren’t much (if any) reasons why you shouldn’t define all your variables at the top of the document.

Use child templates in foreach()-loops

We handled foreach() -loops before, but another good practice in Magento is to embed a child template in your template file when it comes to foreach()-loops. This keeps your templates nice and separated and makes it easy to extend them by other plugins:

You might wonder why I use the whole $this->getLayout() -approach to create a block. This is because the getChildHtml() -method doesn’t accept parameters so we can’t pass our $_product  to our child block. If you want to use the getChildHtml() -method in conjunction with your local.xml  update, you could do something like this:

But of course, as we have learned in the ‘no complex logic’-part, it’s best to let our backend developer take care of this in a helper- or block method so we can keep our template lean and simple:

In conclusion

If you take these 4 tips in consideration when writing your templates, you’ll find yourself writing nicer templates, easier to read, to maintain and to upgrade. You might even get a performance gain although I expect that to be minimal.
If you have more tips on how you can keep your templates lean, mean and organized I’m always ready to listen. If you have a great tip or method how you deal with these situations please feel free to share them with is in the comments section below this article.

Visitors give this article an average rating of 5.0 out of 5.

How would you rate this article?

Leave a Reply