PEAR logo

HTML_QuickForm_advmultiselect : La Référence

Chapitre 5. Votre premier formulaire
Précédent  Partie II. Pour bien débuter  Suivant


Chapitre 5. Votre premier formulaire

Nous allons débuter par la création d'un formulaire très simple. Nos objectifs sont :

Copiez le code suivant dans un fichier, donnez lui l'extension .php, et afficher le résultat dans votre navigateur :

  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>

Le chargement de ce fichier dans votre navigateur devrait afficher quelquechose comme cette capture d'écran.

Revoyons cet exemple en détails, pas à pas :

Ligne 19 :

Au début nous créons une instance HTML_QuickForm qui contiendra notre formulaire avec tous ses éléments et toutes les autres informations nécessaires. Nous ne donnons que le nom du formulaire au constructeur de la classe, ce qui signifie que les valeurs par défaut seront appliquées aux autres paramètres.

Lignes 35, 41, 68 :

Notre formulaire sera constitué de trois éléments :

Le premier n'est pas notre « réel » élément, c'est juste une entête pour améliorer la présentation. Le second est notre élément advmultiselect. Notez que les paramètres pour la méthode HTML_QuickForm::addElement() ont des significations différentes suivant les éléments.

Lignes 22, 37 :

La variable $fruit_array définit les valeurs par défaut (code, libellé) pour l'élément advmultiselect fruit.

Lignes 38-40 :

Il est maintenant temps de définir les attributs de l'élément fruit :

size
Définit le nombre d'occurence visible de chaque liste. La valeur par défaut est 10.
style
La largeur en pixel des listes de sélection. La valeur par défaut est 100.
class
Un identifiant de classe CSS qui permet de redéfinir la présentation de l'élément advmultiselect. Il n'y a pas de valeur par défaut.
Lignes 42, 51, 52 :

Pour ajouter des entêtes à chaque liste (où vous voulez: au sommet, au pied), vous avez besoin de définir ces valeurs en premier. Puis en second, définir les marquages dans le gabarit (comme n'importe quel autre élement supportant la multi étiquette).

[Important] Important
Les marquages {label_2}, {label_3} sont utilisés, de la même façon pour tous les HTML_QuickForm renderers, et définissent : liste d'attente (label_2), et liste de sélection (label_3).
Lignes 43, 58 et 46, 59 :

La dernière étape pour achever la définition d'un élément advmultiselect est de créer les boutons add et remove.

Ici nous attribuons les noms Add >> et << Remove, avec une présentation contrôlée par la classe CSS inputCommand.

[Avertissement] Avertissement
Les marquages {add}, {remove} doivent exister dans le gabarit. Sans eux, vous ne verrez pas les boutons d'échange.
Ligne 65 :

Les futurs choix de l'utilisateur remplaceront les valeurs par défaut de l'élément advmultiselect fruit.

Ligne 106 :

Avant de valider et traiter le formulaire, la phase de création de celui-çi a besoin encore d'une chose. N'oubliez pas, que pour gérer les échanges entre les deux listes, nous avons besoin d'une brique de code javascript. Le temps est venu de l'inclure dans notre flux/gabarit HTML.

[Note] Note
En donnant la valeur false comment argument à la méthode getElementJs(), nous avons choisis de générer le code javascript avec ses balises script englobantes. Le comportement par défaut est de fournir uniquement le code brut sans balises script. Cela peut être utile lors de l'intégration avec du code js existant ou l'utilisation d'un moteur de gabarit.
Ligne 110 :
Nous avons désormais notre formulaire au complet et il nous faut choisir entre le traitement ou l'affichage de celui-çi.
Ligne 111 :

C'est un simple exemple d'affichage. Dans vos scripts vous voudrez enregistrer les valeurs quelquepart ou autre. La méthode HTML_QuickForm::process() peut être ici d'un grand intérêt.

Ligne 117 :
La dernière ligne est assez facile. Si le formulaire n'est pas validé, ce qui signifie qu'il n'a pas été transmis, ou qu'il y a eu des erreurs, il sera alors affiché.
HTML_QuickForm_advmultiselect : La Référence v 1.4.0 : 9 Juin 2007
Précédent  Niveau supérieur  Suivant
Concepts de base  Sommaire  Chapitre 6. Fonctions avancées