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 spam bots, 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 mos_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 mos_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.
Comments
Written by Guest on 2004-04-15 11:18:02Thanks.. waiting for the next tutorial.
Written by Guest on 2004-04-15 14:16:09Thanx, man...it sure is a good start!
very nice Written by Guest on 2004-04-15 14:52:33good little tutorial.
very nice Written by Guest on 2004-04-15 14:52:49good little tutorial.
thank you and hope to see more Written by Guest on 2004-04-15 19:56:05thanks that was very helpful for beginner like myself
Error in hello_world.xml Written by Guest on 2004-04-16 03:43:32Good tutorial! But, there is an error in hello_world.xml file:
instead of: mod_hello_world.php
it should be: mod_hello_world.php
Maybe it would also be good to mention explicitely to create a table mos_hello_world with integer field 'id' and varchar field 'text' in the mambo database.
And, thanks for a tutorial!
Error (2nd try): Written by Guest on 2004-04-16 03:46:38I've forgotten about formatting...
So, instead of: filename module="hello_world"
it should be: filename module="mod_hello_world"
in hello_world.xml file!
Written by MamboHosting on 2004-04-16 10:58:31You make a good point, I will make the appropriate changes. I am currently working on the component tutorial, and this will setup the database. Look for it this weekend.
How to install Written by Guest on 2004-04-23 04:10:09I tried something similar, but it says there is no installer file. Why is that?
What if I just want to call a simple 'include' statement, and use a module to do it? Is it the same procedure?
but what about... Written by Guest on 2004-04-30 05:47:57parameters, would be really nice to see a simple introduction as I cannot find a good guide anywhere.
I don't get it... Written by Guest on 2004-05-11 15:44:23 Argh! I am missing something important, I guess...
How does one install a component that one has created? I'm trying the most basic things and nothing is working.
Do you have to have a component of the same name already installed to get a module installed?
For example, I wanted to create a REALLY simple "hello world" module -- one that just echoes "Hello World" to the screen.
How do I do that???
I have tried submitting the xml file through the administrative interface in MOS but it doesn't work, I get no errors, and I have no idea if I am even close to correct.
I am a fairly advanced PHP programmer, so the PHP part is not a problem. The MOS API is the problem -- there is not enough documentation!
Any help from anyone would be great!
-Jeff S.
This email address is being protected from spam bots, you need Javascript enabled to view it
Oops. PHP was stripped out of my comment Written by Guest on 2004-05-11 15:46:41My "really simple" hello world script was as follows:
BEGIN_PHP
echo "Hello World";
END_PHP
Sorry about that! -Jeff S
This email address is being protected from spam bots, you need Javascript enabled to view it
php Written by Guest on 2004-05-12 07:26:38 php is the best language programation.
godar Written by Guest on 2004-05-17 05:45:20great tute thanks! I have a tute on using module parameters here
ere Written by Guest on 2004-06-01 22:30:56rerere
Fred Aguiar Teixeira Written by Guest on 2004-06-11 13:27:57How to install a mambo component. in your computer, add all these files in a zip file login as administrator in your mambo website go to menu component and hit install/uninstall. A list of all components installed will be shown go to the bottom of the page at "Upload new component", locate your zipped file and upload it again, go to menu component and hit install/uninstall. You will see your new component displayed in the list check in your web site. there will have some files installed under /components/com_hello_world and /administrator/components/com_hello_world. Besides that, you can check do a query to check out the component table: "select * from mos_components;"
Confused Written by Guest on 2004-06-21 13:24:29You talked about how make a module, but not really what it is? What is it's purpose in mambo. I've been through your component tutorial and have been trying to get my custom component to install correctely. I've got a PC and a MAC, I should note that the Mambo System has flaws if you are on mac like things not refreshing correctely etc, so I've been using my PC but regardless help me understand what a module is.
Written by Guest on 2004-06-29 04:12:41Components are shown in main area of your website while modules offer content on the left or right side.
PHP Include Written by Guest on 2004-07-26 14:21:48I have a photo gallery thats in PHP and I would like to add it to my current Mambo Template. Is there an easy way I can do a php Include to get it to display on my page? or is there an easy way to create a module and have the module do a PHP include so my Photo Gallery will be displayed within my template?
the $content variable Written by Guest on 2004-07-26 21:38:26I noticed that in some modules, rather than use 'echo' to display the variable (as in your really helpful tutorial), they assign the text to the $content variable. Does Mambo look for and display $content by default?
$content Written by mambohosting on 2004-09-17 16:17:49Been a while since I've been in here. You still have to echo $content if you use it. Say you are trying to bring in serveral items to show. You want to have a sentence "Hello Doyle, welcome back." where "Doyle" is stored in a database.
You can use $content to put it all together.
$name = "Doyle"; (you would get this from a database)
echo $content; (Would return the sentence we built.)
You wouldn't normally use it for something this easy, but this was just an illustration. It comes in very handy when building text to write to a file.
My Hello world show text...... Written by zbnb on 2005-04-25 02:13:18 i already uploaded the helloWorld component but once i click on show text the code inside my admin.hello_world.php file were shown....was it normal? i mean is that it? plz sumone help me...im a beginner..
Problem with installing module Written by Guest on 2005-08-07 14:26:34I try to install a component/module using a zipfile. Login as administrator and so on. This is the result
Upload component - Upload Failed ERROR: Could not find an XML setup file in the package. [ Continue ... ] Upload component - Failed Installation file not found: /
Can so help me please
RE: Problem with installing module Written by bogho on 2005-09-15 04:49:48I solved this kind of problem by creating on site a directory "toinstall" and in this directory I copied the php and xml files. That from the administration panel, on install new module i write the entire path to this directory ( /home/sites/my_site/toinstall/ ) "Install from directory" text field. than click on the Install button and all its ok.
Only registered users can write comments. Please login or register.
Argh! I am missing something important, I guess... 
php is the best language programation.
i already uploaded the helloWorld component but once i click on show text the code inside my admin.hello_world.php file were shown....was it normal? i mean is that it? plz sumone help me...im a beginner.. 
