cvs: peardoc /en/package/html html-quickform-advmultiselect.xml /en/package/html/html-quickform-advmultiselect firstform.xml

http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-quickform-advmultiselect.xml?r1=1.15&r2=1.16&diff_format=u
Index: peardoc/en/package/html/html-quickform-advmultiselect.xml
diff -u peardoc/en/package/html/html-quickform-advmultiselect.xml:1.15 peardoc/en/package/html/html-quickform-advmultiselect.xml:1.16
--- peardoc/en/package/html/html-quickform-advmultiselect.xml:1.15	Fri Jan 23 14:08:36 2009
+++ peardoc/en/package/html/html-quickform-advmultiselect.xml	Fri Jan 23 16:09:23 2009
@@ -130,6 +130,7 @@
  <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;
  </chapter>
 
  <chapter xml:id="package.html.html-quickform-advmultiselect.ref">

http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-quickform-advmultiselect/firstform.xml?view=markup&rev=1.1
Index: peardoc/en/package/html/html-quickform-advmultiselect/firstform.xml
+++ peardoc/en/package/html/html-quickform-advmultiselect/firstform.xml
<?xml version="1.0" encoding="utf-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.html.html-quickform-advmultiselect.firstform">
 <refnamediv>
  <refname>Your first form</refname>
  <refpurpose>basic usage</refpurpose>
 </refnamediv>

 <refsection xml:id="package.html.html-quickform-advmultiselect.firstform.purpose">
  <info><title>Basic features</title></info>
  <para>
   We will start by creating a very simple form. Our goals are :
   <itemizedlist>
    <listitem>
     <simpara>change the buttons (add, remove) position. Move at bottom of lists.</simpara>
    </listitem>
    <listitem>
     <simpara>center headers at top of lists.</simpara>
    </listitem>
    <listitem>
     <simpara>set list item visible to 5. Default is 10.</simpara>
    </listitem>
    <listitem>
     <simpara>enlarge both list width to 300 pixels. Default width is only 100 pixels.</simpara>
    </listitem>
    <listitem>
     <simpara>change background colors element.</simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Copy the following code to a file, give it a .php extension, and display it
   in your browser:
   <programlisting role="php">
    <![CDATA[
<?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.1 2009/01/23 16:09:24 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>
    ]]>
   </programlisting>
    Lets review this example step by step :
  </para>
  <variablelist>
   <varlistentry>
    <term>
     Line 23 :
    </term>
    <listitem>
     <para>
      At the beginning we creates a HTML_Quickform object that will contain the objects
      representing elements and all the other necessary information.
      We only pass the form's name to the constructor, which means that
      default values will be used for other parameters.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     Lines 39, 41, 72 :
    </term>
    <listitem>
     <simpara>
      Our form will consist of three elements:
     </simpara>
     <para>
      The first one is not the <quote>real</quote> element, it is just a heading
      to improve presentation.
      The second one is our advmultiselect element. Note that parameters for
      <methodname>HTML_Quickform::addElement()</methodname> method have different meanings
      for different elements. That is so because they are actually passed to
      these elements' constructors.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     Lines 26-36 :
    </term>
    <listitem>
     <para>
      The <varname>$fruit_array</varname> variable sets the default values (code, label)
      for the <emphasis>fruit</emphasis> advmultiselect element.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     Lines 42-44 :
    </term>
    <listitem>
     <para>
      It's time to define the fruit element attributes:
      <variablelist>
       <varlistentry>
        <term>
         size
        </term>
        <listitem>
         <simpara>Give count of visible item in each list. Default is 10.</simpara>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>
         style
        </term>
        <listitem>
         <simpara>The select boxes width in pixel. Default is 100.</simpara>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>
         class
        </term>
        <listitem>
         <simpara>A CSS class identifier to override the look and feel. There is no default.</simpara>
        </listitem>
       </varlistentry>
      </variablelist>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     Lines 46, 55, 56 :
    </term>
    <listitem>
     <para>
      To put headers on each list (wherever you want: at top, or bottom),
      you need first to set these values. Then second, defines the placeholder
      in the template (as any other multi-label element).
     </para>
     <para>
      <important>
       <para>
        Placeholders <emphasis role="bold">{label_2}, {label_3}</emphasis> are used,
        in the same way, for all
        <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.manual;en/package.html.html-quickform.intro-renderers.php">
         HTML_Quickform renderers
        </link>, and defines:
        unselected list (<literal>label_2</literal>), and
        selected list (<literal>label_3</literal>).
       </para>
      </important>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     Lines 47, 62 and 50, 63 :
    </term>
    <listitem>
     <para>
      Last step to complete definition of a advmultiselect element is to set the
      <emphasis>add</emphasis> and <emphasis>remove</emphasis> buttons.
     </para>
     <para>
      Here we gave names <literal>Add &gt;&gt;</literal> and <literal> &lt;&lt; Remove</literal>,
      with a skin handled by the <literal>inputCommand</literal> CSS class.
     </para>
     <para>
      <warning>
       <para>
        Placeholders <emphasis role="bold">{add}, {remove}</emphasis> must exists
        into the template. Without them you won't see the move buttons.
       </para>
      </warning>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     Line 69 :
    </term>
    <listitem>
     <para>
      User's input overrides default values of the <emphasis>fruit</emphasis> advmultiselect element.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     Line 110 :
    </term>
    <listitem>
     <para>
      Before to validate and process the form, the building form step need one more thing.
      Don't forget, that to manage swaps between both list, we need some javascript code.
      It's now time to include into our HTML stream/template.
     </para>
     <para>
      <note>
       <para>
        By given the <constant>false</constant> value as argument to the
        <methodname>getElementJs()</methodname> method, we have choosen to build javascript code with
        its script tags. Default behavior is to get only raw code without surrounding script tags.
        May be usefull with template integration and existing js code.
       </para>
      </note>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     Line 114 :
    </term>
    <listitem>
     <simpara>
      We have now the form built and need to decide whether to process it or display.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     Line 115 :
    </term>
    <listitem>
     <para>
      This is a simple display example. In your scripts you'll usually want
      to store the values somewhere or do whatever else. The
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.manual;en/package.html.html-quickform.html-quickform.process.php">
       HTML_Quickform::process()
      </link> method may be of interest here.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     Line 121 :
    </term>
    <listitem>
     <simpara>
      The last line is pretty easy.
      If the form is not valid, which means that it either was not yet submitted
      or that there were errors, it will be displayed.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsection>

</refentry>