Make a simple Joomla module

Modules are one of Joomla’s greatest features. It’s amazing how simple it is to make one. We’re going to show you how to get started making the simplest basic module. In subsequent lessons, we’ll be adding functionality to this basic module and help you master all the steps.

Step 1: Create a directory structure.

Use FTP or a file manager and create these directories inside the module directory of your Joomla Site.
/public_html/modules/mod_firstmodule
/public_html/modules/mod_firstmodule/templ
/public_html/modules/mod_firstmodule/language
/public_html/modules/mod_firstmodule/language/en-GB

Note that the directory starts with mod_ followed by the name of the module. It’s easy to see that all the directories follow this naming convention. The most important files also follow this convention. This is an important part of making the module work.

Step 2: Make a blank index.html file for each directory.

This is a security feature and good practice any time you create a directory on the server.

Next create the actual first file that will start to define your module. There are two all important files the .php file and the .xml file.

Both of them have similar names that follow the same naming convention as the folders. Maintaining the names throughout the module is very important.

mod_modulename.php
mod_modlulename.xml

Step 3: Create mod_firstmodule.php

Use the naming convention and create a file called mod_firstmodule.php
Include these items.

PHP opening tag
A doc bloc with an ID
Access restriction
An include directive
Closing PHP tag
Some content in an html tag

The access directive limits access to the rest of the file from any non-joomla scripts. In other words, if it’s not from Joomla, “die” or stop all further action.

The include is going to require that the contents of the helper.php file are read into this file at run time, before anything else. You can use the require directive to include css files, additions or modifications. You can modify the required file and never have to modify the main file. It’s a very handy technique for programming.

You don’t always need a helper file, so you won’t always need a require directive. We are including one so we can demonstrate all the basic techniques you will need to create a module.

Step 4: Create mod_firstmodule.xml

The most important lines in the first section.

Line 1 – open xml and specify encoding
Line 2 – It’s important to specify the version as 2.5 in the opening extension tag. (remember to close this at the end of the file).
Line 3 – The name of the module
Line 11 – Be sure to add a description. We are going to show you how to use a variable in that position in a later step.

Opening Code

<?xml version=”1.0″ encoding=”utf-8″?>
<extension type=”module” version=”2.5″ client=”site” method=”upgrade”>
<name>mod_firstmodule</name>
<author>Joomla! Project</author>
<creationDate>February 2010</creationDate>
<copyright>Copyright (C) 2005 – 2012 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>ed@ostraining.com<;/authorEmail>
<authorUrl>www.ostraining.com</authorUrl>
<version>2.5.0</version>
<description>My First Module</description>

</codecitation>

Defining the files

The other important sections that must be included.

Files – this specifies the folders and files that will be a part of this module.

includes all the files in that folder recursively
includes an individual file.

Language – this section includes language files and language strings. If you look at some of the core modules you will see this section because they have placed the language files directly in the languages folder. You can also include a custom language folder for your module. The advantage to a custom folder is that it won’t be eliminated by upgrades and your module will be a self-contained unit. We’ll be showing you how to create you’re own language folder.

Configuration and fieldsets

The config section contains the fields and their parameters. Notice that is a tag with an opening and closing . is the closing tag that was opened in line 2 at the top of the file.

</codecitation>

Step 5: Create helper.php

Create a helper.php file with an opening php tag
Add the access restriction.
Close the PHP tag.
Add some HTML

Actually a helper.php file is not necessary to operating a module. If you look at the directories for other modules, you’ll see many that don’t have it. We need to write one for this example, though.

Why do we need one? When I asked you to write the mod_firstmodule.php file, you put in a line that required the helper.php file. If you ask for it, but you don’t have it, Joomla is going to give you an error message that the file wasn’t found. If you don’t want to use one, don’t use the “require” in the .php file.

For now let’s just include a minimal one so we don’t invite an error. More on this later.

<?php
/**
* @package Joomla.Site
* @subpackage mod_firstmodule
* @copyright Copyright (C) 2005 – 2012 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

defined(‘_JEXEC’) or die;
>?
<p>Let’s put a greeting here</p>

</codecitation>

Let’s put a greeting here

Step 6: Check your work by installing the module

Here’s what your public_html/modules folder should look like at this point.
Now go to your Joomla administration.
Go to Extension Manager.
Click the Discover Tab.
Purge Cache
Click Discover.

If you have made any php errors, you’ll be getting an error message right after you click Discover. If you get any messages, clean up the code before going any further.

Install your new module.