Access Keys:
Skip to content (Access Key - 0)
Home (Access Key - 1)
All spaces... (Access Key - 3)
Log in (Access Key - 5)
Sign up (Access Key - 6)
Development

Mambo Manual is part of the documentation project for the Mambo open source content management system
Toggle Sidebar

Create a Component

Walkthrough on how to create a component

Warning

This article was written for Mambo 4.5 which is no longer developed.
For Mambo 4.6 see Hello World Component for Developers

Throughout this article, I'll use 'newcomp' to represent the component name which should be replaced by your own component name, and 'installdir' as the Mambo base installation directory.

I will start by explaining the basic files required to build a component. These files are grouped according to where they are used/viewed:

    * Frontend files

     newcomp.php

    * Administration files

admin.newcomp.php toolbar.newcomp.php

    * Installation files

newcomp.xml

Frontend files

Files in this group are used to display a component to website visitors. Meaning if you link a component to a menu item (using Menu -> Main Menu -> New -> Component), these files control what people see when they click on that menu (and subsequently to any links or buttons displayed by your component).

All front end files must have the following line to prevent being loaded directly in the browser.

<?php
/** ensure this file is being included by a parent file */
defined('_VALID_MOS') or die('Direct Access to this location is not allowed.');
?>

newcomp.php
This is the default file loaded by Mambo to display a component. You can have something as simple as displaying data from text file or database, or a switch statement that calls different functions according to what user choose.

A simple switch statement can look like this:

      <?php
      switch($task) {
          case 'show_form':
              // Display a form
              break;
          case 'save':
              // Save data from the submitted form
              break;
          default:
              // Perhaps display some data, etc
              break;
      }
      ?>

Where does $task variable come from? You need to define it in your form (as hidden variable) or include it in links so it can be sent to the server. You can use any variable name but 'task' is kind of the standard used in most of the components. Other variables that you need to pass to the server are $option (directory name of your component, e.g. com_newcomp) and $Itemid (menu ID of your component). Variable $Itemid is used to generate pathway and highlight the active menu. If you remove it from the URL, the page is still loading correctly but none of the menu is highlighted and pathway is not displayed correctly.

In this page you can also use $mainframe and $database objects to get configuration values, get information of the logged in user, run queries, etc.

Mambo's common convention used for class name is HTML_newcomp. There is no need to create a constructor function because we won't create an instance for this class.

<?php
      class HTML_newcomp {
          function displayForm() {
              // Print form here
          }

          function displayData($db_result) {
              // Print query result in a nice table, etc
          }
      }
      ?>

All forms must be submitted to index.php. You can use sefRelToAbs() function to convert a URL into search engine friendly form.

<?php

      echo '<form method="POST" action="'. sefRelToAbs("index.php?option=$option&Itemid=$Itemid").'">';

      ?>

So how do we link these files? $mainframe object provides function called getPath() to do this easily. Just add the following line to newcomp.php.

<?php
// Load the HTML class
require_once($mainframe->getPath('front_html'));
?>

The string 'front_html' is Mambo predefined key to load newcomp.html.php file. There are other keys available which I'll explain later. For the complete list of getPath keys and where Mambo looks for the files, please refer to Appendix B.

Now we can call the above functions from newcomp.php as follows:

<?php
HTML_newcomp::displayForm();
HTML_newcomp::displayResult();
?>

Administration files

Files in this group are used to display your component to Mambo administrator. This means you will access these files through Administration page.

All files must have the following lines to prevent being loaded directly in the browser and to kick out unauthorised users.

<?php
// ensure this file is being included by a parent file
defined('_VALID_MOS') or die('Direct Access to this location is not allowed.');

// ensure user has access to this function
if (!($acl->acl_check('administration', 'edit', 'users', $my->usertype, 'components', 'all') || $acl->acl_check('administration',
'edit', 'users', $my->usertype, 'components', 'com_dailymessage'))) {
    mosRedirect('index2.php', _NOT_AUTH);
}
?>

admin.newcomp.php and toolbar.comname.php are loaded in the administration page. Files that end with .html.php are not displayed but rather included as utility files. It's a bit difficult to explain these files separately so I'll briefly introduce them and later explain how they all related to each other. Administration page

    * admin.newcomp.php

Contains the 'switchboard' to decide what action to execute based on the selected menu and task buttons (Add, Delete, etc)

    * admin.newcomp.html.php (optional)

