Joomla Tutorial -- Extensions Part 1: Installing Modules

Joomla Extensions Modules are often the simplest type of Joomla extension or add-on that can be used in the Joomla! system. Installing modules will be a quick and simple process once you have learned the basic procedure. This tutorial takes you step-by-step through the installation and placement of a sample Hello World module.

What is a module?

Modules are generally used to display information and occasionally accept some type of basic interaction. When more complex interaction is required, a module will typically pass the control to an associated component. Examples of modules include:

Banner module -- Displays banner images that can include a hyperlink for the user to click on.
Who's Online -- Displays the number of users currently on the site.
Search module -- Accepts the search text string which is passed to the Search component that handles the query and results display.
Poll module -- Displays poll options and includes a submit button that sends the vote selections to the Poll component for processing.

These modules and others are included with the basic Joomla! installation. There are literally hundreds of other modules available for free download on the Joomla Extensions Directory. You can download one or more right now for use with this tutorial. However, I recommend you download the following Hello World module to minimize any potential errors and here's why:

The nature of free software is such that many add-ons that have been uploaded to the Extension Directory in the past NO LONGER WORK. When I started working with Joomla, it surprised me that around 1 in 3 of the extensions didn't work at all. I may have had a particularly unlucky streak in the beginning, but I still find many, many of them either won't install or won't execute properly. The high failure rate is primarily explained by the passage of time -- the original author wrote a working program but has not upgraded it as the Joomla! system changed.

Download Missing Metadata module Download the Jumpstart Hello module for Joomla 1.5 Download for J1.5

(Download Hello World module 1.0 -- coming soon)

Use the Extension Manager for Installation

With Joomla 1.5, installation of all extensions has been unified in the Extension Manager available in the Administrator interface. Login to your Joomla Administrator interface. Click on the Extensions menu and select the Install / Uninstall option as shown below. With Joomla 1.0, you should select the Installers > Modules option to install the module.

t Select the Install/Uninstall option

In the Upload Package File pane, click the Browse button select the module file that you want to install. When you click the Upload button, the module will hopefully upload successfully. This is the point where many extensions fail. If everything worked properly, you should see an installation confirmation screen as shown below. I've highlighted the success message and also the extension's description text which often has readme-type information. Normally you would next move to the Module Manager to properly configure the module. However, since you may have never checked your available template positions before, let's take a look at them first.

Module Upload Success

Check the Template Module Positions (only for Joomla 1.5)

The currently selected Joomla template determines the fonts, the graphics, and the style of the overall site. It also provides the module positions that are available for module display. Below you can see the preview of a template within the Joomla Administrator. I've added arrows to show all of the module positions that are captioned in the preview mode. These module positions are locations where modules can appear. For example, the left column in the figure has the caption left [rounded outline] with "left" as the name of the module position and "rounded outline" the style. Any modules set to appear in the left position will be rendered stacked atop one another in this panel, ordered in the sequence specified in the Module Manager.

Module positions are shown in preview mode

Each templates may support different module positions and those positions may appear in different places in the layout. If you have installed an unfamiliar template (or have never checked the layout before), open the Template Manager through the Extensions menu. Select the radio button to the left of your current template and click the Edit button. Once the selected template is displayed in the Template [Edit] screen, click on the Preview button. You will see your template (as shown above) with each module position captioned in the layout. Make a note of the position where you would like your module to appear.

Using the Module Manager

To configure the newly installed module parameters, in Joomla 1.5 you must select the Extensions > Module Manager option to display that manager. In Joomla 1.0, you want to access the Modules > Site Modules option. If the module you installed is an Administrator module, use Modules > Administrator Modules.

Find the module titled Jumpstart Hello and click on the title. It may be on the second page of the module listings in which case you'll have to use the navigation arrows at the bottom of the screen to page forward. The Module: [ Edit ] screen will be displayed showing you all the module parameters. Set the Enabled parameter to Yes and set the Position parameter to the place you want the module to appear in the template. You can also set the Order parameter to zero (0) if you want the module to appear at the top of the stack for this template position.

Edit the module settings

You may have noticed a pane on the right side of the screen titled Module Parameters. In the case of the Jumpstart Hello module, there are no parameters and it should state this information. However, if your module has parameters to configure (these often include text strings or display colors), the settings can be adjusted here.

Click the Save button to store the enabled and position adjustments and you should be all set!

Looking at the Hello World module

You have successfully installed and configured a module. If you go to your Joomla Frontpage, you should see the module at the place you've specified (as show below). In the next article in the series, you'll learn how to install and configure a component.

Your module show appear on the Frontpage

Joomla Jumpstart