Creating Mambo Components

Submitted by moxley on Wed, 2006-01-11 04:51

Creating Mambo Components

This is just an incomplete outline so far. I might finish it when I have the time. For more information about creating Mambo Components, go download a component and examine it. There are many components at Mambo Extensions Directory

Mambo Open Source is a Content Management System (CMS) that runs on PHP. More information on Mambo can be found at www.mambo-foundation.org/. This tutorial will show you how to create a simple Mambo Component. We will be creating an email list of people interesting in receiving newsletters and notifications from your web site.

Mambo Components

A component is a miniature application that can be plugged into Mambo. It may have functional parts on the administrative and public sides of a Mambo-powered web site.

Component Development Strategy

Fortunately, there's a standard way of developing Mambo components so development and testing of components is relatively easy. You will create a directory to store all the working development files for your component. We will call this your component's development directory.

Within your development directory you will create and maintain an XML file that will let Mambo know how to install and integrate your component into Mambo. You will install your component for testing by using Mambo's component installation function available from Mambo's administration interface.

A Sample Email List Component

Let's start our sample component-- an Email List Component, or EList for short. The Email List Component will take email addresses from the Mambo-powered web site, and allow the administrator to browse the list, and edit and delete entries from the list.

Create the Component's Installation File

The installation file is an XML file that lets Mambo know how your component is organized, which it uses to install and integrate the component into Mambo.


  <?xml version="1.0" ?>

    <mosinstall type="component">

    <name>EList</name>


    <creationDate>21/12/2003</creationDate>

    <author>Moxley Stratton</author>

    <copyright>This component in released under the 
	GNU/GPL License</copyright>

    <authorEmail>moxley@moxleydata.com</authorEmail>


    <authorUrl>http://www.moxleydata.com/</authorUrl>

    <version>0.1</version>

    <files>

    <filename>elist.php</filename>


    </files>

    <install>

    <queries>

    <query>DROP TABLE IF EXISTS `mos_elist`;</query>

    <query>CREATE TABLE `mos_elist` (


    `id` INT NOT NULL AUTO_INCREMENT,

    `addr` VARCHAR(30),

    `dateadded` DATETIME,

    PRIMARY KEY (`id`)

    )

    </query>


    </queries>

    </install>

    

    <administration>

    <menu>Email List</menu>

    <submenu>


    <menu act="all">Show List</menu>

    </submenu>

    <files>

    <filename>admin.elist.php</filename>


    <filename>admin.elist.html.php</filename>

    </files>

    </administration>

    </mosinstall>

Create the Component's Public Interface

Edit a new file called elist.php and enter the following HTML form definition:

elist.php


<?php



    switch( $task ) {



        case 'add':


            doAdd();




            break;


        default:


            doForm();




    }




function doHead()


{


    print "<h2>Email List</h2>\n";




}




function doForm()


{


    doHead();


?>



<!-- begin EList 'add email' form -->


<form method="post" action="index.php">


<input type="hidden" name="option" value="com_elist">


<input type="hidden" name="task" value="add">


<p>Please enter your email address here



to receive news and updates:



<input type="text" name="addr" value="">


<input type="submit" value="submit">


</p>


</form>


<?php


}






function doAdd()


{


    doHead();


?>



<div>Thank you for submitting your email address.</div>



<?php


}


?>

The form submits to index.php, which is the script to submit to for public forms. By setting the option form field to elist, you let Mambo know that it should send the request to the EList component. The task hidden form field tells the EList component what task to perform: Add an email address to the email list.

Creating Component Administration Controls

It is helpful to familiarize yourself with MVC theory to better understand the organization of the administrative component controls. The important concept to remember is that Mambo encourages component developers to separate their component's logic from the component's presentation. For example when a user submits his email address, the PHP script that adds the email address to the database should be separate from the PHP+HTML that displays the next page following the action. Or, for another example, think of when the Mambo administrator chooses to browse the list of email addresses that have been collected. The code that retrieves the list of email addresses from the database should be separate from the code that actually displays them. This separation is so important that the creators of Mambo recommend that you keep your component's logic and presentation in separate files.

Our component will have two files that will contain the code for the administration controls.

Here's the first file, admin.elist.php:

admin.elist.php


<?php





/** admin.elist.php


*/


// ensure this file is being included by a parent file


defined( '_VALID_MOS' ) or die( 'Direct Access to this location is not allowed.' );





global $blankEntry;



$blankEntry = array(


    'id' => 0,



    'addr' => '',



    'dateadded' => ''


);





switch( $act ) {


    case 'new':



        doNew();



        break;


    case 'edit':



        doEdit();



        break;


    case 'list':



    default:



        doList();


        break;



}




function doList()



{


    $list = array(


        'email1@example.com',



        'email2@example.com',



        'email3@example.com',


        'email4@example.com'



    );



    $view = 'list';


    include("admin.elist.html.php");



}





function doNew() {


    global $blankEntry;


    $entry = $blankEntry;




    $view = 'new';


    include("admin.elist.html.php");


}





function doEdit() {



    $entry = array(


        'id' => 101,



        'addr' => 'email1@example.com',



        'dateadded' => 1072068500



    );


    $view = 'edit';



    include("admin.elist.html.php");



}




?>

admin.elist.html.php:

<?php if( $view == 'list' ) { print "<h3>Email Addresses</h3>\n"; if( !$list ) { print "<div>No records found</div>\n"; } else { foreach($list as $addr) { print "<div>$addr</div>\n"; } } return; } else if( $view == 'edit' || $view == 'new' ) { if( $view == 'new' ) { $newAct = 'add'; $btnLabel = 'Add'; $title = 'Add New Address'; } else { $newAct = 'update'; $btnLabel = 'Update'; $title = 'Edit Entry'; } ?> <div style="align: center"> <h3><?php print($title); ?></h3> <form method="post" action="index2.php"> <input type="hidden" name="id" value="<?php print($entry['id']); ?>"> <input type="hidden" name="act" value="<?php print($newAct); ?>"> <table> <tr> <td>Address:</td> <td><input type="text" name="addr" value="<?php print $entry['addr']; ?>"></td> </tr> <?php if( $view == 'edit' ) { ?> <tr> <td>Date Added:</td> <td><?php print(date("Y-m-d", $entry['dateadded'])); ?></td> </tr> <?php } ?> </table> <input type="submit" value="<?php print($btnLabel) ?>"> </form> </div> <?php } ?>

Save these files in a directory, and zip the directory. Then, go to the Install/Uninstall Components page in the Mambo administration area. Browse and then upload your zip file

After installing the component, locate the component in the Components menu and try it out.

Next, use the Site Menu Manager to add the public interface to the web site.

Mambo's PHP API

The Mambo API functions names all begin with 'mos'. Reference information on the API may be found here.

Mambo's HTTP API

These are the Mambo-recognized HTTP request parameters.

parameter	required	definition
option	Y	For each request, Mambo determines which component to handle the request by looking at the 'option' request parameter. If the value of the option starts with 'com_', then option is referring to a component. For our example, the option would be "com_elist".
Itemid	N
task	N	Specifies which component's public actions should be called.
act	N	Specifies which component's administrative actions should be called.
id	N	id refers to a primary of a database record
section
momsg	N	A message to be displayed
no_html