cvs: peardoc /en/package/html html-quickform-advmultiselect.xml /en/package/html/html-quickform-advmultiselect/advanced arrange.xml buttons.xml headers.xml livecounter.xml

http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-quickform-advmultiselect.xml?r1=1.16&r2=1.17&diff_format=u
Index: peardoc/en/package/html/html-quickform-advmultiselect.xml
diff -u peardoc/en/package/html/html-quickform-advmultiselect.xml:1.16 peardoc/en/package/html/html-quickform-advmultiselect.xml:1.17
--- peardoc/en/package/html/html-quickform-advmultiselect.xml:1.16	Fri Jan 23 16:09:23 2009
+++ peardoc/en/package/html/html-quickform-advmultiselect.xml	Fri Jan 23 18:22:36 2009
@@ -129,8 +129,58 @@
 
  <chapter xml:id="package.html.html-quickform-advmultiselect.tutorial">
   <info><title>Getting started</title></info>
-  &package.html.html-quickform-advmultiselect.intro;
-  &package.html.html-quickform-advmultiselect.firstform;
+
+  <section xml:id="package.html.html-quickform-advmultiselect.basic">
+   <info><title>Basic features</title></info>
+   &package.html.html-quickform-advmultiselect.intro;
+   &package.html.html-quickform-advmultiselect.firstform;
+  </section>
+
+  <section xml:id="package.html.html-quickform-advmultiselect.advanced">
+   <info>
+    <title>Advanced features</title>
+    <abstract>
+     <simpara>
+      You should now have an understanding of basic HTML_QuickForm_advmultiselect functionality,
+      but there are many more features in the package, each of them deserving
+      a separate tutorial. This section will give a short overview of them
+      and point you to the complete documentation.
+     </simpara>
+     <para>
+      The advmultiselect element offers a lot of possibilities to customize its layout
+      and appearance. Remember that form output is done via
+      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.manual;en/package.html.html-quickform.intro-renderers.php">
+       renderers
+      </link>
+      - special classes containing necessary logic. There are QuickForm renderers that
+      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.manual;en/package.html.html-quickform.html-quickform-renderer-default.php">
+       directly output HTML
+      </link> and those that
+      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.manual;en/package.html.html-quickform.php#package.html.html-quickform.output.template-renderers">
+      use template engines
+      </link> for this.
+     </para>
+     <para>
+      <link linkend="package.html.html-quickform-advmultiselect.advanced.headers">Headers</link>
+      allow to give caption (label) to one or both list as any other QuickForm element
+      that support multi-labels system.
+     </para>
+     <para>
+      <link linkend="package.html.html-quickform-advmultiselect.advanced.buttons">Buttons</link>
+      allow to swap items from one list to the other, or arrange order of your selection.
+     </para>
+     <para>
+      <link linkend="package.html.html-quickform-advmultiselect.advanced.arrange">Sorts</link>
+      allow to re-arrange order of the selection, by the end-user. Its also allow
+      to set (by programming) a pre-set order (alphabetic or reverse) to each list.
+     </para>
+    </abstract>
+   </info>
+   &package.html.html-quickform-advmultiselect.advanced.headers;
+   &package.html.html-quickform-advmultiselect.advanced.buttons;
+   &package.html.html-quickform-advmultiselect.advanced.arrange;
+   &package.html.html-quickform-advmultiselect.advanced.livecounter;
+  </section>
  </chapter>
 
  <chapter xml:id="package.html.html-quickform-advmultiselect.ref">

