Module specifications

Let’s build a real module! To start with, I am thinking of a module that would present a stylish link to one of the latest articles of our site, randomly chosen. The mystical idea behind this module is to promote existing content while giving a constant freshness to our site. By the way, although this idea is fairly old, it works well.

Before getting into the main example, you may want to consolidate the things you've read so far by looking at the following tutorial at the Joomla Developer Manual.

So, we will name the module ranlatest so, create a mod_ranlatest directory under your Joomla modules path.

There are similar modules around, the only difference with this one is that you will write the code for it. In more detail, here are the configuration options and the tasks the module should carry out.

• The administrator sets the acceptable section ids, from which the article will be selected from. (comma separated)
• The administrator sets the maximum number of articles our set should have before we randomly choose an article. The latest articles will be picked up.
• The administrator can set if the front page articles should be included or not.
• Only published articles will be selected.
• According to settings, a query is run against the jos_content table and a record set is fetched. (if the set is empty, nothing is displayed)
• Randomly an article is picked up from the record set.
• A link to this article is presented.
• The administrator has the option to supplement the presented link with text. The additional text is placed just before the link.

Go on, stop reading here, think about the requirements and try to do your homework.

<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
   <name>ranlatest</name>
   <author>Me</author>
   <creationDate>February 2009</creationDate>
   <copyright>Copyright (C). All rights are yours to keep.</copyright>
   <license>To kill</license>
   <authorUrl>www.joomladin.org</authorUrl>
   <version>0.0.1</version>
   <description>Displays a link to a random article, 
                 the article is one of the latest ones</description>
   <files>
      <filename module="mod_ranlatest">mod_ranlatest.php</filename>
   </files>
   <params>
      <param name="secid" type="text" default="" label="Section ID"
             description="Selects articles from a specific section
                          or set of sections. 
                          Separate each ID with comma. 
                          Leave empty to select all sections." />
      <param name="articlenum" type="text" label="Number of Articles"
             description="Selects the number of articles in the set. 
                          The latest articles are selected. 
                          Leave empty to select all articles." />
      <param name="front" type="radio" default="0" 
             label="Front Page Aricles"
             description="Choose yes to include front page articles." >
             <option value="0">No</option>
             <option value="1">Yes</option> 
      </param>
      <param name="@spacer" type="spacer" default="" 
             label="" description="" />
      <param name="pretext" type="textarea" default="" rows="3" cols="30" 
             label="Pre-Text"
             description="This text will be printed before the link." />
   </params>
</install>

The XML part should be piece of cake, hopefully the only thing new to you here is the spacer. Now, if you have digested the tutorial thus far, you probably think that our only problem is the SQL statement. Well, we have another problem that you have not anticipated yet.