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);
}
?>


The image below shows where admin.mycomp.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.

• admin.mycomp.php
  Contains the 'switchboard' to decide what action to execute based on the selected menu and task buttons (Add, Delete, etc)
• admin.mycomp.html.php (optional)
  Contains class to print HTML codes (display forms, tables, etc)
• toolbar.mycomp.php
  Contains the 'switchboard' to decide which task buttons to display based on the selected menu and currently selected task
• toolbar.mycomp.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.mycomp.php and toolbar.mycomp.php. The difference is that admin.mycomp.php will handle data processing, and toolbar.mycomp.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.mycomp.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.mycomp.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.mycomp.php they are quite easy to spot, just about all actions that begins with 'View ...'. Common convention for class name in admin.mycomp.html.php is HTML_mycomp. For example:

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

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


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


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

Displaying buttons in toolbar requires mosMenuBar class. You can directly use this class without having to include anything. Taking a portion of what we have in toolbar.mycomp.html.php, I'll give an example on how to use mosMenuBar to display 'Add' and 'Delete' button. For a complete list of functions to display various buttons please refer to Appendix A.

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

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

// ... (snipped) ...

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

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


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

class TOOLBAR_mycomp {
    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">