http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-quickform-advmultiselect/advanced/arrange.xml?view=markup&rev=1.1
Index: peardoc/en/package/html/html-quickform-advmultiselect/advanced/arrange.xml
+++ peardoc/en/package/html/html-quickform-advmultiselect/advanced/arrange.xml
<?xml version="1.0" encoding="utf-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.html.html-quickform-advmultiselect.advanced.arrange">
 <refnamediv>
  <refname>Sorts</refname>
  <refpurpose>how to sort results</refpurpose>
 </refnamediv>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.arrange-intro">
  <info><title>Introduction</title></info>
  <para>
   There are two kind of sort with the advmultiselect element: The first one is only available
   by programming and allow an <emphasis role="bold">auto-arrange</emphasis>
   (alphabetic or reverse order) of each select list.
   The second is for end-user and allow them to <emphasis role="bold">sort</emphasis>
   their selection as they want.
   <important>
    <para>
     These features required HTML_QuickForm_advmultiselect package version 0.5.0 or better.
    </para>
   </important>
  </para>
 </refsection>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.arrange-auto">
  <info><title>Auto-arrange</title></info>
  <simpara>
   In some case, it could be interresting to have items lists sort alphabetically
   when elements are moved between them, rather than gets added to the bottom (default behavior).
  </simpara>
  <para>
   To get both list sort alphabetically, you have to set the <parameter>$sort</parameter>
   parameter of the
   <link linkend="package.html.html-quickform-advmultiselect.html-quickform-advmultiselect.html-quickform-advmultiselect">
    HTML_QuickForm_advmultiselect class constructor
   </link> with the PHP <constant>SORT_ASC</constant> constant.
  </para>
  <para>
   To get both list sort in reverse order, you have to set the <parameter>$sort</parameter>
   parameter of the
   <link linkend="package.html.html-quickform-advmultiselect.html-quickform-advmultiselect.html-quickform-advmultiselect">
    HTML_QuickForm_advmultiselect class constructor
   </link> with the PHP <constant>SORT_DESC</constant> constant.
  </para>
  <para>
   A full example is given in appendices. See the sort usage.
  </para>
 </refsection>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.arrange-buttons">
  <info><title>With buttons</title></info>
  <para>
   The other way to have your selection sorted is with help of two buttons:
   <emphasis role="bold">moveup</emphasis> to move an item to the top of the list,
   and <emphasis role="bold">movedown</emphasis> to move an item to the bottom of the list.
   <note>
    <simpara>
     These buttons works only with the selection list
    </simpara>
   </note>
  </para>
  <para>
   A full example is given in appendices. See the sort usage.
  </para>
 </refsection>

