Tutorial: How to add module positions to a Joomla template - part 1

    module-positions-illLast week, I did a post on how to add Javascript snippets to Joomla. The way I did this was by adding module positions to the template.

    In this post, I will delve deeper into how to add module positions to your template.

    This is the first part of a two-part mini-series on how to add a module position to your Joomla template.

    There can be several reasons for you to add more module positions to a template. You might want to:

    • Add code to the template easily, as in my previous post on how to easily add Javascript snippets to Joomla templates
    • Create more positions to facilitate ads or other functionality
    • Add more 'right' or 'left' positions to make it easier for users to control where modules appear (right1, right2 etc).

    Imagination is the only thing stopping you, really.

    What you need to know

    To add module positions, you need some basic HTML knowledge, and it doesn't hurt to know something about CSS (Cascading Style Sheets) as well. I have previously written a post on Joomla and CSS, so take a look at that if you are unfamiliar with the concept.

    To add a new module position successfully, you need to:

    1. Add code to the template index.php file
    2. Add the position name to the template XML file
    3. Style and position the module using CSS

    Sounds scary? Not to worry, I'll walk you through it, step by step.

    1. Add code to the template index.php file

    The template index.php file is the main file of your template. It's the file that loads in the browser when someone visits your website. The file is built up by a combination of HTML, PHP snippets and, oftentimes, Javascript as well.

    Every Joomla template has a component area and some module positions. The component area is where the output from Joomla components are shown. The output can be articles, category or section views from com_content, web links from com_weblinks, or output from some third-party, installed component.

    The component area looks like this in your template:

    <jdoc:include type="component" />

    What are module positions?

    The module positions are where you put all of the other functions of your Joomla site. This includes menus, latest news, banners, breadcrumbs and newsfeed modules, to mention some. As well as any third-party modules you choose to install.

    This is what a simple Joomla template might look like, in terms of component and module positions:

    Simple Joomla template

    A more complex Joomla template may look like this:

    Complex Joomla template

    As you can see, the basics are the same for both templates. The second one just gives you more options in where to place your modules.

    To add the actual module position to the template, we need to add a PHP snippet to our index.php file.

    The module positions snippets look something like this:

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

    The parameters you can change are the name and the style. The name is the actual name used when assigning a module to the position. The style determines which module chrome is used on the module.

    So what's module chrome?

    Before we add the module position to the template, I need to say a few words about module chrome. Simply put, module chrome is the styling code that each module in the position gets wrapped in. There are several module chrome types included in Joomla, and you can also create your own custom module chrome.

    The module is wrapped by code (or not) according to the style parameter you enter in the PHP snippet.

    Joomla module chrome

    For instance, in the above snippet, I used the XHTML module chrome.

    The XHTML style wraps the module in the following code:

    <div class="moduletable_menu">
     <h3>Main Menu</h3>
     <ul class="menu">
     <li><!-- various menu items --></li>
     </ul>
    </div>
    

    There are several other styles available, including TABLE and NONE.

    Output from the TABLE style:

    <table cellpadding="0" cellspacing="0" class="moduletable_menu">
     <tr>
     <th valign="top">Main Menu</th>
     </tr>
     <tr>
     <td>
     <ul class="menu">
     <li><!-- various menu items --></li>
     </ul>
     </td>
     </tr>
    </table>
    

    If the NONE style is applied, the module gets no wrapping at all (surprise!):

    <ul class="menu">
     <li><!-- various menu items --></li>
    </ul>
    

    For more on module chrome, see the What is module chrome article on docs.joomla.org.

    Now, let's add the module position to the template

    First, make a copy of your template and work on the copy. Then, open your template index.php in your HTML editor of choice.

    Secondly, you need to decide where to put the module position. For the purpose of this example, I want to add a new module position above the content of my site. This kind of module position could be used for adverts, or perhaps for alerts or other elements you want to position just above the component area.

    So, I'll add a position called 'contenttop' to the template.

    I'll use the JA Purity template as an example, so you can take a look at the code yourself. This template is one of the standard templates delivered with the default install of Joomla.

    Locate this area in the JA Purity template index.php file:

    <!-- BEGIN: CONTENT -->
     <div id="ja-contentwrap">
     <div id="ja-content">
    
     <jdoc:include type="message" />
    
     <div id="ja-pathway">
     <jdoc:include type="module" name="breadcrumbs" />
     </div>
    
     <jdoc:include type="component" />
     
     <div id="ja-banner">
     <jdoc:include type="modules" name="banner" />
     </div>
    
     </div>
     </div>
     <!-- END: CONTENT -->

    As you can see, there are several module positions in the content section already: Immediately above the component area  you can see the breadcrumbs module. And just below it the designer has placed the banners module.

    I want to add the new contenttop module just above the component area, so it will have to go into the code after the breadcrumbs.

    After adding, the code close to the component area will look like this:

     <div id="ja-pathway">
     <jdoc:include type="module" name="breadcrumbs" />
     </div>
    <jdoc:include type="modules" name="contenttop" style="xhtml" />
    <jdoc:include type="component" />
     
     

    Improving your module position code

    In the above example, I've added the contenttop module position, but I've not added any more code to it. To control the styling and appearance, and when the module appears, you should add some conditional statements and DIV tags:

    <?php if($this->countModules('contenttop')) : ?>
    <div id="contenttop">
    <jdoc:include type="modules" name="contenttop" style="xhtml" />
    </div>
    <?php endif; ?>
    

    What these additions do:

    1. The PHP IF statement adds a check to see if there is a module assigned to the position
      If we don't do this check, the module chrome will be output in the source code when the page is shown in the browser. That's not ideal, as you can end up with empty headers and other unwanted elements on your page. It also bloats the code. If it has no purpose, the code should not be there.
    2. The DIV adds an easier way of styling this particular module position
      You can use CSS to add styling to the module (that's #3 of this post, just so you know).

    Save your template index.php file. Congratulations, you now have a new module position in your template.

    That concludes first part of this two-part series on Joomla module positions.

    The next steps are to add the module position name to the template XML file, and to position and style the module position using CSS.

    Read part two of this series on how to add module positions to a Joomla template.

    Read 53248 times Originally published on Tuesday, 17 August 2010 15:00
    Last modified on Tuesday, 24 August 2010 09:46
    comments powered by Disqus
    Powered by Joomla
    Download Joomla for free