Joomla

This post is an archive. If you have any Joomla questions, please feel free to send us an email!


One of the best features of Joomla is the ease with which you can extend existing functionality. One such example is how you can quickly change the parameters of a given module and how they are implemented. Using a standard Joomla module we will show how simple it is to modify and enhance existing code.

Without going into too much detail, there are some basic things we need to know about modules in Joomla. First, they are made of several different parts, which, for simplicities sake we will group into two important areas. One, the XML manifest file, and two, the grouping of files responsible for code execution and display. The XML manifest file tells Joomla several important things upon installation and beyond. For example, if tables need to be installed in the database, who the author of the file is, etc. However, for this exercise most important is that it defines what parameter options to show when you are administering a module from the Joomla back end. As such this file exists in all modules regardless of origin. The second area, the grouping of files that contain code and render the display of the module may vary in structure depending on the designer, their comfort level with Joomla, and overall skill level as a programmer. This may be daunting at first, but you will see that most modules are pretty easy to figure out once you get a feel for how the module works.

To illustrate how to easily change and enhance an existing module, we have decide to extend the latest news module that is shipped with all installations of Joomla. The function of the latest news module is to take that latest articles published in a certain category or section or author and display their titles and teasers in an unordered list. The modification we are proposing today is to give the user an option to not use a list but a stack of divs instead.

This task essentially breaks down into a few logical steps:

  1. Allow for a new parameter to be set in the back end that determines if an unordered list or divs should be used to display the articles
  2. Read out our new parameter in the module code
  3. Render different html tags based on this new parameter

Starting at the top we first open mod_latestnews.xml, which is the latest news modules manifest file. Conveniently, the options for all module parameters are defined right here. Here is an example of a module parameter definition:

<param name="user_id" type="list" default="0" label="Authors" description="A filter for the authors">
	<option value="0">Anyone</option>
	<option value="by_me">Added or modified by me</option>
	<option value="not_me">Not added or modified by me</option>
</param>

Just looking at the above XML tag we can make some intuitive guesses about how these parameter definitions work. The name attribute represents a unique identifier which we will need later on to read out the parameter. Type reflects the type of parameter desired in our options menu. Other types include among others text, spacer, and radio. Label represents the text which is shown next to the option in our modules back end configuration, and description the tool tip that is show when you hover over that text with your mouse. From the looks of it, the list type appears to resemble the HTML SELECT tag which includes a group of OPTION tags within. The option tag used here is equivalent to the one used in SELECT tags in HTML.

Our next step simply involves crafting our own parameter:

<param name="display_tag" type="list" default="UL" label="Display Tag" description="Choose how to display the list of articles">
	<option value="UL">UL</option>
	<option value="DIV">DIV</option>
</param>

Note how we used the unique name display_tag to identify this parameter, set up two options to choose from, UL and DIV, and assigned the UL option as the default, as this was the initial behavior of the module. The label and description are there to remind us of what our parameter does. Insert the above code below the code for filtering by author and pull up the module options for a latest news module. You will see our brand new parameter available for us to be set.

The next step is to read the parameter in the actual code of the module. In all its glory, Joomla passes an object of these parameters to the module when it is invoked. To get the value of this parameter all we need to do is call the parameter with the key that we assigned the parameter as a name attribute above. So for example

<?php
$value = $params->get('display_tag');
?>

will either return UL or DIV depending on what variable was set in the back end.

From here on out it is trivial to modify the existing module to read out the parameter and output the right HTML. Because we might want to add other options for display in the future, we have opted for a switch statement. The file requiring editing in this case is default.php which can be found in the tmpl directory of mod_latestnews.

Original Code:

<?php // no direct access
defined('_JEXEC') or die('Restricted access'); ?>
<ul class="latestnews<?php echo $params->get('moduleclass_sfx'); ?>">
<?php foreach ($list as $item) :  ?>
	<li class="latestnews<?php echo $params->get('moduleclass_sfx'); ?>">
		<a href="/<?php echo $item->link; ?>" class="latestnews<?php echo $params->get('moduleclass_sfx'); ?>">
			<?php echo $item->text; ?></a>
	</li>
<?php endforeach; ?>
</ul>

Our new Version:

<?php // no direct access
defined('_JEXEC') or die('Restricted access'); 
//get the parameter for display style
switch ($params->get('display_tag')) {
    case "UL":?>
	<ul class="latestnews<?php echo $params->get('moduleclass_sfx'); ?>">
	<?php foreach ($list as $item) :  ?>
		<li class="latestnews<?php echo $params->get('moduleclass_sfx'); ?>">
			<a href="/<?php echo $item->link; ?>" class="latestnews<?php echo $params->get('moduleclass_sfx'); ?>">
				<?php echo $item->text; ?>
			</a>
		</li>
        <?php endforeach; ?>
        </ul>
        <? break;
    case "DIV":?>
        <div class="latestnews<?php echo $params->get('moduleclass_sfx'); ?>">
	<?php foreach ($list as $item) :  ?>
		<div class="latestnews<?php echo $params->get('moduleclass_sfx'); ?>">
			<a href="/<?php echo $item->link; ?>" class="latestnews<?php echo $params->get('moduleclass_sfx'); ?>">
				<?php echo $item->text; ?>
			</a>
	</div>
	<?php endforeach; ?>
	</div>
	<? break;
}
?>

While at first daunting, changing and building on existing Joomla modules can be an easy way to get a lot more kick mileage out of free software.