</refentry>
http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-quickform-advmultiselect/advanced/buttons.xml?view=markup&rev=1.1
Index: peardoc/en/package/html/html-quickform-advmultiselect/advanced/buttons.xml
+++ peardoc/en/package/html/html-quickform-advmultiselect/advanced/buttons.xml
<?xml version="1.0" encoding="utf-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.html.html-quickform-advmultiselect.advanced.buttons">
 <refnamediv>
  <refname>Buttons</refname>
  <refpurpose>how to customize action buttons</refpurpose>
 </refnamediv>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.buttons-intro">
  <info><title>Introduction</title></info>
  <para>
   There is two categories of button: <emphasis>sort</emphasis> and <emphasis>swap</emphasis>.
  </para>
  <para>
   The <emphasis>swap</emphasis> buttons are included since origin, while
   the <emphasis>sort</emphasis> buttons were included in the 0.5.0 version.
  </para>
  <para>
   With <emphasis role="bold">swap</emphasis> buttons, you will do your selection easily.
   Select item(s) (one or more), from unselected or selected list, then clic on the
   <emphasis>add</emphasis> or <emphasis>remove</emphasis> button to move
   your selection from one list to the other.
   <tip>
    <para>
     You can also double-clic on one item to move it, immediately, to the other list
     without to clic on the <emphasis>add</emphasis> or <emphasis>remove</emphasis> button.
    </para>
   </tip>
  </para>
  <para>
   Since version 1.1.0 you have ability to select or unselect all items in one stroke. You may
   also toggle a previous selection. This new feature is available through buttons <emphasis>all</emphasis>,
   <emphasis>none</emphasis> and <emphasis>toggle</emphasis>.
  </para>
  <para>
   Since version 1.2.0 toggle selection feature is available for both single and dual multi-select boxes.
   <note>
    <para>
     <itemizedlist>
      <listitem>
       <para>
        with one multi-select list, buttons available are only:
        <emphasis>all</emphasis>, <emphasis>none</emphasis> and <emphasis>toggle</emphasis>.
       </para>
      </listitem>
      <listitem>
       <para>
        with two multi-select list, buttons available are only:
        <emphasis>add</emphasis>, <emphasis>remove</emphasis>,
        <emphasis>moveup</emphasis>, <emphasis>movedown</emphasis>,
        <emphasis>all</emphasis>, <emphasis>none</emphasis> and <emphasis>toggle</emphasis>.
       </para>
      </listitem>
     </itemizedlist>
    </para>
   </note>
  </para>
  <para>
   A full example is given in appendices. See the advanced selection.
  </para>
  <para>
   With <emphasis role="bold">sort</emphasis> buttons, you have ability to reorder your selection easily.
   Select one item then clic on the
   <emphasis>up</emphasis> or <emphasis>down</emphasis> button to move it to the top or the
   bottom of your selection.
   <note>
    <para>
     Order is keep in the $_POST super global array, when the form is submit; Even if you've
     activated the auto-arrange feature (see <parameter>$sort</parameter> parameter of the
     <link linkend="package.html.html-quickform-advmultiselect.html-quickform-advmultiselect.html-quickform-advmultiselect">
      HTML_QuickForm_advmultiselect class constructor
     </link>)
    </para>
   </note>
  </para>
 </refsection>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.buttons-look">
  <info><title>Appearance</title></info>
  <para>
   There is two kinds of button: <emphasis>text</emphasis> and <emphasis>image</emphasis>.
   These are the standard html buttons we can find in a form. Default appearance is
   <emphasis>text</emphasis> but you can also easily use <emphasis>image</emphasis> layout.
   Here is how to do :
   <programlisting role="php">
    <![CDATA[
<?php
$ams->setButtonAttributes('add',    array('type' => 'image', 'src' => '/img/add.png'));
$ams->setButtonAttributes('remove', array('type' => 'image', 'src' => '/img/remove.png'));
?>
    ]]>
   </programlisting>
   Of course, all images are supported: PNG, GIF, etc ...
   <caution>
    <para>
     If the image file does not exist, you will get the internal text value as output without nothing
     else.
    </para>
    <para>
     Remember that defaults are: <quote><literal> &gt;&gt; </literal></quote> for add button,
     and <quote><literal> &lt;&lt; </literal></quote> for remove button.
    </para>
   </caution>
  </para>
 </refsection>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.buttons-attributes">
  <info><title>Attributes</title></info>
  <para>
   In version 0.4.0, there were only the basic <emphasis>add</emphasis> and
   <emphasis>remove</emphasis> buttons.
   In version 0.5.0, two new buttons were added:
   <emphasis>moveup</emphasis> and <emphasis>movedown</emphasis>.
   In version 1.1.0, three new buttons were added:
   <emphasis>all</emphasis>, <emphasis>none</emphasis>, and <emphasis>toggle</emphasis>.
   <caution>
    <para>
     Any other button identifier than
     <emphasis role="bold">add</emphasis>,
     <emphasis role="bold">remove</emphasis>,
     <emphasis role="bold">all</emphasis>,
     <emphasis role="bold">none</emphasis>,
     <emphasis role="bold">toggle</emphasis>,
     <emphasis role="bold">moveup</emphasis>,
     <emphasis role="bold">movedown</emphasis>
     will throws a PEAR_Error.
    </para>
   </caution>
  </para>
  <para>
   Only five attributes may be set, with these four button identifiers; they are:
   <variablelist>
    <varlistentry>
     <term>
      <parameter>name</parameter>
     </term>
     <listitem>
      <para>
       The form input button name. Default are: 'add', or 'remove',
       or 'all, or 'none', or 'toggle', or 'up', or 'down'.
       <warning>
        <simpara>
         Default values of the name attribute are not equivalent to button identifiers.
        </simpara>
       </warning>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>value</parameter>
     </term>
     <listitem>
      <para>
       The form input button text. Default are ' &gt;&gt; ', or ' &lt;&lt; ',
       or ' Select All ', or ' Select None ', or ' Toggle Selection ', or ' Up ', or ' Down '.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>type</parameter>
     </term>
     <listitem>
      <para>
       The form input button kind. Default is 'button' (Can be either 'button' or 'image').
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>class</parameter>
     </term>
     <listitem>
      <para>
       A CSS class identifier in one of your stylesheets.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>src</parameter>
     </term>
     <listitem>
      <para>
       URL of the image file used.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsection>

