Basic Hello World Module
A Joomla! 1.5 Module is in its most basic form two files: an XML configuration file and a PHP controller file. The XML configuration file contains general information about the module (as will be displayed in the Module Manager in the Joomla! administration interface), as well as module parameters which may be supplied to fine tune the appearance / functionality of the module. The PHP file provides the controlling logic for the module. A very simple "Hello World" module might looking something like this.
/modules/mod_hello_world/mod_hello_world.xml:
!!! Note: it is very important, that XML file name matches module name. Otherwise, installer will install the module, but Joomla wouldn't show parameters and additional info stored in XML.
version="1.0" encoding="utf-8"?>
> Hello World - Hello>
> Ambitionality Software LLC>
> 2008-06-23>
> All rights reserved by Ambitionality Software LLC 2008.>
> GPL 2.0>
> info@ambitionality.com>
> www.ambitionality.com>
> 1.0.0>
> Provides a basic "Hello World" notice>
>
> index.html>
>
/modules/mod_hello_world/mod_hello_world.php:
//don't allow other scripts to grab and execute our file
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
?>
Hello World
Hello World
to the final page.
/modules/mod_hello_world/index.html:
bgcolor="#FFFFFF">To package this module for distribution and installation, simply zip the files together, e.g.,
% cd mod_hello_world % zip mod_hello_world.zip mod_hello_world.php mod_hello_world.xml index.html
Real Joomla! 1.5 Style Module Implementation
Now that was easy...too easy. In fact, that was pretty much the simplest form of a module possible. In reality a module will probably be doing something much more substantial. Let's assume that our modules are going to be more complex - we need to take advantage of the MVC (Model View Controller) design pattern and consider using the following file layout for a "Hello World 2" module instead:/modules/mod_hello_world2/index.html /modules/mod_hello_world2/mod_hello_world2.php /modules/mod_hello_world2/mod_hello_world2.xml /modules/mod_hello_world2/helper.php /modules/mod_hello_world2/en-GB.mod_hello_world2.ini /modules/mod_hello_world2/tmpl/index.html /modules/mod_hello_world2/tmpl/default.php
Let's take a look at what these files might look like and discuss what's going on.
/modules/mod_hello_world2/mod_hello_world2.php:
//no direct access
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
// include the helper file
require_once(dirname(__FILE__).DS.'helper.php');
// get a parameter from the module's configuration
$userCount = $params->get('usercount');
// get the items to display from the helper
$items = ModHelloWorld2Helper::getItems($userCount);
// include the template for display
require(JModuleHelper::getLayoutPath('mod_hello_world2'));
?>/modules/mod_hello_world2/mod_hello_world2.xml
version="1.0" encoding="utf-8"?>
> Hello World 2 - Hello>
> Ambitionality Software LLC>
> 2008-06-23>
> All rights reserved by Ambitionality Software LLC 2008.>
> GPL 2.0>
> info@ambitionality.com>
> www.ambitionality.com>
> 1.0.0>
> Provides a random listing of registered users>
>
> index.html>
> helper.php>
> tmpl/default.php>
> tmpl/index.html>
>
>
>
name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" />
name="@spacer" type="spacer" default="" label="" description="" />
name="usercount" type="text" default="5" label="LABEL USER COUNT" description="DESC USER COUNT" />
>
>/modules/mod_hello_world2/helper.php:
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
class ModHelloWorld2Helper
{
/**
* Returns a list of post items
*/
public function getItems($userCount)
{
// get a reference to the database
$db = &JFactory::getDBO();
// get a list of $userCount randomly ordered users
$query = 'SELECT a.name FROM `#__users` AS a ORDER BY rand() LIMIT ' . $userCount . '';
$db->setQuery($query);
$items = ($items = $db->loadObjectList())?$items:array();
return $items;
} //end getItems
} //end ModHelloWorld2Helper
?>/modules/mod_hello_world2/tmpl/default.php:
defined('_JEXEC') or die('Restricted access'); // no direct access ?>
echo JText::_('RANDOM USERS'); ?>
foreach ($items as $item) { ?>
echo JText::sprintf('USER LABEL', $item->name); ?> } ?>
/modules/mod_hello_world2/en-GB.mod_hello_world2.ini:
LABEL USER COUNT=User Count DESC USER COUNT=The number of users to display RANDOM USERS=Random Users for Hello World2 USER LABEL=%s is a randomly selected user
Now all we have to do is zip up these files, as in:
% pwd /somesite/modules/mod_hello_world2 % zip -r ../mod_hello_world2.zip * % ls .. mod_hello_world2.zip
Joomla! 1.5 Database installation usage
Modules should in general not interact with the database except for normal operations (SELECT, UPDATE, INSERT, DELETE). But in some cases it might be needed to ALTER or even CREATE tables, even though it is not recommended. There is no common practice to this, but here is one way of doing just that:Add a module parameter that to the manifest:
group="advanced"> name="is_installed" type="radio" default="0" label="Is module installed?" description="Only use this if you know the consequences! Click No to recreate database"> value="0">No> value="1">Yes> > >
Then you can use the parameter to switch the state. Since the module parameters is already loaded from the database at this point, any overhead should not be noticable this way.
// put this in the module function. function myModuleReInstall() { if (!$params->get('is_installed')) { $database =& JFactory::getDBO(); $query = "CREATE TABLE IF NOT EXISTS `example` ( `id` INT, `data` VARCHAR(100) );"; $database->setQuery($query); $result = $database->query(); $params->set('is_installed', 1); } }
