On the last tutorial, I've shown you how to create a module that connects to the database and displays links to the latest entries from Jobline. The way we coded the module was simple but it wasn't efficient to handle more complex scenarios.

In this tutorial we are going to modify our module to add more options (like the ability to display random entries). We will also explain how module output is returned and how to handle multiple layout options (like displaying results in lists or whatever format we want). In order to achieve that we need to separate the functions from the output.

The Functions

We start by creating helper.php This file will contain the helper class which will contain all the data functions. We are going to need functions to:

1. Get latest entries.
2. Get random entries.
3. Output the entries.

We will create a class named modJobsHelper containing the functions. The first one will be similar to the one we created on the previous tutorial but instead of outputting the results it returns a variable $rows. The second function will use a different query to get random results. Take a look at the following

<?php
defined('_JEXEC') or die('Restricted access');
class modJobsHelper{
	function getJobs(&$params){
		$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();
		return $rows;
	}
	function getRandomJobs(&$params){
		$number = $params->get('number', 3);
		$db =& JFactory::getDBO();
		$query = "SELECT id, title FROM #__jl_jobposting WHERE state = '1' ORDER BY rand() DESC";
		$db->setQuery( $query, 0, $number );
		$rows = $db->loadObjectList();
		return $rows;
	}
	function renderJobs(&$job, &$params){
		$link = JRoute::_("index.php?option=com_jobline&id=" . $job->id . '&task=view');
		require(JModuleHelper::getLayoutPath('mod_jl_listing', '_job'));
	}
}
?>

The last function is a part of the output, we are going to discuss this later on this tutorial.

Now let's get back to the mod_jl_listing.php We replace all the code we used with the following:

<?php
defined('_JEXEC') or die('Restricted access');

require(dirname(__FILE__).DS.'helper.php');

$random = $params ->get('random',0);
$view = $params ->get('view','default');

if($random){
	$jobs = modJobsHelper::getRandomJobs($params);
}else{
	$jobs = modJobsHelper::getJobs($params);
}

require(JModuleHelper::getLayoutPath('mod_jl_listing',$view));
?>

The first line include the helper.php (placed on the same folder as the mod_jl_listing.php) We create a new parameter $random and another one $view. The first one will be tested. If it's true to call the getRandomJobs to display random entries. The second one will set the layout.

The last line call the getLayoutPath method. This function returns the path to the layout file for the module. It also checks if there are any overrides in the template folder and return it's path if it exists (drop the override now, we'll take about that later!) This method takes two arguments; the module name and the selected layout.

The Output

Layout files are placed inside a folder named tmpl inside the module folder. We will create two layout options; list and default. So we are going to create tmpl/default.php and tmpl/list.php . Let's examine what output should we expect from the two templates:

1. Default :
   

   <a href="/entry1.html">An Entry</a><br/>
   <a href="/entry2.html">Another Entry</a><br/>
   <a href="/entry3.html">Yest Another Entry</a><br/>
   

2. List :
   

   <ul>
    <li><a href="/entry1.html">An Entry</a></li>
    <li><a href="/entry2.html">Another Entry</a></li>
    <li><a href="/entry3.html">Yest Another Entry</a></li>
   </ul>
   

We have something common between the two options:

<a href="/entry1.html">An Entry</a>

Why don't we move this into another file? This way when we make future updates to the module it will be easier. Modifying how a single entry is produce will update all layouts. Go ahead and create another file tmpl/_job.php . The name starts with (_) to remind us that it's an internal template for internal use; not an option the user can select from.

On the default.php we add the following code:

<?php
defined('_JEXEC') or die('Restricted access');
foreach ($jobs as $job){
	modJobsHelper::renderJobs($job, $params);
}
?>
<br/>

It calls the renderJobs function from the helper.php . We mentioned that earlier but didn't explain it. This function create the link to the entry then again use the getLayoutPath but this time this function use the _job template. Now add the following code to _job.php :

<?php
defined('_JEXEC') or die('Restricted access');
?>
<a href="/<?php echo $link ?>"><?php echo $job->title; ?></a>

That's all. The default layout is ready. Now add the following code to tmpl/list.php :

<?php defined('_JEXEC') or die('Restricted access'); ?>
<ul>
<?php
foreach ($jobs as $job){
	echo "<li>";
	modJobsHelper::renderJobs($job, $params);
	echo "</li>";
}
?>
</ul>

To summarize everything, check that figure:

Last thing to do now is to modify xml file to add the new variables and the new files

<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5">
<name>Jobline Latest Jobs</name>
<author>Ahmad Alfy</author>
<creationDate>September 2009</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>
<filename module="mod_jl_listing">helper.php</filename>
<filename module="mod_jl_listing">tmpl/_job.php</filename>
<filename module="mod_jl_listing">tmpl/default.php</filename>
<filename module="mod_jl_listing">tmpl/list.php</filename>
</files>
<params>
<param name="number" type="text" default="3" label="Number" description="Number of jobs to display" />
<param name="random" type="radio" default="0" label="Random" description="Random Review">
<option value="0">No</option>
<option value="1">Yes</option>
</param>
<param name="view" type="list" default="default" label="View" description="Layout">
<option value="default">Default</option>
<option value="list">List</option>
</param>
</params>
</install>

You can download the module here.

I hope you enjoyed this tutorial and I appreciate your feedback and comments. If you have any recommendation or suggestion don't hesitate to contact me. Enjoy developing for Joomla!