</refentry>
http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-quickform-advmultiselect/advanced/headers.xml?view=markup&rev=1.1
Index: peardoc/en/package/html/html-quickform-advmultiselect/advanced/headers.xml
+++ peardoc/en/package/html/html-quickform-advmultiselect/advanced/headers.xml
<?xml version="1.0" encoding="utf-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.html.html-quickform-advmultiselect.advanced.headers">
 <refnamediv>
  <refname>Headers</refname>
  <refpurpose>how to customize labels</refpurpose>
 </refnamediv>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.headers-intro">
  <info><title>Introduction</title></info>
  <simpara>
   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.
  </simpara>

  <para>
   As <emphasis role="bold">{label_2}</emphasis> is the placeholder for
   the second label (unselected list), <emphasis role="bold">{label_3}</emphasis>
   is the placeholder for the third label (selected list), in the hash setting. See
   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.manual;en/package.html.html-quickform.html-quickform-element.setlabel.php">
    HTML_Quickform::setLabel()
   </link> method.
   <important>
    <simpara>
     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.
    </simpara>
   </important>
  </para>
 </refsection>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.headers-default-renderer">
  <info><title>Naming with QuickForm Default Renderer</title></info>
  <para>
   <programlisting role="php">
    <![CDATA[
<?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 =&amp; $form->defaultRenderer();
$renderer->setElementTemplate($template);

// output the form
$form->display();
?>
    ]]>
   </programlisting>
   <variablelist>
    <varlistentry>
     <term>
      Line 8 :
     </term>
     <listitem>
      <para>
       The first label with default renderer, is always named
       <emphasis role="bold">{label}</emphasis>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      Line 32 :
     </term>
     <listitem>
      <para>
       In this example, its value will be <literal>Cars:</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsection>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.headers-itdynamic-renderer">
  <info><title>Naming with QuickForm ITDynamic Renderer</title></info>
  <para>
   <programlisting role="php">
    <![CDATA[
<?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}&amp;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();
?>
    ]]>
   </programlisting>
   <variablelist>
    <varlistentry>
     <term>
      Line 25 :
     </term>
     <listitem>
      <para>
       The first label with ITDynamic renderer, is always named
       <emphasis role="bold">{qf_label}</emphasis>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      Line 53 :
     </term>
     <listitem>
      <para>
       In this example, its value is still <literal>Cars:</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsection>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.headers-in-practice">
  <info><title>In practice</title></info>
  <para>
   Lets review in details how to set the appearance of headers in
   one of examples included in the package.
  </para>
  <para>
   After the labels are set:
   <programlisting role="php">
    <![CDATA[
<?php
$ams->setLabel(array('Fruit:', 'Available', 'Selected'));
?>
    ]]>
   </programlisting>
  </para>
  <para>
   Have a special look on the advmultiselect template element. Here is it:
   <programlisting role="php">
    <![CDATA[
<?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>';
?>
    ]]>
   </programlisting>
   <variablelist>
    <varlistentry>
     <term>
      Line 4 :
     </term>
     <listitem>
      <para>
       Header for the unselected list (named <literal>Available</literal>) is
       center aligned in bold with the TH tag.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      Line 5 :
     </term>
     <listitem>
      <para>
       Header for the selected list (named <literal>Selected</literal>), is also
       center aligned in bold with another TH tag.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  <para>
   <tip>
    <para>
     To give only a header to the selection list, either you set values as:
     <programlisting role="php">
      <![CDATA[
<?php
$ams->setLabel(array('Fruit:', null, 'Your selection'));
?>
      ]]>
     </programlisting>
     or you remove line beginning by <literal>&lt;!-- BEGIN label_2 --&gt;</literal>
     into the advmultiselect template element.
    </para>
   </tip>
  </para>
 </refsection>

