How to write a Joomla! 1.5 module.
A Joomla! module is a simple extension to Joomla!. Many modules are display only or have limited interaction with a user. For more complex extensions or interactions then Joomla! plugins or components are more appropriate. In this post I’ll describe the basics of module development as I understand them.
Written in PHP, at their simplest a module only requires two files, one containing configuration information and the other code. In the best tradition of programming I’ll use a “Hello World” example to demonstrate.
Under the root of your Joomla! installation you will see a directory called modules, unsurprisingly this is where modules are installed to. Each module requires a unique name and although it is not required to be adhered to , a naming convention is in place which notes the module name should begin with “mod_” to denote module, components begin with “com_” (in the component directory) but oddly plugins do not seem to have a naming convention.
I’ll call my module “mod_briaskHello”. Joomla! expects the configuration file to be named the same as the name as the module and the configuration file is XML so I’ll create a file called mod_briaskHello.xml. The configurtaion file can also be considered the installation file as it is this file that Joomla! reads when it is installing the module. The module will be installed into the “mod_briaskHello” directory under the main modules directory.
Although any text editor can be used to create the file, I tend to use Notepad++ . The contents of the file should be as follows:
<?xml version=”1.0″ encoding=”UTF-8″?>
<install type=”module” version=”1.5.0″ >
<name>mod_briaskHello</name>
<author>Briask</author>
<creationDate>May 2008</creationDate>
<copyright></copyright>
<license>GNU GPL</license>
<authorEmail>briask@briask.com</authorEmail>
<authorUrl>http://www.briask.com</authorUrl>
<version>1.0</version>
<description>A HelloWorld example</description>
<files>
<filename module=”mod_briaskHello”>mod_briaskHello.php</filename>
</files>
<params>
<param name=”moduleclass_sfx” type=”text” default=”" label=”Module Class Suffix” description=”PARAMMODULECLASSSUFFIX” />
</params>
</install>
You will need to change the various elements to suit your own details, the following are purely descriptive elements and have no effect on the operation of the module name, author, creationDate, copyright, license, authorEmail, authorUrl, version, description.
The install element and associated attributes type and version detail the type of Joomla! extension (module, component, plugin) and the version of Joomla! that the module is compatible with 1.5.0 meaning J! 1.5 and above
The files element and its child filename elements detail the files that make up the module and will ensure that they are copied to the modules directory. The filename element attribute module indicates the module this file is associated with and the value of the element indicates the actual filename. In the example config file above the module is noted as being “mod_briaskHello” and the file to be installed is called mod_briaskHello.php.
The params element is used to detail the parameters associated with a module, can specify types of parameter, sizes etc. I’ll cover those in a post on more detailed module development. The parameter in the example listed is that for adding the “Module Class Suffix” to a module.
Next we need to create the mod_briaskHello.php file. As a default template the file needs to contain
<?php
/*
* Any comments or copyright(left) or licensing details
*/
defined(’_JEXEC’) or die (’Direct Access is not allowed’);
?>
The defined(’_JEXEC’) or die (”Direct Access is not allowed’); line should be included as the first line of code to be executed in all modules as it helps to ensure that the module will only be called by Joomla! and not bay any nasty hacker type code.
Now for the exciting part! Add the line ” echo JText::_(’Hello World!’);” after the “defined” statement. When executed that line will output Hello World . The _ method of JText hooks into the translation services that can be installed with J!.
Now that the code is written, it needs to be installed into Joomla! To this we need to create a ZIP file that the Joomla! extension manager can read and use to install the module. Use your favourite compression tool to create the zip file and ensure it is named the same as the module, in this case the file would be named mod_briaskHello.zip. Now just follow the usual steps in Joomla! for installing a module and you’ve written/installed your first Joomla! module. You should see that the module appears in the list of modules and that on the filesystem of your server a new subdirectory of the modules directory has been created for this new module.
Have fun!
ImageSlideShow for Joomla! 1.5.x
ImageSlideShow is now feature complete. Well, it is as complete as I’m going to make it for the moment.
It can be downloaded from here.
What is ImageSlideShow?
ImageSlideShow is a simple Joomla! module written in PHP and Javascript. The module displays a sequence of images from a specified directory either in order or in a random order. The slideshow has a simple transition between each image, the timing of which can be specified. ImageSlideShow also has the ability to create “thumbnail” versions of the images and to use them in the slideshow.
It is/was a project for me to learn PHP & JavaScript. Also proved useful in learning the framework behind Joomla 1.5 and generally how programming for the “web” world differs from my normal C# development efforts.
Image Slide Show and resizing images.
Finally got the finger out and got around to implementing fully the resizing capability for ImageSlideShow. It is on view and in test on the demo site here. I still need to spend some time testing / tweaking it, just to make sure all is ok and that I can provide reasonably simple instructions on how to make it work.
Should be able to release it on the Joomla! extension site in the next few days. I will need to write up some instructions on how to configure it as it is not as straightforward as the rest of ISS.
Once it is released, I think I’ll actually get down to writing up a tutorial on how ISS actually works, walking through the PHP and Javascript required to allow it to do what it actually does. ISS has served me well in learning about PHP and Javascript which was the original intent, so it seems good to wrap it up by revealing how it works.
The question then becomes what to look at next… am toying around with taking some extensions which work on J! 1.x but have no current owner/updater and see what I can do with them. I do also want to get to grips with MySQL and CSS so maybe I’ll go in that direction. Maybe I take this site from being a WordPress blog and actually put it on Joomla! 1.5. Maybe Drupal is worth a look? We’ll see…
Maybe I’ll also get around to organising this site so it actually makes sense! and that people can actually easily find the download for ISS, just noticed I couldn’t find it myself! If you are looking for the current version it is here.
Joomla! and more Music I Like
Came across this guy today as I was looking for some more music to relax the brain while I struggled with real world work. Seriously though I have to get back to ImageSlideShow and complete its functionality, still have not released the resize capability which I think would round it off nicely, not too sure if I will bother with releasing the plugin version, the prototype works fine but kinda hard to figure out a good usage pattern for it.
I still want to create a simple tutorial on how to write Joomla! modules for 1.5 but trying to figure out the most effective medium, probably a combination of webpages, video and sample code works best.
Anyways, back to the music, Andy Mckee is the guys name, plays guitar and make some wonderful music while doing so. Have a listen to him here and enjoy!
Briask- Minor update to ImageSlideShow
- OK Computer! Just start already…
- What a to-do about what to do!
- Final Fantasy - take a listen.
- Return from Vacation!
- How to write a Joomla! 1.5 module.
- ImageSlideShow for Joomla! 1.5.x
- Image Slide Show and resizing images.
- Joomla! and more Music I Like
- Bug fixing for ImageSlideShow