To add a new position to the Protostar template, you must take three basic steps:

A: Add the position name to templateDetails.xml

B: Add the position to index.php in the root of the Protostar template files

C: Add styles to the stylesheet for the position to appear as you wish

When taking these steps you must keep in mind how you want to name the position, where you want to have it placed on the page and how you want it to appear.

As with any edits to the Protostar template, you must realize that these edits can be overwritten if you upgrade your Joomla files. You can copy and rename the Protostar template using the proper steps in Template Manager so that the files are not overwritten. You can also keep the template as is and replace the edits in the new Protostar files.

Always make a backup of your site's files before editing the files. This way you can quickly replace the files if you make edits that crash you site or cause major problems. If you have a live website and are making large changes, consider making the edits on a duplicate site and moving the site over when you have accomplished your goals.

Add a new position name to templateDetails.xml

Within the files in the root of the Protostar template, there is a file with the name of templateDetails.xml. To create a new position for your modules, you must add the position name to the templateDetails.xml within the <positions>...</positions> area. When Joomla displays the possible positions in Module Manages, it looks at all the positions in this list.

For this example, we will add a new position name of customposition.


Save this file back to your template files for your site.

If you login to the back end of your Joomla site, go into Module Manager and take the steps to crate a new module, you should see this new position in the dropdown list for positions. It will also show up in this list for existing modules. Just because it is in this list, does not mean that it will appear on the site. You must now add it to your index.php, so that Joomla loads the position to the HTML of the web page.

Add the position to your index.php file

This is the complicated step. You must do this step correctly, or you can crash your website. Make a backup of the index.php as it is, before editing the original file.

For this example, we are going to create a position that sits below the <header> area and sits within the content area. Our example position will sit on top of position-7. You may wish to add a position somewhere else on the page, if so, you need to add it in the proper location and give it the proper class name so it appears as you wish.

Open up the index.php file in a text editor and scroll down to where you see the current position-7. In a new Joomla installation that has not been edited, these lines are somewhere around line 182. Copy all of these lines and paste them above the existing lines.

<?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 -->
<?php endif; ?>

Let us explain what these lines are accomplishing, so you know how to edit them to fit your new position.

<?php    ?> These tells the browser that there is PHP code between the opening and closing brackets
if ($this->countModules('position-7')) : This is a PHP if statement that checks if there is any module assigned to position-7 for this particular web page. If so, the browser will continue with the following lines, if not, the browser will skip this <?php ... ?> section.
<div id="aside" class="span3"> This adds the HTML with this <div> its id and class name added. The id and class name are for styling with the stylesheet. You will want to add a unique id and a class name to your custom position so that you can target it with your styles. The class of "span3" uses Bootstrap styles for a responsive webpage.
<!-- Begin Right Sidebar --> This is simply a comment for your own information. The browser does not display text within <!-- and -->
<jdoc:include type="modules" name="position-7" style="well" />  This is code that Joomla uses to load the content of the module. Note, the position name is not added to the HTML, just the content of the module assigned to that position. Joomla assigns specific information to types with the style="well". The other possible styles are style="none" and style="xhtml". If you want your module to be able to display the module title, use style="xhtml"
<!-- End Right Sidebar --> Anther comment line
</div> Closes the <div id="aside">
<?php endif; ?> Closes the PHP if statement.

Edit the copy of the <?php..?> statement to work with your new position:

<?php if ($this->countModules('customposition')) : ?>
    <div id="topright" class="span3">
        <!-- Add custompostion -->
        <jdoc:include type="modules" name="custompostion" style="xhtml" />
        <!-- End Custom Postion -->
<?php endif; ?>

Be sure to add the name of you new position in two places, inside the PHP if statement and inside the <jdoc:> tag.

Add styling for your new position

In your custom stylesheet or at the end of template.css, add styles to make your position appear as you wish.

In our example, by assigning class="span3" to this position, it will already have the styles that apply to span3 from template.css.

Has 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