</refentry>
http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-quickform-advmultiselect/advanced/livecounter.xml?view=markup&rev=1.1
Index: peardoc/en/package/html/html-quickform-advmultiselect/advanced/livecounter.xml
+++ peardoc/en/package/html/html-quickform-advmultiselect/advanced/livecounter.xml
<?xml version="1.0" encoding="utf-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.html.html-quickform-advmultiselect.advanced.livecounter">
 <refnamediv>
  <refname>Live counters</refname>
  <refpurpose>get number of item in results</refpurpose>
 </refnamediv>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.livecounter-intro">
  <info><title>Introduction</title></info>
  <para>
   When selection lists have lot of item, we don't expect to count each item one by one.
  </para>
  <para>
   When it's so easy to count selections on server side, once the form is submitted,
   there is no ability to do the same in live, until new feature "Live counter".
   <important>
    <simpara>
     This feature require HTML_QuickForm_advmultiselect package version 1.3.0 or better.
    </simpara>
   </important>
  </para>
  <para>
   A full example is given in appendices. See
   live counter combines with multiple elements.
  </para>
 </refsection>

 <refsection xml:id="package.html.html-quickform-advmultiselect.advanced.livecounter-id">
  <info><title>Identification and localisation</title></info>
  <para>
   Implements display of live counters (selected, unselected items) is fully independant.
   Its requires for each counter to add new placeholders.
  </para>
  <para>
   For item unselected list, these placehodlers are :
   <itemizedlist>
    <listitem>
     <para>
      <emphasis role="bold">{unselected_count}</emphasis>
      for localisation (where the counter value will be displayed)
     </para>
    </listitem>
    <listitem>
     <para>
      <emphasis role="bold">{unselected_count_id}</emphasis>
      for identification by DOM API (ID attribut of any HTML tag)
     </para>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   For item selected list, these placehodlers are :
   <itemizedlist>
    <listitem>
     <para>
      <emphasis role="bold">{selected_count}</emphasis>
      for localisation (where the counter value will be displayed)
     </para>
    </listitem>
    <listitem>
     <para>
      <emphasis role="bold">{selected_count_id}</emphasis>
      for identification by DOM API (ID attribut of any HTML tag)
     </para>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   <note>
    <para>
     <programlisting role="php">
      <![CDATA[
<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';
// ...
$form = new HTML_QuickForm('amsLC');
$ams =& $form->addElement('advmultiselect', 'cars', null, $car_array);
// ...
?>
      ]]>
     </programlisting>
    </para>
    <para>
     Counters identifiers (attribut ID) used by DOM API are identified by string :
     advmultiselect element name concat with "_selected" or "_unselected" suffix (depending of lists).
    </para>
    <para>
     Result for example (previous code) :
     <literal>cars_selected</literal> or <literal>cars_unselected</literal>
    </para>
    <para>
     advmultiselect element with single list (with checkboxes) are identified by string :
     "qfams_" prefix concat with advmultiselect element name
    </para>
    <para>
     Result for example (previous code) : <literal>qfams_cars</literal>
    </para>
    <para>
     advmultiselect element with double list are identified with string :
     prefix "__" (two underscores) concat with advmultiselect element name for unselected list.
     While selection list (selected item) is identified with string :
     prefix "_" (one underscore) concat with advmultiselect element name.
    </para>
    <para>
     Result for example (previous code) :
     <literal>__cars</literal> et <literal>_cars</literal>
    </para>
   </note>
  </para>
  <para>
   <important>
    <para>
     advmultiselect elements with single list (with checkboxes) are identified by DOM API
     with only <literal>{selected_count}</literal> et <literal>{selected_count_id}</literal>
     placeholders.
     No need to add <literal>{unselected_count}</literal> and
     <literal>{unselected_count_id}</literal> placeholders.
    </para>
    <para>
     See example in appendix
     Live counter combines with multiple elements,
     and template definition <literal>$template1</literal> lines 49-57.
    </para>
   </important>
  </para>
 </refsection>

</refentry>