New users of Joomla tend to find template module positions confusing and possibly frustrating. Joomla 1.5 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 will attempt to clear the air about template module positions.
In the Joomla 1.5 Module Manager ( Extensions > Module Manager, you can assign your modules to a number of positions. As opposed to Joomla 1.0, where positions where defined at website level, the positions in Joomla 1.5 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.
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 , 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 1.5, 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?
Simple 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 left, right, top and banner
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//templateDetails.xml Find the 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>
To add your own position, you need to insert a new 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. More information on how Joomla 1.5 templates work can be found in the 1.5 template Wiki page: http://docs.joomla.org/New_features_introduced_in_Joomla!_1.5_templates
 |
Joomla Tutorials 
Dec.20
Subscribe to this comment's feed
