Each Joomla template will have its own unique set of predefined positions. The position names are set up in the templateDetails.xml file and placed into the template in the index.php file using PHP and HTML.

You see the list of existing position names in Module Manager when you set up or edit a module. A drop down list shows all the positions for each front end template enabled for your site.

You can add new positions or rename existing positions with edits to the templateDetails.xml and index.php. Before editing the original files, you should always make a safety backup.

You can edit the original files by downloading them to a local computer with an FTP program and editing them in a text editor like Notepad++. Do not edit the files using a word processing program like Microsoft Word.

You can also edit these files at your hosting environment. If your host provides cPanel for managing your files and databases, you can get to the files with the file manager, then use the code editor to edit the files. Different web hosting services have different ways to access and edit individual files.

Joomla 3 now has a nice text editor built in for editing these files as well. If you go to Template Manager then click on the name of your default template in the Template column you will arrive at a screen where you can directly edit the files for your template. Click on the name of the file and a text editor appears with the contents of the file.

Position names in templateDetails.xml

Position names are defined in the templateDetails.xml file that resides on the root of your chosen template. For example:


If you are using a template other than Protostar, edit the templateDetails.xml file for your own template.

These position names are used to populate the position drop down menu in Module Manager. Different templates have different position names. Some will use rather generic names, like position-2. Others will have very specific position names like top-left-sidebar. 

We will use the Protostar template for this example:


If you wish to add your own position name, you can edit this list by adding the new name in the same format. It must be XML recognizable characters and do not add spaces. This new position name will show up in the list of positions for your template in Module Manager, but you need to tell Joomla where to place this position in the index.php for your template.

Add the position to index.php

The index.php file that sits on the root of your template is the base for every page on your website. It uses PHP and HTML to compile every page displayed on your site. You Joomla installation has many index.php files, so be sure to edit the correct one. Here is an example for locating this file.


If you are using a template other than Protostar, be sure to edit the index.php for your own template.

Note: you need to be very careful when editing the index.php file as it is the backbone of your website. Always make a safety backup before editing the original file. Test your website after each edit to be sure that you have not cause the site to go down.

Open up the index.php file in a text editor. You want to emulate how other positions are put into place. Here is an example from Protostar on how position-8 is located in the framework for the web page:

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

Let look what this code is doing:

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

This line above is using PHP to test if any module has been assigned to this web page for position-8. If so, the program proceeds to the next step. If not, nothing is added to the page

<!-- Begin Sidebar -->
    <div id="sidebar" class="span3">
        <div class="sidebar-nav">

The next few lines shown above add the HTML for the page. This is what you will target with your styles. The actual position name is not added to the HTML document and you do not target the position name with your styles.

            <jdoc:include type="modules" name="position-8" style="xhtml" />

This line is using the internal Joomla API to include whatever content is contained in the modules placed into position-8. The style="xhtml" allows you to include the title of the module. You may also see style="none" in your document.

    <!-- End Sidebar -->
<?php endif; ?> 

The following lines are two closing tags, a comment and the endif; for the PHP.

To add your custom module position, copy this format and place it where you wish the module to go in the HTML for the page. You should include the PHP if and endif statements so that the HTML elements for this only show up when a module has been placed into your new position.