Une étiquette est une zone texte de description (légende) qui sera affichée à coté de l'élément. Quelques moteurs de rendu (renderers) peuvent gérer le multi étiquettage. Les marquages utilisés par ces renderers ont des conventions de nom différent. Ne vous en faites pas, HTML_QuickForm_advmultiselect utilise seulement un standard de codification qui est équivalent à celui du QuickForm default renderer.
Alors que {label_2} est le marquage de la seconde étiquette (liste d'attente), {label_3} est le marquage pour la troisième étiquette (liste de sélection), dans le tableau des valeurs. Voir aussi la méthode HTML_Quickform::setLabel
La première étiquette est toujours pour l'élément advmultiselect lui-même. Son nom dépend du QuickForm renderer utilisé. Voir les exemples qui suivent pour noter la différence.
<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';
$template =
'<tr>
<td align="right" valign="top">
<b>{label}</b>
</td>
<td valign="top" align="left">
{element}
<!-- BEGIN error --><br/><font color="red">{error}</font><br/><!-- END error -->
</td>
</tr>';
// Create the form, and add a header to it.
$form = new HTML_QuickForm('qfamsLabels');
$form->addElement('header', null, 'QuickForm Labels Example: default renderer');
$cars = array(
'dodge' => 'Dodge',
'chevy' => 'Chevy',
'bmw' => 'BMW',
'audi' => 'Audi',
'porsche' => 'Porsche',
'kia' => 'Kia',
'subaru' => 'Subaru',
'mazda' => 'Mazda',
'isuzu' => 'Isuzu',
);
$labels = array('Cars:', 'Models', 'Your selection');
// Do the magic! Just pass your label to the element as an array!
$form->addElement('advmultiselect', 'cars', $labels, $cars);
// customize the element template
$renderer =& $form->defaultRenderer();
$renderer->setElementTemplate($template);
// output the form
$form->display();
?>
La première étiquette avec le default renderer, est toujours identifiée par {label}.
Dans cet exemple, sa valeur sera Cars:
<?php
require_once 'HTML/Template/Sigma.php';
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/Renderer/ITDynamic.php';
require_once 'HTML/QuickForm/advmultiselect.php';
$template = '
<form {qf_attributes}>
<table class="maintable">
<!-- BEGIN qf_hidden_block -->
<div style="display: none;">
<!-- BEGIN qf_hidden_loop -->{qf_hidden}<!-- END qf_hidden_loop -->
</div>
<!-- END qf_hidden_block -->
<!-- BEGIN qf_main_loop -->
<!-- BEGIN qf_header -->
<tr><th class="maintable" colspan="2">{qf_header}</th></tr>
<!-- END qf_header -->
<!-- BEGIN qf_element -->
<tr>
<td align="right" width="30%"><span class="qfLabel">{qf_label}&nbsp;</span></td>
<td>{qf_element}
<!-- BEGIN qf_element_error --><br /><span style="color: #FF0000;">{qf_error}</span><!-- END qf_element_error -->
</td>
</tr>
<!-- END qf_element -->
<!-- END qf_main_loop -->
</table>
</form>
';
// Create the form, and add a header to it.
$form = new HTML_QuickForm('qfamsLabels');
$form->addElement('header', null, 'QuickForm Labels Example: itdynamic renderer');
$cars = array(
'dodge' => 'Dodge',
'chevy' => 'Chevy',
'bmw' => 'BMW',
'audi' => 'Audi',
'porsche' => 'Porsche',
'kia' => 'Kia',
'subaru' => 'Subaru',
'mazda' => 'Mazda',
'isuzu' => 'Isuzu',
);
$labels = array('Cars:', 'Models', 'Your selection');
// Do the magic! Just pass your label to the element as an array!
$form->addElement('advmultiselect', 'cars', $labels, $cars);
// set the form template
$tpl = new HTML_Template_Sigma('.');
$tpl->setTemplate($template);
$renderer = new HTML_QuickForm_Renderer_ITDynamic($tpl);
$form->accept($renderer);
// output the form
$tpl->show();
?>
La première étiquette avec le ITDynamic renderer, est toujours identifiée par {qf_label}.
Dans cet exemple, sa valeur est encore Cars:
Revoyons en détails comment définir l'apparence des entêtes dans un des exemples inclus de ce paquet.
Après la définition des étiquettes:
<?php
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));
?>
Regardons de plus prêt le contenu du gabarit advmultiselect qui suit :
<?php
$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>';
?>
L'entête de la liste d'attente (nommée Available) est en gras centré au sommet de celle-ci grace à la balise TH.
L'entête de la liste de sélection (nommée Selected), est aussi en gras centré au sommet de celle-ci grace à une autre balise TH.
Pour attribuer un entête à la seule liste de sélection, soit vous coder la ligne
<?php
$ams->setLabel(array('Fruit:', null, 'Your selection'));
?>ou alors vous supprimer la ligne commençant par <!-- BEGIN label_2 --> dans le gabarit de l'élément advmultiselect.