Page 1 of 2
A simple module is the easiest way to get started with Joomla 1.5 development.
The simplest of the Joomla 1.5 additions is the module.
It's not just that modules are in some sense a simpler form of component invented to save time and effort - they each serve very distinct purposes.
A module can be loaded into a specific location specified by the template and a component can be associated with a menu option. You could say that a component is integrated into the menu structure of a Joomla site and modules make up the page furniture of a typical page - but there are exceptions to this simplification in that a component or a module doesn't actually have to appear anywhere within your website and it can still be doing a useful job.
However this said - if you want something to display on most pages in a specified location then you want to create a module but if you want something only to appear when the user selects a menu option or on the front page then you need a component.
From a more technical point of view the difference comes down to how the they are invoked. A module is loaded by the framework while a page is being constructed according to a set of specifications which determine if the module should be loaded for that particular page. A component on the other hand is always loaded as a result of a specification carried in the URL that caused the page to load.
The way that modules are invoked and placed on the page also makes it reasonable to create multiple instances of a module within the site and even on a single page. Each instance of the module can be customised to show something different by setting its parameters withing the administrative backend. Components on the other hand tend to be singleton implementations - that is there is generally no more than on instance of a component within a site. However, this said modules and components are flexible and I'm sure you can find ways of using them that break these guidelines!
In A Joomla Component with PHP and Eclipse how to create a basic "Hello World" example component is explained in detail. In this article the same format and approach is used to build a module.
It is assumed that you already have a development Joomla system set-up, possibly remotely or even virtual. It is important that you can easily restore this system after making a mess of it and certainly don't develop anything using a live or otherwise important site as your victim.
It is also assumed that you have a copy of Eclipse for PHP set up and you have imported your Joomla test site as a project and that you can use the IDE to test and debug your PHP code.
The basic idea is to first set up a zip file that acts as the Joomla installer for a dummy module, install the module to the test Joomla site, use the code files installed to develop the module and then copy the changed files back to the installation zip ready to install on a production site when everything is working.
This approach isn't the simplest or minimal work but it means that you always have a complete installation ready to use and test.
A minimal module
The first job is to create a PHP project for the module.
Start Eclipse and load the main Joomla project (if it isn't already in your workspace). Outside of Eclipse create a directory to act as the root of the project - you can call it whatever you like as its name doesn't find its way into the installation - but it is usual to give it the name the name of the component, in this case mymodule.
Next use Eclipse to create a project based on this "existing" project using File,New PHP Project and create the project from existing source - once again you can give the project any name you like but it is reasonable to use the component's name.
Alternatively you could simply create the project in the Eclipse workspace but it is sometimes better to keep the project files in another location away from the workspace.
Creating the XML file
First we have to consider the XML file which describes all of the other files in the Joomla module and their locations. - i.e. it acts as a manifest.
Using Eclipse you can create the XML file which describes the module and its folders and files to build a module installation.
Create an XML file and give it the same name as the module - mod_mymodule in this example. The file starts with some very obvious basic information which is just there to help other programmers:
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
Notice the <install> tag that specifies that this is a module rather than a component or a plug-in that we are installing. Notice also that module files all start with mod_.
The basic files
A module can have many files organised into many subdirectories as indicated by the XML file but only one is really needed - the entry point. This is a file called mod_mymodule.php and is the default main entry point for the module in the sense that it’s the PHP file loaded first.
In a more complete module there would be other files - generally a helper PHP file that works with the data and a template PHP file that generates the HTML from the data. This is a sort of lightweight MVC architecture but for getting started and for some very simple modules it is unnecessary.
All we need is the one main module file mod_mymodule.php and a blank HTML file that is loaded if a user browses to the directory directly.
These two files and the XML file itself have to be specified in the XML file: