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" />
   </div>   

 </div>
  <!-- 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:

<positions>
      <position>left</position>
      <position>right</position>
      <position>top</position>
      <position>banner</position>
      <position>header</position>
      <position>footer</position>
      <position>pathway</position>
      <position>user1</position>
      <position>user2</position>
      <position>user3</position>
      <position>user4</position>
      <position>user5</position>
      <position>inset</position>
      <position>debug</position>
      <position>search</position>
      <position>debug</position>
</positions>

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:

<positions>
      <position>left</position>
      <position>right</position>
      <position>top</position>
      <position>banner</position>
      <position>header</position>
      <position>footer</position>
      <position>pathway</position>
      <position>user1</position>
      <position>user2</position>
      <position>user3</position>
      <position>user4</position>
      <position>user5</position>
      <position>inset</position>
      <position>debug</position>
      <position>search</position>
      <position>debug</position>
      <position>adlinks</position>
</positions>  

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

Detailed Instructions to Create a Template Position

 

Creating a new template position in a Joomla! Template is something that many people will need to do some time or other. The specific requirement of a website will probably require to create a new position or alter any existing ones.

 This isn't something very complicated as long as you perform the right steps as defined below.

How to create a new module position

1) Where Do You Want Your New Position?

Naturally, the FIRST STEP in the process is to figure out and decide where you want to position your new module. For this, it is helpful to see a map/schematic of how the current modules are laid out/positioned within the template. 

Template creators typically create Module Position Guides for each template thus you can most quickly find each Template’s Module Position Guide by going to the respective template’s information page and clicking on the “Position Guide” button for the particular template version you want to view.

However, there are times when one wants to view a particular template’s module positions, and a convenient template module map is not readily provided. So, this little trick is handy so that you don’t have to play the guessing game. So, for example, if you wanted to find out what are the module positions for your template, here is how to do it:

1. Login to your Joomla Administrator backend.
2. Open your Template Manager and, on the right-hand side, click “Options‘”
3. Under the Template Tab >> Global configurations for Templates >> set ‘Preview Module Positions’ to “Enabled”
4. SAVE the changes you’ve just made.
5. Within your browser address bar, you can now append your site url with “?tp=” - for example, https://www.yourdomain.com/?tp=1.

After you press <enter>, you should see the template module positions. To turn off the template module positions you can follow through the same path and under the Template Manager >> Options >> Template Tab >> Global Configurations for Templates and set ‘Preview Module Positions’ to “Disabled”.

TIP:
For Joomla 1.5 based templates, you can see template module positions easily by just typing ?tp=1 following the URL path. For example – https://www.domainname.com/?tp=1 will enable you to see all the template module positions of your active template.

2) Which Layout Block for New Position?

Once you have decided where you want to position your new module, you then need to figure out within which layout-block file to add the necessary PHP code for your new position. 

NOTE: Blocks are files to hold module positions, perform specific script calls and prepare the HTML generation of the content. As you know, the most popular elements: header, footer, left, right, spotlights, pathway, etc. these are now separate files, no longer HTML elements defined in the index.php file.

For the purpose of this tutorial, I am going to add a new module position within the HEADER section of a template between the logo and the right banner . . . though the basic principles and steps can apply to create a new module position most anywhere within the template blocks structure.  We will be using Joomlart's Telive IV  template as an example


module1

Okay, so since we’ve decided that we want to position our new module within our template’s HEADER section, we need to locate and open the appropriate layout file for this section. For our example, we will need to work with the header.php file, which is located within the following file path:

\templates\ja_teline_iv\blocks\header.php

In its base/core form, the Teline IV header.php file looks like this:

PHP Code:

<?php
/*
 * ------------------------------------------------------------------------
 * JA Teline IV Template for Joomla 2.5
 * ------------------------------------------------------------------------
 * Copyright (C) 2004-2011 J.O.O.M Solutions Co., Ltd. All Rights Reserved.
 * @license - Copyrighted Commercial Software
 * Author: J.O.O.M Solutions Co., Ltd
* This file may not be redistributed in whole or significant part.
 * ------------------------------------------------------------------------
*/
// no direct access
defined '_JEXEC' ) or die ( 'Restricted access' ); 
 
?>
            <?php
            $app 
= & JFactory::getApplication();
            
$siteName $app->getCfg('sitename');
            if (
$this->getParam('logoType''image')=='image'): ?>
            <h1 class="logo">
                        <a href="index.php" title="<?php echo $siteName?>"><span><?php echo $siteName?></span></a>
            </h1>
            <?php else:
            
$logoText = (trim($this->getParam('logoText'))=='') ? $siteName JText::_(trim($this->getParam('logoText')));
            
$sloganText JText::_(trim($this->getParam('sloganText'))); ?>
            <div class="logo-text">
                        <h1><a href="index.php" title="<?php echo $siteName?>"><span><?php echo $logoText?></span></a></h1>
                        <p class="site-slogan"><span><?php echo $sloganText;?></span></p>
            </div>
           
            <?php endif; ?>
           
            <div class="ja-header-r">
                        <jdoc:include type="modules" name="header-r" />

            </div>


