PEAR logo

HTML_QuickForm_advmultiselect : The Definitive Guide

Headers
Prev  Chapter 6. Advanced features  Next


Headers

Introduction
Naming with QuickForm Default Renderer
Naming with QuickForm ITDynamic Renderer
In practice

Introduction

A label is a description text that will be displayed near the element. Some renderers can handle multiple labels for the element. Placeholders used by these renderers are different in naming convention. Nevermind, HTML_QuickForm_advmultiselect used only one standard coding that is equivalent to the QuickForm default renderer.

As {label_2} is the placeholder for the second label (unselected list), {label_3} is the placeholder for the third label (selected list), in the hash setting. See HTML_QuickForm::setLabel() method.

[Important] Important
The first label is always for the advmultiselect element group itself. Its name depend of the QuickForm renderer used. See examples that follow to notice the difference.

Naming with QuickForm Default Renderer

  1. <?php
  2. require_once 'HTML/QuickForm.php';
  3. require_once 'HTML/QuickForm/advmultiselect.php';
  4.  
  5. $template =
  6. '<tr>
  7.     <td align="right" valign="top">
  8.         <b>{label}</b>
  9.     </td>
  10.     <td valign="top" align="left">
  11.         {element}
  12.         <!-- BEGIN error --><br/><font color="red">{error}</font><br/><!-- END error -->
  13.     </td>
  14. </tr>';
  15.  
  16. // Create the form, and add a header to it.
  17. $form = new HTML_QuickForm('qfamsLabels');
  18. $form->addElement('header', null, 'QuickForm Labels Example: default renderer');
  19.  
  20. $cars = array(
  21.     'dodge'     =>  'Dodge',
  22.     'chevy'     =>  'Chevy',
  23.     'bmw'       =>  'BMW',
  24.     'audi'      =>  'Audi',
  25.     'porsche'   =>  'Porsche',
  26.     'kia'       =>  'Kia',
  27.     'subaru'    =>  'Subaru',
  28.     'mazda'     =>  'Mazda',
  29.     'isuzu'     =>  'Isuzu',
  30. );
  31.  
  32. $labels = array('Cars:', 'Models', 'Your selection');
  33.  
  34. // Do the magic! Just pass your label to the element as an array!
  35. $form->addElement('advmultiselect', 'cars', $labels, $cars);
  36.  
  37. // customize the element template
  38. $renderer =&amp; $form->defaultRenderer();
  39. $renderer->setElementTemplate($template);
  40.  
  41. // output the form
  42. $form->display();
  43. ?>
Line 8 :

The first label with default renderer, is always named {label}.

Line 32 :

In this example, its value will be Cars:.

Naming with QuickForm ITDynamic Renderer

  1. <?php
  2. require_once 'HTML/Template/Sigma.php';
  3. require_once 'HTML/QuickForm.php';
  4. require_once 'HTML/QuickForm/Renderer/ITDynamic.php';
  5. require_once 'HTML/QuickForm/advmultiselect.php';
  6.  
  7. $template = '
  8. <form {qf_attributes}>
  9. <table class="maintable">
  10.  
  11. <!-- BEGIN qf_hidden_block -->
  12. <div style="display: none;">
  13.   <!-- BEGIN qf_hidden_loop -->{qf_hidden}<!-- END qf_hidden_loop -->
  14. </div>
  15. <!-- END qf_hidden_block -->
  16.  
  17. <!-- BEGIN qf_main_loop -->
  18.  
  19.   <!-- BEGIN qf_header -->
  20.   <tr><th class="maintable" colspan="2">{qf_header}</th></tr>
  21.   <!-- END qf_header -->
  22.  
  23.   <!-- BEGIN qf_element -->
  24.   <tr>
  25.     <td align="right" width="30%"><span class="qfLabel">{qf_label}&amp;nbsp;</span></td>
  26.     <td>{qf_element}
  27.       <!-- BEGIN qf_element_error --><br /><span style="color: #FF0000;">{qf_error}</span><!-- END qf_element_error -->
  28.     </td>
  29.   </tr>
  30.   <!-- END qf_element -->
  31.  
  32. <!-- END qf_main_loop -->
  33. </table>
  34. </form>
  35. ';
  36.  
  37. // Create the form, and add a header to it.
  38. $form = new HTML_QuickForm('qfamsLabels');
  39. $form->addElement('header', null, 'QuickForm Labels Example: itdynamic renderer');
  40.  
  41. $cars = array(
  42.     'dodge'     =>  'Dodge',
  43.     'chevy'     =>  'Chevy',
  44.     'bmw'       =>  'BMW',
  45.     'audi'      =>  'Audi',
  46.     'porsche'   =>  'Porsche',
  47.     'kia'       =>  'Kia',
  48.     'subaru'    =>  'Subaru',
  49.     'mazda'     =>  'Mazda',
  50.     'isuzu'     =>  'Isuzu',
  51. );
  52.  
  53. $labels = array('Cars:', 'Models', 'Your selection');
  54.  
  55. // Do the magic! Just pass your label to the element as an array!
  56. $form->addElement('advmultiselect', 'cars', $labels, $cars);
  57.  
  58. // set the form template
  59. $tpl = new HTML_Template_Sigma('.');
  60. $tpl->setTemplate($template);
  61.  
  62. $renderer = new HTML_QuickForm_Renderer_ITDynamic($tpl);
  63.  
  64. $form->accept($renderer);
  65.  
  66. // output the form
  67. $tpl->show();
  68. ?>
Line 25 :

The first label with ITDynamic renderer, is always named {qf_label}.

Line 53 :

In this example, its value is still Cars:.

In practice

Lets review in details how to set the appearance of headers in one of examples included in the package.

After the labels are set:

  1. <?php
  2. $ams->setLabel(array('Fruit:', 'Available', 'Selected'));
  3. ?>

Have a special look on the advmultiselect template element. Here is it:

  1. <?php
  2. $template = '
  3. <table{class}>
  4. <!-- BEGIN label_2 --><tr><th align="center">{label_2}</th><!-- END label_2 -->
  5. <!-- BEGIN label_3 --><th align="center">{label_3}</th></tr><!-- END label_3 -->
  6. <tr>
  7.   <td>{unselected}</td>
  8.   <td>{selected}</td>
  9. </tr>
  10. <tr>
  11.   <td align="center">{add}</td>
  12.   <td align="center">{remove}</td>
  13. </tr>
  14. </table>';
  15. ?>
Line 4 :

Header for the unselected list (named Available) is center aligned in bold with the TH tag.

Line 5 :

Header for the selected list (named Selected), is also center aligned in bold with another TH tag.

[Tip] Tip
To give only a header to the selection list, either you set values as:
  1. <?php
  2. $ams->setLabel(array( 'Fruit:', null, 'Your selection'));
  3. ?>
or you remove line beginning by <!-- BEGIN label_2 --> into the advmultiselect template element.
HTML_QuickForm_advmultiselect : The Definitive Guide v 1.4.0 : 9 Juin 2007
Prev  Up  Next
Chapter 6. Advanced features  Home  Buttons