Your first form

Your first form – basic usage

Basic features

We will start by creating a very simple form. Our goals are :

change the buttons (add, remove) position. Move at bottom of lists.
center headers at top of lists.
set list item visible to 5. Default is 10.
enlarge both list width to 300 pixels. Default width is only 100 pixels.
change background colors element.

Copy the following code to a file, give it a .php extension, and display it in your browser:


<?php
/**
 * Custom advMultiSelect HTML_QuickForm element
 * using stylesheet rules selectors and a template.
 *
 * The template allows to add label as headers of dual select box
 * and moves the button to another location (below each select box).
 *
 * @version    $Id: firstform.xml,v 1.2 2009-02-09 17:10:32 farell Exp $
 * @author     Laurent Laville <pear@laurent-laville.org>
 * @package    HTML_QuickForm_advmultiselect
 * @subpackage Examples
 * @access     public
 * @example    examples/qfams_custom_1.php
 *             qfams_custom_1 source code
 * @link       http://www.laurent-laville.org/img/qfams/screenshot/custom1.png
 *             screenshot (Image PNG, 677x197 pixels) 4.80 Kb
 */

require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';

$form = new HTML_QuickForm('amsCustom1');
$form->removeAttribute('name');        // XHTML compliance

$fruit_array = array(
    'apple'     =>  'Apple',
    'orange'    =>  'Orange',
    'pear'      =>  'Pear',
    'banana'    =>  'Banana',
    'cherry'    =>  'Cherry',
    'kiwi'      =>  'Kiwi',
    'lemon'     =>  'Lemon',
    'lime'      =>  'Lime',
    'tangerine' =>  'Tangerine',
);

// rendering with QF renderer engine and template system
$form->addElement('header', null, 'Advanced Multiple Select: custom layout ');

$ams =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array,
                           array('size' => 5,
                                 'class' => 'pool', 'style' => 'width:300px;'
                                )
);
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));
$ams->setButtonAttributes('add',    array('value' => 'Add >>',
                                           'class' => 'inputCommand'
));
$ams->setButtonAttributes('remove', array('value' => '<< Remove',
                                           'class' => 'inputCommand'
));
$template = '
<table{class}>
<!-- BEGIN label_2 --><tr><th align="center">{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th align="center">{label_3}</th></tr><!-- END label_3 -->
<tr>
  <td>{unselected}</td>
  <td>{selected}</td>
</tr>
<tr>
  <td align="center">{add}</td>
  <td align="center">{remove}</td>
</tr>
</table>';
$ams->setElementTemplate($template);

if (isset($_POST['fruit'])) {
    $form->setDefaults(array('fruit' => $_POST['fruit']));
}

$form->addElement('submit', 'send', 'Send');

?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>HTML_QuickForm::advMultiSelect custom example 1</title>
<style type="text/css">
<!--
body {
  background-color: #FFF;
  font-family: Verdana, Arial, helvetica;
  font-size: 10pt;
}

table.pool {
  border: 0;
  background-color: lightyellow;
}
table.pool th {
  font-size: 80%;
  font-style: italic;
  text-align: center;
}
table.pool select {
  background-color: lightblue;
}

.inputCommand {
    background-color: #d0d0d0;
    border: 1px solid #7B7B88;
    width: 7em;
    margin-bottom: 2px;
}
 -->
</style>
<?php echo $ams->getElementJs(false); ?>
</head>
<body>
<?php
if ($form->validate()) {
    $clean = $form->getSubmitValues();

    echo '<pre>';
    print_r($clean);
    echo '</pre>';
}
$form->display();
?>
</body>
</html>

Lets review this example step by step :

Line 23 :: At the beginning we creates a HTML_Quickform object that will contain the objects representing elements and all the other necessary information. We only pass the form's name to the constructor, which means that default values will be used for other parameters.

Lines 39, 41, 72 :: Our form will consist of three elements:
The first one is not the "real" element, it is just a heading to improve presentation. The second one is our advmultiselect element. Note that parameters for HTML_Quickform::addElement method have different meanings for different elements. That is so because they are actually passed to these elements' constructors.

Lines 26-36 :: The $fruit_array variable sets the default values (code, label) for the fruit advmultiselect element.

Lines 42-44 :

It's time to define the fruit element attributes:

size: Give count of visible item in each list. Default is 10.

style: The select boxes width in pixel. Default is 100.

class: A CSS class identifier to override the look and feel. There is no default.

Lines 46, 55, 56 :

To put headers on each list (wherever you want: at top, or bottom), you need first to set these values. Then second, defines the placeholder in the template (as any other multi-label element).

Placeholders {label_2}, {label_3} are used, in the same way, for all HTML_Quickform renderers , and defines: unselected list (label_2), and selected list (label_3).

Lines 47, 62 and 50, 63 :

Last step to complete definition of a advmultiselect element is to set the add and remove buttons.

Here we gave names Add >> and << Remove, with a skin handled by the inputCommand CSS class.

Placeholders {add}, {remove} must exists into the template. Without them you won't see the move buttons.

Line 69 :: User's input overrides default values of the fruit advmultiselect element.

Line 110 :

Before to validate and process the form, the building form step need one more thing. Don't forget, that to manage swaps between both list, we need some javascript code. It's now time to include into our HTML stream/template.

By given the false value as argument to the getElementJs method, we have choosen to build javascript code with its script tags. Default behavior is to get only raw code without surrounding script tags. May be usefull with template integration and existing js code.

Line 114 :: We have now the form built and need to decide whether to process it or display.

Line 115 :: This is a simple display example. In your scripts you'll usually want to store the values somewhere or do whatever else. The HTML_Quickform::process method may be of interest here.

Line 121 :: The last line is pretty easy. If the form is not valid, which means that it either was not yet submitted or that there were errors, it will be displayed.

Your first form

Basic features

User Notes: