This tutorial will help you create a simple module, and should help you on the way to creating much more powerful modules in no time. I will only cover the basics here, and this should be in now way considered as powerful as you can get.
For the purposes of this tutorial, we will build a module called hello_world, that runs in conjunction with a component of the same name that has already been installed. In a normal module, there are 2 files needed to get it to install and run correctly. The installer file hello_world.xml and the module itself, mod_hello_world.php.
The code for your hello_world.xml file should look like:
<?xml version="1.0" ?> <mosinstall type="module"> <name>hello_world</name> <creationDate>04/14/2004</creationDate> <author>Doyle Lewis</author> <copyright>Released under GNU/GPL License</copyright> <authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authorEmail> <authorUrl>www.mambo-hosting.com</authorUrl> <version>1.0</version> <description>Module to display "Hello World."</description> <files> <filename module="mod_hello_world">mod_hello_world.php</filename> </files> </mosinstall>
Now let's break down what the important lines do:
<?xml version="1.0" ?> This is the xml opening container. You will need to place it at the beginning of any xml file
<mosinstall type="module"> This tells Mambo that what is being installed is indeed a module.
<copyright>Released under GNU/GPL License</copyright> It is important to let users know what license your module is released under. Be sure to research licenses so you know what you are allowing people to do or not do with your module.
<description>Module to display "Hello World."</description> This lets people know what your module should do at a glance.
<files> <filename module="mod_hello_world">mod_hello_world.php</filename> </files> This is very important. This tells Mambo what your main module file will be, and any other files you would like installed as well.
</mosinstall> This will always be the last line of the xml file. It closes out the installer.
Now let's take a look at our mod_hello_world.php file. This calls from the database where there is a 2 column table consisting of `id` and `text`:
<?php //hello_world Module// /** * Content code * @package hello_world * @Copyright (C) 2004 Doyle Lewis * @ All rights reserved * @ hello_world is Free Software * @ Released under GNU/GPL License : http://www.gnu.org/copyleft/gpl.html * @version 1.0 **/
defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );
global $database; $query = "SELECT * FROM jos_hello_world LIMIT 1"; $database->setQuery( $query ); $rows = $database->loadObjectList(); $row = $rows[0];
echo $row->text;
?>
Let's break it down:
defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' ); This is the most important line you will ever use in your Mambo development. This will keep people from accessing it from outside Mambo.
global $database; $database is a Mambo variable which, suprisingly enough, holds the database information. This sets it as a global variable so you can use it throughout your module. You will want to do this anytime you use the database.
$query = "SELECT * FROM jos_hello_world LIMIT 1"; $database->setQuery( $query ); This defines your query, and then tells the database which query to run. IMPORTANT NOTE: This does not actually run the query. Just having this line will not yield any results.
$rows = $database->loadObjectList(); This is the line that runs the query and loads the results into an array.
$row = $rows[0]; This sets the variable to just the first row. It still contains all values for the row.
echo $row->text; This tells Mambo to display the column `text` from your row. `text` in this case is set to "Hello World" so we will achieve our desired output.
So this is a simple module using some basic API from Mambo. For more information on the $database variable, check out classes/mambo.php. You will learn a wealth of knowledge from this one file. My next tutorial will be how to build the basic component to get this information into the database.
Please note that The author or Mambohut shall not be held liable for any damages or losses caused by the code listed here.
