Nous allons débuter par la création d'un formulaire très simple. Nos objectifs sont :
changer la position des bouttons (add, remove). Déplacer aux pieds des listes.
centrer les entêtes aux sommets des listes.
définir une visibilité de 5 occurences au lieu des 10 par défaut.
agrandir la largeur des listes à 300 pixels. Par défaut la largeur est seulement de 100 pixels.
changer la couleur des différents éléments.
Copiez le code suivant dans un fichier, donnez lui l'extension .php, et afficher le résultat dans votre navigateur :
<?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 20:05:23 farell Exp $
* @author Laurent Laville <[email protected]>
* @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>
Revoyons cet exemple en détails, pas à pas :
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.
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.
La variable $fruit_array définit les valeurs par défaut (code, libellé) pour l'élément advmultiselect fruit.
Il est maintenant temps de définir les attributs de l'élément fruit :
Définit le nombre d'occurence visible de chaque liste. La valeur par défaut est 10.
La largeur en pixel des listes de sélection. La valeur par défaut est 100.
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.
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).
Les marquages {label_2}, {label_3} sont utilisés, de la même façon par tous les moteurs de rendu HTML_Quickform , et définissent : liste d'attente (label_2), et liste de sélection (label_3).
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.
Les marquages {add}, {remove} doivent exister dans le gabarit. Sans eux, vous ne verrez pas les boutons d'échange.
Les futurs choix de l'utilisateur remplaceront les valeurs par défaut de l'élément advmultiselect fruit.
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.
En donnant la valeur false comme 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.
Nous avons désormais notre formulaire au complet et il nous faut choisir entre le traitement ou l'affichage de celui-çi.
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.
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é.