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 at 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 - Issue, publishing ISS module multiple times on Joomla 1.5
Quite a number of people have asked if it is possible to publish mutiple copies of the ImageSlideshow on one Joomla 1.5 page. The answer is, unfortunately, no. Well, not just yet…
To be honest, when the first query came in I thought that it would be very quick and simple to code, but no! it is not.
The problem is, ISS needs to remember which image is being displayed, which image list to use, which image is next in rotation and how to smoothly transition between the two images on the Joomla page etc.
With only one ISS module published you can get away with relatively poor coding but when you start to allow the possbility of 2 or unlimited copies then keeping track of where you are in the sequence becomes more problematic and you can’t really resolve it with poor coding practice.
So this turns out to be a very good coding exercise and precisely what I needed to enable me to learn more about PHP, Javascript and Joomla 1.5 . The resolution is being worked on, I will resolve it and when it is ready it will be published it here and I will update the Joomla extensions site.
As for the other requests, I have finished coding the ability for links, titles, random display of images, resizing images and even the generation of image thumbnails but I am not going to publish that until I can include the resolution to the multiple copies issue.
Image slideshow and Google Analytics
Have to say that pushing Image Slideshow up onto the Joomla! extensions site was an interesting exercise, didn’t think it was quite ready but as I had just updated this site with a new plaything… Google Analytics, I wanted to see what would happen.
As much as I love and hate Google, they are the biggest web search engine around and have free and interesting tools to see what is happening with your website. Lots of interesting statistics which I have yet to understand the meaning behind but one simple one was very interesting.
60% of the people who came to the site use FireFox, 30% on IE, the other 10% on Opera, Safari and Mozilla and some other obscure or niche browsers. I know the audience for J! is kinda skewed towards the technical types like myself but a 2:1 in favour of Firefox was a little surprising to me… or maybe I just need to get out more!
Joomla 1.5 Rotating Image SlideShow module
Finally got my act together and got the Joomla 1.5 slideshow module up and running.
Will be writing up a tutorial on how to develop this type of module for Joomla 1.5. Follows the usual J! 1.5 install process and has parameter that can be changed to suit your need.
Works fine with IE 7 and FireFox 2. Don’t have IE6 to test with so if any problems are found please email me at briask@briask.com
Written in PHP and Javascript, it has proved to be a nice introduction to programming in those languages
PHP and JavaScript - books and first impressions
JavaScript: The Definitive Guide
Professional Joomla! (Programmer to Programmer)
are the first books I’ve bought to help me get started coding.
Haven’t had a detailed read yet, but the O’Reilly “The Definitive Guide” series have served me well in the non-web world so should be good here too.
Have been playing with the simple examples in the first chapters of each book,just to get familar with the coding and looks like there is nothing too odd from a structure or logic point of view. Dealing with HTML and the webworld may hold some surprises but haven’t gotten that far yet.
Of course to actually play with PHP, MySQL, and JavaScript you need to have a webserver and MySQL installed. Turns out this are really simple and easy to install on your own machine. Will write up my experiences of those soon.
Briask- How to edit a Joomla template to publish a module in a new position.
- End of life announced for Joomla 1.0.x
- Interesting point from xkcd
- Change in support method
- How to publish multiple copies of ImageSlideShow
- 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!