Some best practices to manage templates with the magento template loading API

I presented you a few days ago an introduction on how are built the Magento pages. Now we we’ll see how the templates files are loaded since Magento 1.4 with the template loading API and how we can use this loading API to reduce our work with Magento.

Reminder: how are defined the templates path in a layout file?

Templates are defined in the layout files in a couple block / template with a relative path like this:


<block type="module_identifier/class_suffix" template="relative/path/to/template/file/in/the/template/design/subfolder.phtml"/>

For example, here’s the definition of the block / template that defines the search form field available in your catalog pages:

So, how does Magento find the full path for the relative path defined in this structure?

Magento template loading API available since Magento community edition 1.4 and above (Enterprise 1.7 and above)

Since Magento 1.4.x, when a page is requested, Magento analyzes all couples block / template that compose it. Afterthat, Magento will look for the full path of the template file in the following folders:

  • 1. app/design/%context%/%design%/%theme%/template
  • 2. app/design/%context%/%design%/default/template
  • 3. app/design/%context%/base/default/template

Magento takes the first file found and use it.

What happens if the file is not found? By default, if template file is not found in these folders:

  • No output is renderering
  • A trace in log will be written if log is enabled

This loading API explains why we can define easily some temporary themes for your site like for christmas, summer, sales…: after setting up a new theme, you must only update some elements in your template in a new theme template folder

This is this loading API which allow Magento to drive some merchandising design on your website

We will now see how we can work more efficiantly whis this loading template API

Some best practices when building a new Magento design and theme

Copy paste the default theme when building your package?

When looking for the template file in the folders mentionned before, Magento runs a file_exists. Even if copy paste is the devil, when you build your package, duplicate content will avoid many file_exists when rendering your page, so it could be interesting to duplicate the base/default theme

But one of the drawback of duplicate base/default content will appear during magento upgrade: you won’t benefit of the new templates design for templates you have not overloaded: after upgrading the magento source code: do you really want to check if all template have changed? Or keep your own one and do not use the new functionnalities?

Today, I haven’t seen any limit of the file_exists loading. There are many others points to check before this performance option to make magento faster…

New functionnality in Magento: in base/default !!!!

Another common workaround in Magento project is that we can hear that it’s strictly forbidden to write in the in base/default template folder. I never understood why: if you run in multiple stores model and have specific packages defined for each store, this is the only way you have to share templates between each store. In case we do not want to write in base/default, the only way that we have to share template is to copy paste it in each package/default theme… wonderfull 🙂

Furthermore, if you want to share your module in Magento connect, this is the only way you have to avoid requiring a post configuration by copying the embedded template files in the current package folder (modules should be installed through only one click)

How organize your new templates file in your theme?

When we define a new couple block / template, we provide a relative path to define the related template to load. As a best practice, I cluster all my templates in a subfolder like %namespace%/%module%

This best practice has the following advantages:

  • When you develop your module, this is quicker to find it in the directory tree
  • If you share your module in Magento connect, this reduce the risk that other modules will have already existing templates in directory tree

Be lazy when you work with Magento templates!

I’ve made hosting for one of the biggest french bank and I liked this work: check everything is ok or be able to solve problem quickly and easily with the tools you made. Magento loading API is able to help you to provide you quick answer and easily manageable way to customize the appareance of a Magento website

Sometimes I hear that for performance issues, some people overload the Magento template loading API. It’s a shame to avoid using this model because your client won’t be able to drive the website marketing design: model is quite fine and allows you to do what you want easily without too much work. There are really many thing to do before updating this API for performance issues