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!
Comments
4 Responses to “How to write a Joomla! 1.5 module.”
Leave a Reply
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!
Hi Briask,
I like the new look!
Thanks for the Module tutorial, I hope to find time soon to try my hand at authoring an extension, and this will really help me get started in the right direction.
Hi Briask,
I see you are a brisk developer too, keen on Joomla, which I think is terrific.
I just wondered whether you welcome people like me coming to you time and again asking you questions to enhance our knowledge of making Joomla productive and acting the way we would like and want.
Essentially, HOW-TOs, because I have upteen things especially how to position Joomla’s modules to output in given positions in a template.
And templates can differently designed, so what is the defacto that Joomla sees and works with, or is there some way a template designer imparts the positions used in his/her template so they can then be referenced and out accordingly.
These are important questions, especially as I get into manipulating Joomla 1.5 templates, customising them.
Hope tohear from you soon.
Kind regards,
James.
If you want to ask me questions directly then email me directly at briask@briask.com.
hello Briask,
Thanks for the Module tutorial.I read your tutorial and learn it. I’m going to start writing My first module Now.
best Regards