Through this tutorial we're going to learn how to create and configure a basic module that will display information from the database. I choosed a popular component for job posting called Jobline. Jobline let you post jobs on your website and let your visitors apply. It's compatible with Joomla 1.5 legacy. We are going to develop a module that will connect to the database and list recent posted jobs and display it according to parameters we pass. On the next tutorials we'll be expanding our module to add more functions and more layouts and templates for output. This tutorial is for the beginners so bear me if you find explaination for the simplest things.

Simple facts:

1. Module files are placed within a folder named /modules/mod_ plus the module name
2. Each module contain an xml file which hold the module information and can be used to configure the module by passing parameters to it

We are going to call our module jl_listing so all files will be held in /modules/mod_jl_listing/

Start by registering the module in the database. Open phpmyadmin and execute the following statement ( you can also use EasySQL )

INSERT INTO `jos_modules` ( `title`,  `ordering`, `position`,`published`, `module`, `showtitle`, `params`) VALUES
 ('Latest Jobs', 1, 'left', 1, 'mod_jl_listing', 1, 'number=3');

Go to Joomla!'s administration panel -> Extensions -> Module Manager

You will find the module created with the name "Latest Jobs". If you clicked the module you will have a page like this with no details or parameters just some basic configuration for any module. Let's start adding some code to list the jobs!

Create mod_jl_listing.php inside /modules/mod_jl_listing/ and add the following code

<?php
defined('_JEXEC') or die('Restricted access');
$number = $params->get('number', 3);
$db =& JFactory::getDBO();
$query = "SELECT id, title FROM #__jl_jobposting WHERE state = '1' ORDER BY created DESC";
$db->setQuery( $query, 0, $number );
$rows = $db->loadObjectList();
foreach($rows as $row){
	echo '<a href="' . JRoute::_('index.php?option=com_jobline&id='. $row->id . '&task=view') . '">' . $row->title .'</a><br />';
}
?>

Don't panic, We will go through every line of this to explain how it works.

defined('_JEXEC') or die('Restricted access');

Almost every file in Joomla! begins with this line. This is to check if '_JEXEC' is defined to allow the code to work. That constant is defined on index.php so it will ensure that the code is called through Joomla! and block any direct access to the file. So this is not specific to our module this is a part of every file.

$number = $params->get('number', 3);

Next we declare the variable $number which will get and set the parameter number that will set the # of jobs to display using the get() function. We also passed 3 as a default value if no value exists.

$db =& JFactory::getDBO();

We declare another variable that will get a database object reference using the getDBO() method of the JFactory class. This is important to be able to retrieve the information we need from the database

$query = "SELECT id, title FROM #__jl_jobposting WHERE state = '1' ORDER BY created DESC";

The varilable $query hold the statement we are going to use. This is a pretty straight sql statement based on the structure of the table created by Jobline. We use #__ as the table prefix instead of jos_. When Joomla! executes the query, it automatically translates #__ into the database prefix chosen by the admin. Isn't it awesome ? We select the id and title . The clause WHERE state = '1' ensure we only get the published items. Items are ordered by creation date in a descending manner using ORDER BY created DESC. Note that created is the name of the column holding the creation date of the entery.

$db->setQuery( $query, 0, $items );

We use setQuery function to execute our SQL statement. The parameters that funcion use are the

1. $query containing the SQL statment to execute
2. 0 is the offset to start selection
3. $number is the number of results to return

Next we use $rows = $db->loadObjectList(); to returns an array containing the data we retrieved from the database.

And finally using foreach to list the recent jobs and create the links to it using the JRoute::_() function. This function takes a relative link as the parameter and returns a SEF version of it. Note that you don't have to encode the & mark to & to be XHTML valid. JRoute::_() take care of this part and it's considered best practice to use this function.

Now we are done, refresh the page and check out the restults!

Our module successfully connect to the database, get the information and display it! We're not done yet, we have to create the xml file which will hold the module information and pass the parameters to the module!

Go ahead and create mod_jl_listing.xml and insert the following code:

<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5">
<name>Jobline Latest Jobs</name>
<author>Ahmad Alfy</author>
<creationDate>March 200p</creationDate>
<copyright>(C) 2009</copyright>
<license>Non-Commercial</license>
<authorEmail>ahmadalfy-at-gmail.com</authorEmail>
<authorUrl>www.alfystudio.com</authorUrl>
<version>1.0</version>
<description>Display the latest jobs posted on Jobline.</description>
<files>
<filename module="mod_jl_listing">mod_jl_listing.php</filename>
</files>
<params>
<param name="number" type="text" default="3" label="Number" description="Number of jobs to display" />
</params>
</install>

Take a quick look everything here describe itself. The parameter named number is used to set how many enteries you want to display. Right now we are only introduced to the text type of the parameter. Later on as we expand our module we'll get to know other types.

Now check out the module after adding the xml file. See the parameter we added and the module description

To finish everything, we create a zip file containing both the mod_jl_listing.php and mod_jl_listing.xml and name this file mod_jl_listing.zip. Try installing the file through Joomla!'s installer. The installer use the data from the xml to create the module and insert the files in the correct place.

Congratulation! we've finished creating our first Joomla! 1.5 module You can now create similar modules to display recent enteries from any component you have! We explored the module code and learned how to create and configure it. Through the next tutorials we're going a bit deaper by exploring how to:

• Display error message if no enteries exist.
• Display random job.
• Create more layouts for the same module.
• Separate the database functionality from the display logic.
• Use language files to make our module compatible with multilingual componenets like Joomfish.

You can download the module here.

This tutorial is the first of a series coming through AlfyStudio.com so I appreciate your feedback and comments. If you have any recommendation or suggestion don't hesitate to contact me. Don't forget to digg or bookmark this page to help spread the world! Have a nice day developing for Joomla!