As I mentioned above, I want to place my new module position between the logo and the right banner image. As you can see from above, there is already a position called "header-r" within the header.php file structure. So, since I will want my new module position in the middle, I will call the new position "header-m"

The modified header.php file will now look like this . . . 

 * ------------------------------------------------------------------------
 * JA Teline IV Template for Joomla 2.5
 * ------------------------------------------------------------------------
 * Copyright (C) 2004-2011 J.O.O.M Solutions Co., Ltd. All Rights Reserved.
 * @license - Copyrighted Commercial Software
 * Author: J.O.O.M Solutions Co., Ltd
* This file may not be redistributed in whole or significant part.
 * ------------------------------------------------------------------------
*/
// no direct access
defined '_JEXEC' ) or die ( 'Restricted access' ); 
 
?>
           
            <?php
            $app 
= & JFactory::getApplication();
            
$siteName $app->getCfg('sitename');
            if (
$this->getParam('logoType''image')=='image'): ?>
            <h1 class="logo">
                        <a href="index.php" title="<?php echo $siteName?>"><span><?php echo $siteName?></span></a>
            </h1>
            <?php else:
            
$logoText = (trim($this->getParam('logoText'))=='') ? $siteName JText::_(trim($this->getParam('logoText')));
            
$sloganText JText::_(trim($this->getParam('sloganText'))); ?>
            <div class="logo-text">
                        <h1><a href="index.php" title="<?php echo $siteName?>"><span><?php echo $logoText?></span></a></h1>
                        <p class="site-slogan"><span><?php echo $sloganText;?></span></p>
            </div>
           
            <?php endif; ?>
            <div class="ja-header-m">
                        <jdoc:include type="modules" name="header-m" />
            </div>
           
            <div class="ja-header-r">
                        <jdoc:include type="modules" name="header-r" />

Basically, all I did was copy-and-paste the code for the "header-r" position, and then modified it as needed - pretty simple, right? This same concept can apply to add/duplicating other module positions within other parts of your site - but you do need to make sure you are modifying the new position code sufficiently so all relative elements reflect the new position you are creating.

4) Adding New Position to templateDetails.xml

We now need to add our new position to our TemplateDetails.xml file, which can usually be found along the following path:

\templates\ja_purity_ii\templateDetails.xml

About halfway down the file (at about line 58), you will see the template position listing:

https://www.joomlart.com/forums/ja-tpl/images/misc/quote-left.png'); background-color: transparent; display: block; width: 9px; height: 13px; position: absolute; left: -9px; padding: 0px; margin: 0px; background-position: 0% 50%; background-repeat: no-repeat no-repeat;"> 
<positions>
<position>hornav</position>
<position>breadcrumbs</position>
<position>search</position>
<position>banner</position>
<position>left</position>
<position>right</position>
<position>right1</position>  
<position>right2</position>
<position>top</position>
<position>headlines</position>
<position>header-r</position>
<position>mega</position>
<position>mega-adv1</position>
<position>mega-item</position>
<position>mega1</position>
<position>mega2</position>
<position>mega5</position>
<position>mega6</position>
<position>mega3</position>
<position>mega4</position>
<position>user1</position>
<position>user2</position>
<position>user3</position>
<position>user4</position>
<position>user5</position>
<position>user6</position>
<position>user7</position>
<position>user8</position>
<position>user9</position>
<position>user10</position>
<position>user11</position>
<position>user12</position>
<position>content-mass-bot</position>
<position>col-mass-bot</position>
<position>col-mass-top</position>
<position>col-mass1</position>
<position>col-mass1</position>
<position>ja-news-1</position>
<position>ja-news-2</position>
<position>ja-news-3</position>
<position>ja-news-mobile</position>
<position>sl1-l</position>
<position>sl1-r</position> 
<position>ja-tabs1</position>
<position>ja-tabs2</position>
<position>menulist</position>
<position>footer</position>
<position>syndicate</position>
<position>debug</position>
</positions>


Add our new position to the list:

https://www.joomlart.com/forums/ja-tpl/images/misc/quote-left.png'); background-color: transparent; display: block; width: 9px; height: 13px; position: absolute; left: -9px; padding: 0px; margin: 0px; background-position: 0% 50%; background-repeat: no-repeat no-repeat;"> 
<positions>
<position>hornav</position>
<position>breadcrumbs</position>
<position>search</position>
<position>banner</position>
<position>left</position>
<position>right</position>
<position>right1</position>
<position>right2</position>
<position>top</position>
<position>headlines</position>
<position>header-m</position>
<position>header-r</position>
<position>mega</position>
<position>mega-adv1</position>
<position>mega-item</position>
<position>mega1</position>
<position>mega2</position>
<position>mega5</position>
<position>mega6</position>
<position>mega3</position>
<position>mega4</position>
<position>user1</position>
<position>user2</position>
<position>user3</position>
<position>user4</position>
<position>user5</position>
<position>user6</position>
<position>user7</position>
<position>user8</position>
<position>user9</position>
<position>user10</position>
<position>user11</position>
<position>user12</position>
<position>content-mass-bot</position>
<position>col-mass-bot</position>
<position>col-mass-top</position>
<position>col-mass1</position>
<position>col-mass1</position>
<position>ja-news-1</position>
<position>ja-news-2</position>
<position>ja-news-3</position>
<position>ja-news-mobile</position>
<position>sl1-l</position>
<position>sl1-r</position> 
<position>ja-tabs1</position>
<position>ja-tabs2</position>
<position>menulist</position>
<position>footer</position>
<position>syndicate</position>
<position>debug</position>
</positions>