Contains class to print HTML codes (display forms, tables, etc)

    * toolbar.newcomp.php

Contains the 'switchboard' to decide which task buttons to display based on the selected menu and currently selected task

    * toolbar.newcomp.html.php (optional)

Contains class to print the buttons

I guess it is best to learn by example so let's assume that our component, My Component, has 2 submenus, Config and Manage Items. Config is to change global settings of the component and Manage Items is to add/delete some data from the database. I need to define these submenus in the installation XML file as follows: (XML file structure will be explained later)

<?xml version="1.0" ?>
<mosinstall>
    <administration>
        <submenu>
            <menu act="config">Config</menu>
            <menu act="manage">Manage Items</menu>
        </submenu>
    </administration>
</mosinstall>

Attribute 'act' describes what is the main action that we want to perform. As we will see later, we can specifiy more specific task to be done for each action. If we were to scribble our menu design so far, this is what we have:

act: Config (config) act: Manage Items (manage)

When I select Config menu, I want to be presented with a form pre-filled with configuration values and have a button to save the data if I make any changes to the configuration. We are going to write this requirement as follows:

act: Config (config) task: default View configuration form Buttons: Save (save)

act: Manage Items (manage)

'task: default' means it is the default task to do when I click Config menu. What happens when I click the 'Save' button? The form should be submitted and the data saved to the database. Then I want to see the form again with the updated values.

act: Config (config) task: save Save form data to the database View configuration form Buttons: Save (save) task: default View configuration form Buttons: Save (save)

act: Manage Items (manage)

That's all we need for Config menu. Now we'll take a look at Manage Items. By default I want to see the list of items I have in the database, a button to add new item, and another to delete items.

act: Config (config) task: save Save settings to the database View configuration form Buttons: Save (save) task: default View configuration form Buttons: Save (save)

act: Manage Items (manage) task: default View list of items with checkboxes on the left Buttons: Add (add), Delete (delete)

When I click the 'Add' button I want to see a form to add new item and a 'Save' button, while clicking on 'Delete' will delete the items I selected and show me the updated list of items.

act: Config (config) task: save Save settings to the database View configuration form Buttons: Save (save) task: default View configuration form Buttons: Save (save) act: Manage items task: add View add form Button: Save (save) task: delete Delete items View list of items Buttons: Add (add), Delete (delete) task: default View list of items Buttons: Add (add), Delete (delete)

The last thing is to define what happen if the 'Save' button is clicked (when adding new item).

act: Config (config) task: save Save settings to the database View configuration form Buttons: Save (save) task: default View configuration form Buttons: Save (save)

act: Manage items (manage) task: add View add form Button: Save (save) task: delete Delete items View list of items Buttons: Add (add), Delete (delete) task: save Add new item to the database View list of items Buttons: Add (add), Delete (delete) task: default View list of items Buttons: Add (add), Delete (delete)

We are done with the menu design and can translate it into PHP using switch statement:

<?php
switch($act) {
  case 'config':
    switch ($task) {
      case 'save':
        // Save settings to the database
        // View configuration form
        // Buttons: Save
        break;
      default:
        // View configuration form
        // Buttons: Save
        break;
    }
    break;

  case 'manage':
    switch ($task) {
      case 'add':
        // View add form
        // Button: Save
        break;
      case 'delete':
        // Delete items
        // View list of items
        // Buttons: Add, Delete
        break;
      case 'save':
        // Add new item to the database
        // View list of items
        // Buttons: Add, Delete
        break;
      default:
        // View list of items
        // Buttons: Add, Delete
        break;
    }
    break;
}
?>

Where should we put this code? In both admin.newcomp.php and toolbar.newcomp.php. The difference is that admin.newcomp.php will handle data processing, and toolbar.newcomp.php will handle displaying the buttons. But the structure is generally the same for both files because we need to define what form and buttons to be displayed for each combination of $act and $task.

<?php
// In admin.newcomp.php file

switch($act) {
  case 'config':
    switch ($task) {
      case 'save':
        // Save settings to the database
        // View configuration form
        break;
      default:
        // View configuration form
        break;
    }
    break;

  case 'manage':
    switch ($task) {
      case 'add':
        // View add form
        break;
      case 'delete':
        // Delete items
        // View list of items
        break;
      case 'save':
        // Add new item to the database
        // View list of items
        break;
      default:
        // View list of items
        break;
    }
    break;
}
?>

<?php
// In toolbar.newcomp.php file

