The Protostar template comes with a set of predefined positions. These positions are listed in the Position dropdown list of options when you create a module. Not all of these positions listed are used in the default Protostar template. Position locations must be defined in the index.php in order to have the modules assigned to them appear on the web page.

You can't simply "activate" these unused positions. They must be placed into the index.php document using HTML, PHP and a Joomla API statement. You can use the same method and statements used by the other active positions for placing your new position.

If you are comfortable with editing the index.php for Protostar, you can add statements to place these unused positions where you wish into the HTML framework for the page. You need to emulate how other positions are placed, but change the name="" to your new position.

How modules assigned to positions appear on the web page

Joomla uses the index.php document in your template directory to construct every page on your website. Joomla uses PHP programming to compile all the parts of each web page when the URL for that page is entered into the browser.

Within the index.php at the root of the Protostar template there are a number of if/end if statements that test if a module has been assigned to that particular position for that page to be displayed. If there is a module assigned to a position then that <div> or other HTML element will appear on the page. If there are no modules assigned, then that <div> or other HTML will not appear on the page.

Below are a two examples pulled from the index.php for Protostar:

<?php if ($this->countModules('position-1')) : ?>
   <nav class="navigation" role="navigation">
      <jdoc:include type="modules" name="position-1" style="none" />
   </nav>
<?php endif; ?>

<?php if ($this->countModules('position-7')) : ?>
    <div id="aside" class="span3">
        <!-- Begin Right Sidebar -->
            <jdoc:include type="modules" name="position-7" style="well" />
        <!-- End Right Sidebar -->
    </div>
<?php endif; ?>

What these statements are doing is using a PHP  if statement to test if a module has been assigned to position-1 or position-7. If true, the <nav> and <div id="aside"> are created for the page. If there are no modules assigned to these positions, then <nav> or <div id="aside"> are not created for that page.

Using a Joomla API statement of <jdoc: include type="modules" name="..." style ="..."/> the modules assigned to that position are placed into the page.

There are several other if/end if statements in index.php for other positions.

How do I create a new position location in index.php

First you need to figure out where you want the new position located in the HTML framework for the page.

Do you want this new position located in the <header>, or maybe across the bottom of the page, but below all three columns, maybe you want to add a position to the <footer> area. You need to have a good understanding of editing an HTML document and the HTML tag system to do this properly.

If you are going to use one of the existing "Unused" position names, which are position-9 through position-14, you won't need to edit the templateDetails.xml file, as these position names are already listed.

If you want to create a new position name, you need to edit the templateDetails.xml file and add your new name to the list. Once the position name is in this list, it will appear in the Position dropdown list for the modules.

A module assigned to this new position won't appear on the page until it is defined by the index.php file on the root of the Protostar template folder.

Add the new position to the index.php file

The index.php file that you need to edit is located in your Joomla file system at templates/protostar/index.php.

Always make a safety backup of the index.php file before editing the original file. You can download the index.php file to your own computer for editing with an FTP program and edit it with a text editor such as Notepad++. Do not use a word processor such as Microsoft Word to edit the file. You can also edit the index.php file using Template Manager inside the Joomla Administrative interface. Another way to edit the index.php file is to use your hosting company's file management system if they have a text editor available.

Open up the index.php in a text editor. Scroll down to the <body> section of the document. 

For this example we will create a new <div> that sits below the three columns of <div id="sidebar">, <main id="content"> and <div id="aside">. This new div will be as wide as the <div class="container"> and be contained in that <div>. It needs to sit outside of the </div> and </main> tags that close these other elements.  

This example assumes that the HTML framework has not previously been edited.

Find the last </div> just before the <footer>. This is somewhere near the end of the document. The last </div> closes the <div class="body">. The next </div> up closes <div class="container"> on a static layout or <div class="container-fluid"> on a fluid layout. The next </div> up is the <div class="row-fluid"> that contains the three columns. We want our new position to reside inside of this div.

Add the following lines just above the third to last </div> (there should be three </div> tags remaining below your new lines).

<!-- Custom Edit - add position-9 -->
<?php if ($this->countModules('position-9')) : ?>
    <div id="pagebottom" class="span12">
        <jdoc:include type="modules" name="position-9" style="XHTML" />
    </div>
<?php endif; ?>
<!-- End custom edit -->

Explanations for these lines are as follows:

<!-- Custom Edit - add position-9 -->  

This line is a comment so you can easily see where the index.php has been edited.

<?php if ($this->countModules('position-9')) : ?>  

This line uses a PHP if statement to see if any module has been assigned to position-9. If true, the lines below the if statement will be added to the HTML for the web page.

<div id="pagebottom" class="span12">

This line will create a new <div> for the page. The class of span12 will use the existing Bootstrap styling and will take up the entire width of the containing element of <div class="container">. Creating a containing <div> for our new position allows us to add styles in the CSS to target this particular element.

<jdoc:include type="modules" name="position-9" style="XHTML" />

This line uses Joomla API to include any module assigned to the position within the name="" attribute. The style = "XHTML" will allow you to choose if the module title can be displayed. The other options are style="none", no title will display, or style="well" which will use all of the styles from template.xml for the .well class. The style="well" also allows the module title to be displayed.

</div>

This closes the <div id="pagebottom">

<?php endif; ?>

This ends the PHP if statement

 <!-- End custom edit -->

This line is a comment to let you know where the custom editing ends.

Upgrading Joomla 

Keep in mind that whenever you edit the index.php file for Protostar you run the risk of losing these edits when you upgrade your Joomla installation. When you upgrade, the index.php for Protostar is replaced with a new file. There are ways to keep your changes:

Option 1: Recreate the changes in the new index.php

This is why you added the comments so you know where you made changes.

Option 2: Replace the new index.php with your old edited index.php

This will keep all your changes. You do need to realize that when doing this, you will lose any improvements made to the template.

Option 3: Make a copy of the Protostar template and rename the copy

To do this, you must take the proper steps for copying a template through Template Manager. This is the safest approach as no files will be overwritten when you upgrade Joomla. Keep in mind that you won't see any of the improvements made to the Protostar template with the new release.

Read this article to properly copy a Joomla template: How to Copy and Rename the Protostar Template


Has BJ.Zemplate.com helped you with understanding Joomla?

If you would like to make a small contribution to help fund this resource, that would be great, but do not feel obligated in any way.

Donation Amounts


Still not finding a special topic?

Use Google's Search function below for search the content of bj.zemplate.com.