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.
<?xml version="1.0" encoding="utf-8"?> <install type="module" version="1.5.0"> <!-- Name of the Module --> <name>Hello World - Hello</name> <!-- Name of the Author --> <author>Ambitionality Software LLC</author> <!-- Version Date of the Module --> <creationDate>2008-06-23</creationDate> <!-- Copyright information --> <copyright>All rights reserved by Ambitionality Software LLC 2008.</copyright> <!-- License Information --> <license>GPL 2.0</license> <!-- Author's email address --> <authorEmail>info@ambitionality.com</authorEmail> <!-- Author's website --> <authorUrl>www.ambitionality.com</authorUrl> <!-- Module version number --> <version>1.0.0</version> <!-- Description of what the module does --> <description>Provides a basic "Hello World" notice</description> <!-- Listing of all files that should be installed for the module to function --> <files> <!-- The "module" attribute signifies that this is the main controller file --> <filename module="mod_hello_world">mod_hello_world.php</filename> <filename>index.html</filename> </files> <!-- Optional parameters --> <params /> </install>
/modules/mod_hello_world/mod_hello_world.php:
<?php //don't allow other scripts to grab and execute our file defined('_JEXEC') or die('Direct Access to this location is not allowed.'); ?> <p> Hello World </p>
Hello World
to the final page.
/modules/mod_hello_world/index.html:
<html><body bgcolor="#FFFFFF"></body></html>
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:
<?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
<?xml version="1.0" encoding="utf-8"?> <install type="module" version="1.5.0"> <!-- Name of the Module --> <name>Hello World 2 - Hello</name> <!-- Name of the Author --> <author>Ambitionality Software LLC</author> <!-- Version Date of the Module --> <creationDate>2008-06-23</creationDate> <!-- Copyright information --> <copyright>All rights reserved by Ambitionality Software LLC 2008.</copyright> <!-- License Information --> <license>GPL 2.0</license> <!-- Author's email address --> <authorEmail>info@ambitionality.com</authorEmail> <!-- Author's website --> <authorUrl>www.ambitionality.com</authorUrl> <!-- Module version number --> <version>1.0.0</version> <!-- Description of what the module does --> <description>Provides a random listing of registered users</description> <!-- Listing of all files that should be installed for the module to function --> <files> <!-- The "module" attribute signifies that this is the main controller file --> <filename module="mod_hello_world2">mod_hello_world2.php</filename> <filename>index.html</filename> <filename>helper.php</filename> <filename>tmpl/default.php</filename> <filename>tmpl/index.html</filename> </files> <languages> <!-- Any language files included with the module --> <language tag="en-GB">en-GB.mod_hello_world2.ini</language> </languages> <!-- Optional parameters --> <params> <!-- parameter to allow placement of a module class suffix for the module table / xhtml display --> <param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" /> <!-- just gives us a little room between the previous parameter and the next --> <param name="@spacer" type="spacer" default="" label="" description="" /> <!-- A parameter that allows an administrator to modify the number of users that this module will display --> <param name="usercount" type="text" default="5" label="LABEL USER COUNT" description="DESC USER COUNT" /> </params> </install>
/modules/mod_hello_world2/helper.php:
<?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:
<?php defined('_JEXEC') or die('Restricted access'); // no direct access ?> <?php echo JText::_('RANDOM USERS'); ?> <ul> <?php foreach ($items as $item) { ?> <li> <?php echo JText::sprintf('USER LABEL', $item->name); ?> </li> <?php } ?> </ul>
/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:
<params group="advanced"> <param 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"> <option value="0">No</option> <option value="1">Yes</option> </param> </params>
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); } }
No comments:
Post a Comment