5) Creating CSS Styling for our New Position 

Okay, we have created our new position and have entered it within our position listing (so that we can select it from the list of positions within our Module Manager). But we still have not established certain display parameters for our new position – i.e. height, width, margins/padding, background color, relative positioning within the header block, etc. For this, we need to create some basic CSS styling properties for our new position.


  -------------------------------------------------------------------------
NOTE: LEARNING CSS
Now, I am not going to try to teach a lesson on CSS styling – this is something you will need to take some time to research and learn individually. However, there are a great many learning resources available throughout the internet – many of which are 100% FREE. While I will leave it to you to conduct a more thorough search, here are a few initial resources with regard to CSS basics:


https://www.cssbasics.com/download-all-chapters/

https://www.w3schools.com/css/


These resources should at least get you started.
-------------------------------------------------------------------------

We will be placing our CSS rule(s) within our template.css file à \templates\ja_teline_iv\css\template.css

TIP:
It really doesn’t matter where you enter your CSS – many simply add it at the end of the sheet. I tend to like to place any new CSS rules/classes I create within the same general line area as other CSS for the particular section of the template – in this case, where the CSS for the "header-r" is (at/around line 748).

Our new position is going to be relatively simple, but we’re going to want to position it between the logo and the right side banner image. 

https://www.joomlart.com/forums/ja-tpl/images/misc/quote-left.png'); background-color: transparent; display: block; width: 9px; height: 13px; position: absolute; left: -9px; padding: 0px; margin: 0px; background-position: 0% 50%; background-repeat: no-repeat no-repeat;"> 
/* Header Middle ---*/
.ja-header-m { 
padding: 0;
border: 1px solid #ccc; 
position: absolute; 
right: 470px; 
top: 40px; 
width: 265px;
z-index: 999;
}

Obviously, depending on how you are going to want to style and position your module, your CSS properties and parameters are going to be different. More likely than not, the process of getting it just as you want it will take a bit of time, trial-and-error and patience. In fact, for our example, I had to play around with the "right" positioning value several times until I was able to position the module exactly where I wanted it. 

It's all part of the process . . . and the more you experiment with various properties, the more you learn about how CSS affects website element display.

6) Assign Module to the New Position

We've created our new position within the appropriate layout block . . . we've added the position to the position list within our templateDetails.xml . . . we've created the CSS to position and style our module . . . we're now ready to assign our module to our new position (and see if our work has paid off).

As stated above, I am going to assign a custom_html module with a JoomlArt banner image to the new position. While creating a new module within the Module Manager is a basic Joomla function, I will quickly outline the steps for you . . . 

1. Open your site administration backend >> open your Module Manager
2. Click the "New" icon
3. Select "Custom_HTML" from the list of module type choices
4. Name your new module
5. Click "Select Position" and scroll down until you find the new position (in our case, "header-m")
6. Configure your module parameters as needed

In our example, I used one of JoomlArt's banners for the new module . . .
And here is the result . . . .

module7

So, as you can see, creating a new module position within your site template is not as difficult or intimidating a process as you might have otherwise thought. 


IT IS IMPORTANT TO UNDERSTAND, however, that the above steps are THE MOST BASIC WAY to create a new module position within a given template. This exact process may vary slightly depending on the kind of module position you are creating and/or the layout block in which you want to create the position. 


As with most any new process one wants to learn, it's going to involve elements of time, trial-and-error/experimentation and patience . . . so PLEASE DO NOT GET TOO FRUSTRATED OR GIVE UP if your first try (or even first few tries) do not result in perfection right off the bat. Rest assured that almost anything you can envision can be accomplished if you allow it the time and attention it takes to do so.

 

 

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 .

Just ENABLE IT.

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 :

https://www.domain.com/index.php?tp=1 

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>
    </a>
    </div>
    <div class="nav-collapse">
      <jdoc:include type="modules" name="user4" style="none" />
    </div>
  </nav>
<?php endif; ?>

Joomla 1.5

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

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

Joomlart

Our template (JA MAGZ II) 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
Author: David AttardWebsite: https://www.linkedin.com/in/dattard/
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 using WordPress, Joomla 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!

Disclosure: This page may contain links to external sites for products which we love and wholeheartedly recommend. If you buy products we suggest, we may earn a referral fee. Such fees do not influence our recommendations and we do not accept payments for positive reviews.

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 

How to make your website FAST!

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

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