PEAR logo

HTML_QuickForm_advmultiselect : The Definitive Guide

Chapter 5. Your first form
Prev  Part II. Getting Started  Next


Chapter 5. Your first form

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

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

  1. <?php
  2. /**
  3. * Custom advMultiSelect HTML_QuickForm element
  4. * using stylesheet rules selectors and a template.
  5. *
  6. * The template allows to add label as headers of dual select box
  7. * and moves the button to another location (below each select box).
  8. *
  9. * @version    $Id: qfams_custom_1.php,v 1.3 2007/01/05 15:35:33 farell Exp $
  10. * @author     Laurent Laville <pear@laurent-laville.org>
  11. * @package    HTML_QuickForm_advmultiselect
  12. * @subpackage Examples
  13. * @access     public
  14. * @example    examples/qfams_custom_1.php
  15. *             qfams_custom_1 source code
  16. * @link       http://www.laurent-laville.org/img/qfams/screenshot/custom1.png
  17. *             screenshot (Image PNG, 677x197 pixels) 4.80 Kb
  18. */
  19.  
  20. require_once 'HTML/QuickForm.php';
  21. require_once 'HTML/QuickForm/advmultiselect.php';
  22.  
  23. $form = new HTML_QuickForm('amsCustom1');
  24. $form->removeAttribute('name');        // XHTML compliance
  25.  
  26. $fruit_array = array(
  27.     'apple'     =>  'Apple',
  28.     'orange'    =>  'Orange',
  29.     'pear'      =>  'Pear',
  30.     'banana'    =>  'Banana',
  31.     'cherry'    =>  'Cherry',
  32.     'kiwi'      =>  'Kiwi',
  33.     'lemon'     =>  'Lemon',
  34.     'lime'      =>  'Lime',
  35.     'tangerine' =>  'Tangerine',
  36. );
  37.  
  38. // rendering with QF renderer engine and template system
  39. $form->addElement('header', null, 'Advanced Multiple Select: custom layout ');
  40.  
  41. $ams =& $form->addElement('advmultiselect', 'fruit', null, $fruit_array,
  42.                            array('size' => 5,
  43.                                  'class' => 'pool', 'style' => 'width:300px;'
  44.                                 )
  45. );
  46. $ams->setLabel(array('Fruit:', 'Available', 'Selected'));
  47. $ams->setButtonAttributes('add',    array('value' => 'Add >>',
  48.                                            'class' => 'inputCommand'
  49. ));
  50. $ams->setButtonAttributes('remove', array('value' => '<< Remove',
  51.                                            'class' => 'inputCommand'
  52. ));
  53. $template = '
  54. <table{class}>
  55. <!-- BEGIN label_2 --><tr><th align="center">{label_2}</th><!-- END label_2 -->
  56. <!-- BEGIN label_3 --><th align="center">{label_3}</th></tr><!-- END label_3 -->
  57. <tr>
  58.   <td>{unselected}</td>
  59.   <td>{selected}</td>
  60. </tr>
  61. <tr>
  62.   <td align="center">{add}</td>
  63.   <td align="center">{remove}</td>
  64. </tr>
  65. </table>';
  66. $ams->setElementTemplate($template);
  67.  
  68. if (isset($_POST['fruit'])) {
  69.     $form->setDefaults(array('fruit' => $_POST['fruit']));
  70. }
  71.  
  72. $form->addElement('submit', 'send', 'Send');
  73.  
  74. ?>
  75. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  76.     "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  77. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
  78. <head>
  79. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  80. <title>HTML_QuickForm::advMultiSelect custom example 1</title>
  81. <style type="text/css">
  82. <!--
  83. body {
  84.   background-color: #FFF;
  85.   font-family: Verdana, Arial, helvetica;
  86.   font-size: 10pt;
  87. }
  88.  
  89. table.pool {
  90.   border: 0;
  91.   background-color: lightyellow;
  92. }
  93. table.pool th {
  94.   font-size: 80%;
  95.   font-style: italic;
  96.   text-align: center;
  97. }
  98. table.pool select {
  99.   background-color: lightblue;
  100. }
  101.  
  102. .inputCommand {
  103.     background-color: #d0d0d0;
  104.     border: 1px solid #7B7B88;
  105.     width: 7em;
  106.     margin-bottom: 2px;
  107. }
  108.  -->
  109. </style>
  110. <?php echo $ams->getElementJs(false); ?>
  111. </head>
  112. <body>
  113. <?php
  114. if ($form->validate()) {
  115.     $clean = $form->getSubmitValues();
  116.  
  117.     echo '<pre>';
  118.     print_r($clean);
  119.     echo '</pre>';
  120. }
  121. $form->display();
  122. ?>
  123. </body>
  124. </html>

Loading this file in your browser will simply show something like this screenshot.

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).

[Important] Important
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.

[Warning] Warning
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.

[Note] Note
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.
HTML_QuickForm_advmultiselect : The Definitive Guide v 1.4.0 : 9 Juin 2007
Prev  Up  Next
Basic concepts  Home  Chapter 6. Advanced features