Joomla is a great content management system and once you get to know about the structure of components, modules and plugins you can begin to create your own custom extensions. However, online documentation is pretty sparse when it comes to this part - the most in-depth documentation usually only consists of how to create a 'Hello World' extension.
As a newcomer to the world of Joomla I found this lack of tutorials quite frustrating so I've decided to write my own. The following instructions explain how to create a module from scratch that includes parameters, a third party library and a Google map chart. Once finished we will have a module that displays visitor information on a map of the world using data grabbed from Google Analytics. Hopefully this will shed some light on the topic for some of you.
To start the process you are going to need to have Joomla installed either on your local machine or on a web server. To find out how to do this please follow these instructions or some similar ones.
You will also need to have Google Analytics set up on your site in order to be able to pull data from the Analytics API.
In your FTP client or on your local machine navigate to your site's main directory. From here go to the directory administrator/modules. You will see a list of directories whose titles begin with "mod_". Each one of these folders contains the files for an individual module.
Somewhere on your local machine create a new directory called "mod_analytics".
Open the mod_analytics directory and create two files - 'mod_analytics.xml' and 'mod_analytics.php'. If you're wondering how to do this, one easy way is to right click, create a new "Text Document" and change the extension from .txt to .php or .xml. Create another directory called 'tmpl'.
This xml file is the installation file for the module and it lets Joomla know that the module exists. It contains details of the module's version number, creation date, author, files, folders and parameters. We are going to create a module for the administrator interface of Joomla. For this reason we enter "client='administrator'" in the install type line. Open your empty xml and paste the following:
{codecitation class="brush: xml; gutter: false;" width="74.923em"}
<?xml version="1.0" encoding="utf-8"?>
<install type="module" client="administrator" version="1.5.0">
<name>Analytics</name>
<author>Your name or your company name</author>
<creationDate>May 2010</creationDate>
<copyright>Copyright (C) 2005 - 2010 Open Source Matters. All rights reserved.</copyright>
<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
<authorEmail>your email</authorEmail>
<authorUrl>freakedout</authorUrl>
<version>1.0</version>
<description>Allows you to display a Google Analytics visitor map in your admin interface</description>
<files>
<filename module="mod_analytics">mod_analytics.php</filename>
<folder module="mod_analytics">tmpl</folder>
</files>
</install>
{/codecitation}
Open the other file you created - mod_analytics.php. This is the next file that Joomla reads after the xml file and is the "entry" into the module. Paste the following into this file.
{codecitation class="brush:php; gutter:false;" width="74.923em"}
<?php
// no direct access
defined('_JEXEC') or die('Restricted access');
require(JModuleHelper::getLayoutPath('mod_analytics'));
{/codecitation}
The first line of code here, "defined...", is a standard line of code that ensures that the code is called through Joomla! instead of being accessed directly at ...administrator/modules/mod_analytics/mod_analytics.php.
The second line uses a built in function in Joomla called JModuleHelper that gets the path to the layout file for the module. We have not yet created this layout file. This is the next step.
Open the "tmpl" directory and create a file called "default.php" and paste the following.
{codecitation class="brush:php; gutter:false;" width="74.923em"}
<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
echo '<table class="adminlist">This is some text that we are going to display</table>';
{/codecitation}
You have now finished setting up the basic structure for a module. Zip the folder mod_analytics.
Once you have zipped the folder you are ready to install your module. For details on how to install a module please see the following tutorial.
Now that the module is installed you will see it in the Administrator part of the Modules list. Open it up and set it to display in the "icon" position. This position is located on the "Control Panel" of the Joomla administrator interface.
Now go to the Control Panel and you should see something similar to the following screenshot.
We have a working module that displays some text. This is usually where most tutorials end but not this one!