1. Code
  2. Web Development

Magento Theme Development: Template Files

This post is part of a series called Magento Theme Development.
Magento Theme Development: Layout Files

In this article, we will be covering the basics of Magento template files. We will go over their introduction and do some basic modifications. 

This will include displaying featured products on the homepage and how to load JavaScript in the footer.

Following on from our previous article, we have seen that the layout files control each block in a theme and decide what does and doesn't get displayed. But what gets rendered inside of that block is where the template files come into action.

In this article, we will be focusing on the following directories:

  • Template - app/design/frontend/<package_name>/<theme_name>/template/
  • Locale - app/design/frontend/<package_name>/<theme_name>/locale/

If you've just joined us please be sure to checkout the previous articles in this series.

For reference, we've covered:

  1. An Introduction
  2. Layout Files

Without further a do, let's get started.


Magento template files are PHTML files made up of a mixture of HTML and PHP, some of which render a page such as 1column.phtml while others render specific blocks within a page such as header.phtml

For the majority of the time during development of a website these are the files we'll mostly be working with, for front end developers, that is. Once the XML is in place and a template gets called, it is expected that the file will be parsed and displayed accordingly.

There are hundreds of template files available, knowing which one to edit and then track down the file in the hierarchy can be tricky when first starting out. 

All is well though, there are a few neat admin area settings which can help us out, they will save us hours of headache!

Important to note, we can only use the following settings at the "Website" or "Store View" scope, the settings aren't available to us on the "Default Config" scope, so we must remember to change the scope once logged in. This is useful though as it means we can toggle the settings just for a particular website or store view rather than globally.

Template Hints

These will quickly identify which files are being loaded for a specific page by showing us the path to the file. Toggling it on or off is a quick setting change in the admin area. 

Head over to system > configuration. Then in the left hand menu scroll all the way down to the bottom and click "Developer" from under the "Advanced" heading. Once we have changed the scope to "Main Website" we then have the setting available to us under "Debug".

It would appear that nothing has happened once you've clicked save config, but if you go to the front end of the website, the homepage for example, and refresh the page you will see the hints coming through. 

With this we now know where the files are located, and if any modifications are required simply copy the file across from base to our theme and modify as necessary.

We can also set "Add Block Name to Hints" to "Yes" if we want further information, this is generally used for back end development so I wouldn't worry about this setting too much.

Now, on to the code. I will run through a couple of modifications which are often used in theme development, but again I will only be touching the surface on whats possible.

  1. Displaying featured products on the homepage
  2. Loading JavaScript in the Footer

Let's get started...

1. Displaying Featured Products on the Homepage

This point has to be the most common request on any website, everyone wants to show off a handful of products on the landing page of their site right?

It's actually much easier than you'd imagine, with a combination of XML and PHP we can achieve this in no time. There are, as with many things in Magento, more than one way of doing this. I'm going to show you what I think is the easiest method.

First up, we need to create our category in the admin area that will hold our products. Once logged in head over to catalog > manage categories. For this example, we will create a subcategory under root, so we need to click on "Root Catalog" and then click on the "Add Subcategory" button. Enter a title for the category, make sure "Is Active" is set to "Yes" and then click "Save Category".

Make a note of the category ID number at the top as we will be needing this later on:

This will be a good time to also add some products to the category we have just created. To do this click on the "Category Products" tab and select the products you want to display, not forgetting to click "Save Category" once we have finished.

Next up, we need to create our template where our foreach loop will be run.

For this we will base it off the product list template which has all the necessary code already done for us, we just need to make a few adjustments to suit our needs.


Copy to:


We will then make some modifications to our file.

  1. Load in our product collection via the category ID
  2. Only display one view, I have picked the grid view but feel free to change this
  3. Remove the toolbar as this is no longer needed
  4. Add in our category name for a heading

The finished file will look like the following:

Don't forget to change the value of the $_categoryId variable to your category ID.

Lastly we just need to create an XML block that will load in the template we have created above. We will do this in our local.xml file like so:

That's all there is to it, pretty straight forward right? Below is a screenshot of the finished product.

2. Loading JavaScript in the Footer

For starters, we would think Magento already has this ability built in through the XML when we add our scripts, some sort of parameter we could pass in, but we would be wrong - Magento isn't going to make it that easy for us!

WordPress, on the other hand, does this perfectly via the wp_register_script. Maybe a back end developer will pick up on this and add in the ability to pass through an additional XML parameter, now there's a side project for someone to get cracking with. 

Any takers?

So, fortunately for now there is an alternative method to getting this to work.

I think it's important to cover this topic as it will improve the speed of our site which everyone wants. I tend to leave Magento core JavaScript files left as they are in the <head>, I may minify them but apart from that they remain as they are.

Anything we add in on top of Magento, such as jQuery and our own custom functions there is no harm in loading these in the footer. When developing a website I tend to keep a keen eye on the <head> tag, when a third party module gets installed it usually adds something in here. With a bit of work we can edit the third party module XML and point it to load in the footer - it's well worth the extra five minutes doing so!

First we need to create an XML block in our local.xml file within the default layout handle like so:

Notice we are using the same method of adding JavaScript files as we did in the previous article. If you need a refresher click here, for demonstration purposes we will add in a local copy of jQuery.

Now we can go about creating our template file. Create a new file in:


with the following content:

Lastly we need to add a single line of code into our template files just before the closing </body> tag.

Our template files can be found at app/design/frontend/base/default/page/ not forgetting to copy them over to our own theme. There are multiple template files, I have collated a list together below:

  • 1column.phtml
  • 2columns-left.phtml
  • 2columns-right.phtml
  • 3columns.phtml

Below is an example of how it should look:

With all the steps now complete if we refresh our page and view source we will now see the script being loaded in just before the closing </body> tag.

If you've made it this far I think a congratulations is in order! There is a lot to take in one sitting but hopefully it's all starting to make sense.

Wrapping It Up!

This series is only the tip of the iceberg, Magento is a very powerful platform and has much more to offer than what we have covered. I hope it has given you an insight into the theme principles of Magento and that you can put it to good use.

There's no better way to learn Magento but to just get stuck in, you'll learn the ropes in no time.

As always I'm more than happy to assist if you need a hand with anything. Also be sure to checkout my Magento Boilerplate which has a whole bunch of goodies inside.

Until next time.

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.