switch($act) {
  case 'config':
    switch ($task) {
      case 'save':
        // Buttons: Save
        break;
      default:
        // Buttons: Save
        break;
    }
    break;

  case 'manage':
    switch ($task) {
      case 'add':
        // Button: Save
        break;
      case 'delete':
        // Buttons: Add, Delete
        break;
      case 'save':
        // Buttons: Add, Delete
        break;
      default:
        // Buttons: Add, Delete
        break;
    }
    break;
}
?>

We have the structure ready now and it's time to fill it in with the codes that do the actual processing. In general, all processes that are related to GUI (HTML) should be kept in *.html.php. For admin.newcomp.php they are quite easy to spot, just about all actions that begins with 'View ...'. Common convention for class name in admin.newcomp.html.php is HTML_newcomp. For example:

<?php
// In admin.newcomp.html.php

class HTML_newcomp {
    function displayConfigForm() {
    }
}
?>

After having done writing the functions in admin.newcomp.html.php, link it from admin.newcomp.php with this line of code:

<?php
// In file admin.newcomp.php
require_once($mainframe->getPath('admin_html'));
?>

admin_html is the key name to load admin.newcomp.html.php file just like front_html key we saw before to load newcomp.html.php.

Displaying buttons in toolbar requires mosMenuBar class. You can directly use this class without having to include anything.

<?php
// In toolbar.newcomp.php file

// Include toolbar's HTML class
require_once($mainframe->getPath('toolbar_html'));

// ... (snipped) ...

    default:
        // Buttons: Add, Delete
        TOOLBAR_newcomp::defaultButtons()
        break;

// ... (snipped) ...
?>

<?php
// In toolbar.newcomp.html.php file

class TOOLBAR_newcomp {
    function defaultButtons() {
        // Open the table that contains the buttons
        mosMenuBar::startTable();

        // Display 'add' button
        mosMenuBar::addNew();

        // Display 'delete' button
        mosMenuBar::deleteList();

        // Close the table
        mosMenuBar::endTable();
    }
}
?>

Toolbar button acts as a submit button and therefore we must have a form on each page. This form must be named 'adminForm', submitted to index2.php, and have hidden fields to pass back variable $option, $act, and $task variables. Here's an example of a very minimal form.

<?php
// Form name must be adminForm
echo '<form action="index2.php" method="POST" name="adminForm">';

// Option (current component folder name) is available
// as global variable
echo '<input type="hidden" name="option" value="'.$option.'">';

// Act is also available as global variable
echo '<input type="hidden" name="act" value="'.$act.'">';

// The value of task will be set by Mambo upon submit,
// depending on which button is clicked
echo '<input type="hidden" name="task" value="">';

echo '</form>';
?>

If you have a list of items with checkboxes in the form, Mambo provides JavaScript functions to select/deselect all items and to check that at least 1 item is selected when you submit the form. The requirements for this to work are:

  • The checkbox that acts as switch to select/deselect all must be named 'toggle' 
    * The onClick event of 'toggle' checkbox must call checkAll(n) function.
Replace 'n' with the number of checkboxes you have in the list (e.g. you can get the value from mysql_num_rows(), etc)
  • Each checkbox must have its 'id' attribute set to 'cb', followed by an integer which starts from 0 ('cb0', 'cb1', 'cb2', etc). You can set the 'name' to anything.
  • The onClick event of each checkbox in the list must call isChecked(this.checked) function. Basically this function will increase variable 'boxchecked' value by 1 if an item is selected.
  • Therefore, you must have a hidden field named 'boxchecked' and set its initial value to 0. 
    <input type="checkbox" name="toggle" value="" onClick="checkAll(n);">

<input type="checkbox" id="cb0" name="cid[]" value="" onClick="isChecked(this.checked);">
<input type="checkbox" id="cb1" name="cid[]" value="" onClick="isChecked(this.checked);">
<input type="checkbox" id="cb2" name="cid[]" value="" onClick="isChecked(this.checked);">

<input type="hidden" name="boxchecked" value="0">

Class files

newcomp.class.php (optional)Class file newcomp.class.php contains other helper functions that are shared between frontend and adminstration files. For example, you can have a function that returns query result here and another function in newcomp.html.php to use this result, parse, and display the data nicely in a table. You can put this file either in 'installdir/components/newcomp' (Mambo will look here first) or 'installdir/administrator/components/newcomp' and include it from frontend or administration files using the following line:

     <?php
      require_once($mainframe->getPath('class'));
      ?>

