Understanding Joomla 2.5 / 3 Template Positions

Article Audience: Webmasters / Joomla Newbies

New users of Joomla tend to find template module positions confusing and possibly frustrating. Joomla 3 has improved the way templates work to ensure this is less confusing, however, some users might still find it hard to add template positions to their templates. This article on CollectiveRay.com will attempt to clear the air about template module positions.

Module Positions

In the Joomla 3 Module Manager ( Extensions > Module Manager, you can assign your modules to a number of positions. The positions in Joomla 3 are defined per template. Thus the template positions problems is reduced, and responsibility is now with the template author to ensure that template positions defined in the template details file, actually exist in the template!

If you require additional template positions, you would need to change your template to cater for the additional positions you need. Obviously, this requires knowledge of PHP, HTML and XML in order not to break your template.

This is particularly important for you to know and understand, especially if you're planning to use a number of Joomla extensions such as the ones which we listed here.

Also note that you can usually add more than one module to the same position i.e. you can add more than one modules to your left and right positions, with the order in which they are displayed being determined by the Order parameter in the Module setup.

Also note that in some poorly written templates the module positions do not agree exactly with the name given to the position (e.g. user position shows up at the bottom). It is up to the author of the template and the Joomla webmaster to understand where the module will be rendered by testing different module positions, and if necessary changing the name in the template code. Please be sure that you always take backups and know exactly what you are doing before changing any template files.

The JDOC tag

So what determines where modules are rendered. The JDOC tag in the index.php file is replaced by the modules assigned to that position (via Extensions > Module Manager and assigning to a particular position) when the page is being rendered. So if we have

<jdoc:include type="modules" name="left" style="xhtml"/>

in the index.php file, and the Main Menu module is assigned to the left position, the Main Menu will be displayed instead of this tag. This applies to each jdoc tag defined in the index.php file. If I have a <jdoc:include type="modules" name="right" style="xhtml"/>, this will be replaced by the modules which are assigned to the right position.

Logical Position Names

The name attribute in the jdoc tag, is a logical name. It is entirely possible to define the bottom position in the top part of the module, though typically template designers define tag names which make sense, i.e. the left position would eventually be displayed in the left area of the page, and the banner position would be displayed just above the content and so on.

How do I know what Positions my Template supports?

Typically, with serious template designers they explain which module positions are available in the template. In Joomla 3, the responsibility remains with the designer to define the correct positions in the template details file. However, for free templates, one might not know which positions actually exist. So how do you go about discovering which positions are supported by the template?

It is quite simple to do this by enabling a small piece of functionality which few people are typically aware of. You can easily "Preview" what template positions you can use in your template. However, you need to enable the Template preview. Go to Extensions > Template Manager. Click on the Options icon at the top right corner and make sure the "Preview Module Positions" is enabled. At this point you can now see your template positions availableby adding ?tp=1 to your index.php e.g. www.yourdomain.com/index.php?tp=1 ... sweet isn't it?

You can also view directly which are the positions in the template files directly!

Simply open the template's index.php file, and search for the jdoc tag. Note the name of the places when the jdoc tag appears. I.e. if you find the following tags in the index.php file:

   <jdoc:include type="modules" name="top" style="xhtml" />


   <jdoc:include type="modules" name="left" style="xhtml" />


<jdoc:include type="modules" name="banner" style="xhtml" />


   <jdoc:include type="modules" name="right" style="xhtml" />

You can safely assume that the positions supported by your template are:

  • top
  • left
  • banner
  • right 

Adding Module Positions

In this section I will show briefly how to create an new module position in any template.

You first need to decide where you are going to place the position in your template (in terms of the template's HTML). You need to understand exactly how the tempalate works. For example we will be adding an adlinks position to my template (to insert Google AdSense adlinks code). We find the position (in the index.php) file where we want to add the adlinks and insert php / html code similar to the following:

<!-- BEGIN: adlinks -->

  <div id="adlinks">

   <div class="adlinks-class">
    <jdoc:include type="modules" name="adlinks" style="xhtml" />

  <!-- END: adlinks --> 

 We then need to create the Module Position in the Template Details file by creating a new adlinks position. Find the TemplateDetails.xml file enclosed with you template under /templates/<templatename>/templateDetails.xml

Find the <positions> tag in your XML file. It looks something like this:


templatepositionjoomla15.jpgTo add your own position, you need to insert a new <position> tag before the closing positions tag. The end result will be as follows:


Once this is done, we can now assign a module to the adlinks position in the Extensions > Module Manager page.



How to find positions for modules in your Joomla Template

Today a nice handy tip, straight from the horse's mouth (the Joomla community team). Sometimes, you need to know which are the positions currently being used by your template. You can do this either by checking out the Module Manager in the administrator, i.e. viewing the positions which have modules assigned to them, or else use this tip.

Enable Joomla tp=1

Joomla 2.5, Joomla 3

In Joomla 1.5, we used to just add tp=1 to the index.php url and we were able to view all the module positions on the frontend template. But on Joomla 1.6 and 2.5 and Joomla 3 you need to perform an additional step before Joomla tp=1 works correctly

In order to see the Module Positions on the template, here is what you have to do :

Goto :

Administrator > Template Manager > Options  > Templates Tab > Preview Module Positions .


Now you can type "index.php?tp=1" on your frontend and you can see all of your module positions.

So to view the module positions with Joomla tp=1 you will need to click to :


Joomla 1.5 

In Joomla there is a hidden core function which once activated displays a layer on a Joomla website which shows you exactly the template positions currently used.

To activate this function you just need to add ?tp=1 to the end of your current Joomla address. As an example take a look at the following link: https://www.collectiveray.com?tp=1 As you can see, you can know see all the positions which are template makes use of. You can use this on any Joomla version, on any Joomla site and on any Joomla page (though you might need to use &tp=1). The following parameters can be used: 

  • ?tp=1 (for horizontal view)
  • ?tp=-1 (for no wrapper niew)
  • ?tp=0 (for normal view - no view of positions)

And this is how to find your Joomla positions using joomla tp=1


Use Joomla Collapsible Template Positions to save space where necessary

Often when designing a Joomla website, you find that there are certain pages where you require certain modules, whilst other pages where these shouldn't be visible. This is easily done via Joomla's functionality of assigning modules to menu item links.

However, this brings about a new problem. The position in the template. How do you create a template which can collapse a module position which is currently not being used? This can be done by counting the number of modules currently assigned to this position by using a few Joomla function calls countModules or in older versions mosCountModules. An example of this is found below.

Joomla 2.5 / Joomla 3

<?php if ($this->countModules('user4')) : ?>
  <nav class="navigation" role="navigation">
    <div class="navbar pull-left">
      <a class="btn btn-navbar collapsed" data-toggle="collapse" data-target=".nav-collapse">
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    <div class="nav-collapse">
      <jdoc:include type="modules" name="user4" style="none" />
<?php endif; ?>

Joomla 1.5

<div id="usertoolswrap">
    <div id="usertools">
    <?php if (mosCountModules('user4')) {?>
        <div id="user4">
            <?php mosLoadModules ( 'user4', -1 ); ?>
   <?php } ?>

As we can see, in the code above the user4 position is only rendered when there are modules assigned to position user4. The count modules function allows us only to render the position when modules are assigned to it, and collapses the template position if there are no modules assigned.



So you want a good looking template? 

If you really want to look professional, stop searching for those free templates. Most of them look poor, are very limited in positions and flexibility, have bugs, and typically contain hidden links to the original designers. If you want your site to look great, go to the pros and get yourself a template from there. You won't be sorry, and the end result will definetely show. The first impression of a website is obviously from the template, and you really want to get the first impression right

Template Designers


Our template (JA Pollux) was bought from JoomlaArt club. The good thing about this club is that you can subscribe to buy a 3 month membership. During this time you can download and try as many templates as you like. Also, Joomlart claim that they release at least 1 new template each month.




About the Author
David Attard
David has been working in or around the online / digital industry for the last 18 years. He has vast experience in the software and web design industries and niches surrounding them. As a digital consultant, his focus is on helping businesses get a competitive advantage using a combination of their website and digital platforms available today.

One more thing... Did you know that people who share useful stuff like this post look AWESOME too? ;-)
Please leave a useful comment with your thoughts, then share this on your Facebook group(s) who would find this useful and let's reap the benefits together. Thank you for sharing and being nice!

Featured On

Inc Magazine Logo  

Sitepoint logo  

CSS Tricks logo   

webdesignerdepot logo   WPMU DEV logo   

and many more!



Get Started Now With ShutterstockShutterstock

Best Rated Caching Plugin

Make your website faster 

Monstrous B-Day Party

CLICK HERE for discounts!

Monstrous bday party

How to make your website FAST!

Step-by-step - free email course, how to make your website load in less than 1 second 


The Outstanding HungryJPEG Bundles

AWESOMENESS! Bundles of premium font + graphic packs at more than 96% OFF!  Get a bundle for just $9 - ONLY!

The Hungry JPEG Awesome font bundles


Work with CollectiveRay.com

CollectiveRay (formerly known as DART Creations) is interested in developing partnerships with mutual benefit. If you like the stuff we publish and would like to develop a relationship, we'd be happy to hear from you. Go on - drop us a line - we'd love to hear from you :-)


Disclosure: CollectiveRay is funded personally out of pure passion for helping people working with websites. We do however generate some income through recommendations of products. This means if you click on a link and purchase an item we link to, we will receive a small sum out of that sale. We usually partner with vendors to make your purchase cheaper than buying direct.


InMotion Hosting CollectiveRay Deal

who are we?

CollectiveRay is run by David Attard - working in and around the web design niche for more than 12 years, we provide actionable tips for people who work with and on websites. We also run DronesBuy.net - a website for drone hobbyists.

David attard

Follow us on Social

Follow us on Facebook   Subscribe to our RSS Feed   Follow us on Twitter


Where are we hosted?

This site is proudly powered by FAST VPS InMotion Servers and given an insane speed thanks to StackPath CDN!

Web Hosting stackpath


Popular Content

Joomla extensions to take your website to the NEXT level

Is your Joomla website reaching its full potential? We install many of these extensions on almost ALL of our Joomla sites - why don't you check them out our list of Joomla Extensions and see whether you can take your site to the next level?