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

Before reading this part, please read part 1 of this series on how to add module positions to a Joomla template.

Add the position name to the template XML file

The template XML file contains the settings for the template, including the module positions. The file is located in the /template/yourtemplatename/ folder and is called templateDetails.xml. For instance, in the default JA_Purity template, the file is located here:

/templates/ja_purity/templateDetails.xml

As you know, you can choose between these module position when creating a new Joomla module using a drop-down. You can actually write the module position directly into the field as well. This means that it's not absolutely necessary to add the module position name to the XML file.

To make this clear: If you add a module to the position by entering the name into the field manually, the name will appear in the drop-down list. However, this happens only as long as there is a module assigned to the position. If the module is assigned to another position or deleted, the module name will disappear from the drop-down. This can be confusing. You might forget it yourself, and other users of the template will not know that the position is available.

So, it's good practice to add the module name to the XML file, so I recommend you do so. It's really easy, too.

To have the new module position name appear in the drop-down menu you have to add a new line in the XML file.

Open you templateDetails.xml file in your text editor of choice.

Locate the POSITIONS tag. You will see that between the start and end POSITIONS tag, the module positions are listed. All you need to do is copy one of the existing lines and change the position name to what you added in the template index.php file. In this case, we added a module position called "contenttop", so the line we need to add looks like this:

<position>contenttop</position>

Add a module to the module position

Now you're ready to add a module to the newly created module position. Let's say you want to add an alert telling your site visitors of an important event.

Go to the Module Manager in the Joomla Administrator, and click 'New'.

Click on the 'Custom HTML' module type name.

This creates a new custom HTML module in which you can place whatever HTML you want. I want to add a text, an image and a bright, red border. Want the alert to really stand out, right? ;)

I add the text 'System alert' to the title field. Then, I enter the following text into the text field below:

System Alert
Due to delivery problems, some of our yellow widgets will not be available for a couple of weeks. Please try our red widgets. They're just as nice.

I make the first line (System Alert) into a level 3 heading (H3), and the rest of the text into paragraph (P).

Make sure you disable the module title and enable the module itself:

Style and position the module using CSS

Now that you have added the module position to the template, and added the actual module, you can think about positioning and styling the module. This is what the module looks like without styling:

Because we added the DIV tag with the ID named 'contenttop', we can style the contents of the module position easily. Let's say I would like to have a fat, red border around the module. I would have to add some CSS to my template stylesheet. The template stylesheet (or stylesheets) is located in the /template/ja_purity/css/ folder. The stylesheet is normally found in the CSS folder of the template in question.

Border and color

To add the red border, I would add the following code to my CSS file:

div#contenttop .moduletable {
     border:5px dashed red;
}

This makes the module turn into this:

As you can see, there is too much space over and below the text. There is also a background image (the grey line), which is not something I'd want in my module. I adjust the CSS to the following:

div#contenttop .moduletable {
     border:5px dashed red;
     margin-top:20px;
     margin-bottom:20px;
     padding:10px;
     padding-top:14px;
     background:none;
}

What I did her was add some space (margin) over and under the module. I also added a general padding (space inside the module) of 10 pixels. I decided I wanted a bit more towards the top. I also set the background parameter to 'none', to remove the grey line.

The result is this:

Although this is OK, I want to add some more flair to the module.

Adding some design to the module

I want to place an image showing an alert triangle into the module. I want it to appear to the left of the text. I could, of course, add the image directly into the custom HTML module. However, I don't want my users messing with the image. I just want them to be able to add some text, and then have the image appear automagically in the module.

To do this, I need to add the image as a background image using CSS. First, I need to add the image to my images folder. Then, I have to adjust the CSS into something like this:

div#contenttop .moduletable {
     border:5px dashed red;
     margin-top:20px;
     margin-bottom:20px;
     padding:10px;
     padding-top:14px;
     background: #eee url("/images/stories/Alert-64.png") 20px 10px no-repeat;
}

The addition now is the 'background' parameter, which includes a backgrund color, an image URL, the positioning of the image inside the module. I also just want the image to appear once, so I add a 'no-repeat' value.

These adjustments give me the following, final result:

If you've followed my instructions, you now have a nicely styled and positioned system alert, which you can turn on and off as you please.

To learn more about how CSS works, read my article on Joomla CSS for beginners :)

Of course, this is just scratching the surface of what you can do with modules in Joomla.

Let me hear in the comments below what you would like to see more of!