Of course you can have other files than those explained here. For example, Awesome! component has Smarty templates included for easier customization of the layout. However, you cannot use $mainframe->getPath() to include the files since Mambo does not have the keys for this.

<?php
// Example how to include other helper file
// $mosConfig_absolute_path is the full path
// to Mambo installation directory
require_once($mosConfig_absolute_path.'/components/newcomp/helper1.php');
?>

Installation files

Installation files are only used during the installation (or uninstallation) process to copy/delete files and images to (or from) the correct locations, create (or delete) database tables used by your component, and display your installation (or uninstallation) messages. Files in this group are copied to installdir/administrator/components/newcomp folder.

newcomp.xmlThis file contains details about your component (name, version, copyright, your URL & email, etc), the list of files and images used, SQL commands to be executed during install/uninstall, and list of menu items to appear in administration page (under 'Components' menu).

Your component name (the text between <name></name>) will be used as directory name after it is converted to lowercase, all the spaces removed, and prefixed with 'com_'. So 'My Component' will be saved in 'com_newcomponent' directory, etc. Therefore it is better to avoid using non-alphanumeric characters in component name.

Below is a sample of the XML file for our hypothetical component 'My Component'. I will only explain some of the tags since most are self-explanatory.

      <?xml version="1.0" ?>
      <mosinstall type="component">
        <name>My Component</name>
        <creationDate>01/02/2005</creationDate>
        <author>Your Name</author>
        <copyright>(c) 2005 Company</copyright>
        <authorEmail> me@example.net</authorEmail>
        <authorUrl>www.domain.com</authorUrl>
        <version>1.0</version>
        <description>
          Description of this component
        </description>

        <files>
          <filename>newcomp.php</filename>
          <filename>newcomp.html.php</filename>
        </files>

        <images>
          <filename>img/img1.gif</filename>
          <filename>img/img2.gif</filename>
        </images>

        <install>
          <queries>
            <query>
              CREATE TABLE #__newcomp_data(
                id int unsigned not null,
                name varchar(255) not null,
                PRIMARY KEY (id)
              ) TYPE=MyISAM;
            </query>
            <query>
              (another query, etc)
            </query>
          </queries>
        </install>

        <installfile>
          install.newcomp.php
        </installfile>

        <uninstallfile>
          uninstall.newcomp.php
        </uninstallfile>

        <uninstall>
          <queries>
            <query>DROP TABLE #__newcomp_data;</query>
            <query>(another query, etc)</query>
          </queries>
        </uninstall>

        <administration>
          <menu>My Component</menu>
          <submenu>
            <menu act="config">Config</menu>
            <menu act="manage">Manage Items</menu>
          </submenu>

          <files>
            <filename>admin.newcomp.php</filename>
            <filename>admin.newcomp.html.php</filename>
            <filename>toolbar.newcomp.php</filename>
            <filename>toolbar.newcomp.html.php</filename>
          </files>

          <images>
            <filename>img/img3.gif</filename>
            <filename>img/img4.gif</filename>
          </images>
        </administration>
      </mosinstall>

All files in <files></files> and <images></images> will be copied to installdir/components/newcomp while those in <administration></administration> will be copied to installdir/administrator/components/newcomp.
SQL queries in <install></install> are executed during installation while those in <uninstall></uninstall> are executed during uninstall.

Table name format used is #_newcomp_tablename where # will be replaced by Mambo to whatever table prefix you select during
Mambo installation. By default the prefix is 'mos' so '#__newcomp_data' will create a table named 'mos_newcomp_data'.

install.newcomp.php (optional) This file contains only 1 function, com_install(), which will be called after successful installation of your component. Examples of what you can put here is congratulation message, copyright information, link to your website, etc.

     <?php
      function com_install() {
          return 'Installation successful! Please check my website for the latest update and support.';
      }
      ?>

Please take note that com_install() expects you to return the message, not echo it directly from within the function, to display it in the correct position on the success page.

Well, that wraps up our component tutorial. Write everything in lower case, check your syntax and you should be well on your way to writing your own component.
Toggle Sidebar
Space Navigation
Added by Lynne Pope on 30 Dec, 2007 02:09, last edited by Lynne Pope on 19 Sep, 2008 16:46

Adaptavist Theme Builder Powered by Atlassian Confluence
Free theme builder license