svn: /pear/peardoc/trunk/ en/package/html/html-common2.xml en/package/html/html-quickform2/controller-actions.xml en/package/html/html-quickform2/controller-overview.xml en/package/html/html-quickform2/elements.xml en/package/html/html-quickform2/javascript.xml en/package/html/html-quickform2/qf-migration.xml en/package/html/html-quickform2/rules.xml en/package/html/html-quickform2/tutorial.xml en/package/html/html-quickform2.xml entities/global.ent
[email protected] (Alexey Borzov) Sat, 29 Oct 2011 09:34:47 +0000
| Newsgroups | php.pear.doc |
|---|---|
| Message-ID | <[email protected]> |
avb Sat, 29 Oct 2011 09:34:47 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=318550
Log:
Added sections on elements and Javascript
Additional crosslinks, improved wording, fixed typos
Changed paths:
U pear/peardoc/trunk/en/package/html/html-common2.xml
U pear/peardoc/trunk/en/package/html/html-quickform2/controller-actions.xml
U pear/peardoc/trunk/en/package/html/html-quickform2/controller-overview.xml
A pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml
A pear/peardoc/trunk/en/package/html/html-quickform2/javascript.xml
U pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml
U pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml
U pear/peardoc/trunk/en/package/html/html-quickform2/tutorial.xml
U pear/peardoc/trunk/en/package/html/html-quickform2.xml
U pear/peardoc/trunk/entities/global.ent
svn-diffs-318550.txt
(text/x-diff, 58.7 KB)
Modified: pear/peardoc/trunk/en/package/html/html-common2.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-common2.xml 2011-10-29 08:42:40 UTC (rev 318549)
+++ pear/peardoc/trunk/en/package/html/html-common2.xml 2011-10-29 09:34:47 UTC (rev 318550)
@@ -11,8 +11,9 @@
<para>
The <classname>HTML_Common2</classname> package provides methods for <acronym>HTML</acronym>
attributes handling and setting document-wide options. It is quite helpful as a building block
- for packages generating HTML and is used as such by <phd:pearapi phd:package="HTML_QuickForm2"
- /> package. Main features:
+ for packages generating HTML and is currently used as such by <link
+ linkend="package.html.html-quickform2"><package>HTML_QuickForm2</package></link> package. Main
+ features:
<itemizedlist>
<listitem><simpara>
Allows easy setting, removing, merging of <link
Modified: pear/peardoc/trunk/en/package/html/html-quickform2/controller-actions.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/controller-actions.xml 2011-10-29 08:42:40 UTC (rev 318549)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/controller-actions.xml 2011-10-29 09:34:47 UTC (rev 318550)
@@ -99,7 +99,7 @@
<entry><literal>'next'</literal></entry>
<entry><phd:pearapi phd:package="HTML_QuickForm2"
phd:linkend="HTML_QuickForm2_Controller_Action_Next" /></entry>
- <entry>This handler should be bound to the <literal>"Back"</literal> button of
+ <entry>This handler should be bound to the <literal>"Next"</literal> button of
(usually) a wizard-type multipage form, it redirects to the next page if the current
one is valid (or the form is not wizard). On the last page of a multipage form it behaves
like <literal>'submit'</literal>.</entry>
@@ -212,8 +212,7 @@
absolute URL for a redirect (per <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="&url.rfc;2616">RFC 2616</link>). It uses various values from
<varname>$_SERVER</varname> array for this, but your server may be configured in such a way (e.g.
- if you use reverse proxy) that an URL a user sees is quite different from the one a script can
- guess.
+ if you use reverse proxy) that an URL a user sees is quite different from one a script can guess.
</para>
<para>
Thus the only bulletproof solution sometimes will be to explicitly set the
Modified: pear/peardoc/trunk/en/package/html/html-quickform2/controller-overview.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/controller-overview.xml 2011-10-29 08:42:40 UTC (rev 318549)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/controller-overview.xml 2011-10-29 09:34:47 UTC (rev 318550)
@@ -19,14 +19,17 @@
input. <package>HTML_QuickForm2_Controller</package> is somewhat smaller in scope than a typical
framework controller since it only deals with forms. When using the Controller, an action name is
sent in <literal>GET</literal> or <literal>POST</literal> data, usually by clicking a specially
- named button. This name contains <varname>id</varname> of the form and name of action handler to
- call (e.g. <literal>'next'</literal> for going forward in a wizard), so Controller has to extract
- that data and call the requested handler on the requested form.
+ named button. This name contains <varname>id</varname> of one of the form pages added to
+ Controller and name of action handler to call (e.g. <literal>'next'</literal> for going forward
+ in a wizard), that data is extracted and an appropriate action handler is called.
</para>
<para>
Key features:
<itemizedlist>
<listitem><simpara>
+ Allows forms spanning multiple pages, stores form data in session between HTTP requests;
+ </simpara></listitem>
+ <listitem><simpara>
Binds OO action handlers to buttons that submit the form;
</simpara></listitem>
<listitem><simpara>
Added: pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/elements.xml 2011-10-29 09:34:47 UTC (rev 318550)
@@ -0,0 +1,664 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.html.html-quickform2.elements"
+>
+ <refnamediv>
+ <refname>Elements</refname>
+ <refpurpose>Base Element API and list of built-in Elements</refpurpose>
+ </refnamediv>
+ <refsection xml:id="package.html.html-quickform2.elements.baseclasses">
+ <info>
+ <title>Base classes</title>
+ </info>
+ <para>
+ Element classes in <package>HTML_QuickForm2</package>, including <phd:pearapi
+ phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2"/> itself, are descended from either
+ <classname>HTML_QuickForm2_Container</classname> or
+ <classname>HTML_QuickForm2_Element</classname>, class tree for those two abstract classes given
+ below. Common <acronym>API</acronym> for elements is mostly defined in
+ <classname>HTML_QuickForm2_Node</classname>.
+ <itemizedlist>
+ <listitem><para>
+ <phd:pearapi phd:package="HTML_Common2" phd:linkend="HTML_Common2"/>
+ <itemizedlist>
+ <listitem><para>
+ <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Node"/>
+ <itemizedlist>
+ <listitem><para>
+ <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Container"/> - a
+ common parent class for form elements that can contain other elements (e.g. fieldsets,
+ groups).
+ </para></listitem>
+ <listitem><para>
+ <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Element"/> - a
+ common parent class for "scalar" form elements.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ <tip>
+ <para>
+ As can be seen from the above tree, all elements are descended from
+ <classname>HTML_Common2</classname>, so you have access to attribute-handling methods defined in
+ that class. Please refer to <link
+ linkend="package.html.html-common2"><package>HTML_Common2</package> documentation</link> for more info.
+ </para>
+ </tip>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.elements.node">
+ <info>
+ <title><classname>HTML_QuickForm2_Node</classname> API overview</title>
+ </info>
+ <note>
+ <para>
+ Only public methods that are of interest to package users are described in this section. Other
+ methods are mostly useful for those wishing to extends the package and will be described in a
+ separate documentation section targeted at them.
+ </para>
+ </note>
+ <para>
+ Constructors of all the elements have the same list of parameters, as defined in
+ <classname>HTML_QuickForm2_Node</classname>:
+ <variablelist>
+ <varlistentry>
+ <term>&type.string; <parameter>$name</parameter></term>
+ <listitem><para>Element name</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&type.string;|&type.array; <parameter>$attributes</parameter></term>
+ <listitem><para>HTML attributes</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>&type.array; <parameter>$data</parameter></term>
+ <listitem><para>
+ Additional element-specific data. A <literal>'label'</literal> key in this array is understood
+ by every element and is used for element's label. Other possible keys are described in the
+ tables below.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ As a result, <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Factory::createElement" /> and <phd:pearapi
+ phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Container::addElement" /> that pass
+ their arguments to the element's constructor also have constant list of parameters, the first
+ being element type and subsequent ones corresponding to constructor parameters.
+ </para>
+ <para>
+ Getters and setters for miscellaneous element properties: <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::setName">setName()</phd:pearapi> / <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::getName">getName()</phd:pearapi>, <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::setId">setId()</phd:pearapi> / <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::getId">getId()</phd:pearapi>, <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::setLabel">setLabel()</phd:pearapi> / <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::getId">getLabel()</phd:pearapi>, <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::getContainer">getContainer()</phd:pearapi>, <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::getData">getData()</phd:pearapi>, <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::getType">getType()</phd:pearapi>.
+ </para>
+ <tip>
+ <para>
+ Setter methods in <package>HTML_QuickForm2</package> tend to return <varname>$this</varname>, so
+ that it is possible to chain their invocations:
+ <programlisting role="php">
+<![CDATA[
+$text->setName('aText')
+ ->setLabel('Text input field:');
+]]>
+ </programlisting>
+ </para>
+ </tip>
+ <para>
+ Methods for getting and changing elements' values: <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::setValue">setValue()</phd:pearapi>, <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::getValue">getValue()</phd:pearapi>, <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::getRawValue">getRawValue()</phd:pearapi>. Their detailed
+ description is in <link
+ linkend="package.html.html-quickform2.values-datasources.values-overview">the next
+ section</link>.
+ </para>
+ <para>
+ Filtering the elements' values is done by <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::addFilter">addFilter()</phd:pearapi> and <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::addRecursiveFilter">addRecursiveFilter()</phd:pearapi>
+ methods. The former is applied directly to element's value on <function>getValue</function> call
+ and the latter is propagated to contained elements if the element is a Container or applied
+ recursively to the value if element's value is an array.
+ </para>
+ <para>
+ Validation-related methods: <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::setError">setError()</phd:pearapi> / <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::getError">getError()</phd:pearapi>, <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::createRule">createRule()</phd:pearapi>, <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::addRule">addRule()</phd:pearapi> / <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::removeRule">removeRule()</phd:pearapi>, <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::isRequired">isRequired()</phd:pearapi>. Please consult
+ <link linkend="package.html.html-quickform2.rules">the section on validation</link>.
+ </para>
+ <para>
+ The elements implement magic <function>__toString</function> method so they can be used in string
+ contexts:
+ <programlisting role="php">
+<![CDATA[
+$element = new HTML_QuickForm2_Element_InputText(
+ 'textBox', array('size' => 20, 'id' => 'textBoxId')
+);
+echo $element;
+]]>
+ </programlisting>
+ with output being
+ <screen>
+<![CDATA[
+<input type="text" id="textBoxId" size="20" name="textBox" />
+]]>
+ </screen>
+ More complex output needs are covered by <function>render</function> method.
+ </para>
+ <para>
+ A helpful feature of <package>HTML_QuickForm2</package> is the ability to "freeze" form
+ elements, displaying their values without HTML input tags. This may be used for an additional
+ confirmation step after form submit or for sending a filled form via email, among other things.
+ Two methods deal with this: <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::toggleFrozen">toggleFrozen()</phd:pearapi> and <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Node::persistentFreeze">persistentFreeze()</phd:pearapi>, the
+ former toggling the "frozen" status and the latter "persistent freeze"
+ behaiour. If persistent freeze is on, element's value will be kept (and possibly submitted) in a
+ hidden field.
+ </para>
+ <example>
+ <title>Freezing the element</title>
+ <para>
+ <programlisting role="php">
+<![CDATA[
+$box = new HTML_QuickForm2_Element_InputCheckbox(
+ 'aBox', array('value' => 'boxValue', 'checked' => 'checked')
+);
+echo $box . "\n\n";
+
+$box->toggleFrozen(true);
+echo $box . "\n\n";
+
+$box->persistentFreeze(false);
+echo $box;
+]]>
+ </programlisting>
+ the above code results in
+ <screen>
+<![CDATA[
+<input type="checkbox" value="boxValue" checked="checked" name="aBox" id="aBox-0" />
+
+<tt>[x]</tt><input type="hidden" name="aBox" value="boxValue" id="aBox-0" />
+
+<tt>[x]</tt>
+]]>
+ </screen>
+ </para>
+ </example>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.elements.container">
+ <info>
+ <title><classname>HTML_QuickForm2_Container</classname> API overview</title>
+ </info>
+ <para>
+ In addition to methods defined in <classname>HTML_QuickForm2_Node</classname>, Container
+ defines <acronym>DOM</acronym>-like <acronym>API</acronym> for handling of child elements:
+ <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container::appendChild">appendChild()</phd:pearapi>, <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container::insertBefore">insertBefore()</phd:pearapi>, <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container::removeChild">removeChild()</phd:pearapi>, <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container::getElementById">getElementById()</phd:pearapi>, <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container::getElementsByName">getElementsByName()</phd:pearapi>.
+ Their behaviour should not be too difficult to guess, the code
+ <programlisting role="php">
+<![CDATA[
+$fieldset = new HTML_QuickForm2_Container_Fieldset();
+
+$radioOne = $fieldset->appendChild(
+ new HTML_QuickForm2_Element_InputRadio('aRadio', array('id' => 'radioOne'))
+);
+$radioThree = $fieldset->appendChild(
+ new HTML_QuickForm2_Element_InputRadio('aRadio', array('id' => 'radioThree'))
+);
+$radioTwo = $fieldset->insertBefore(
+ new HTML_QuickForm2_Element_InputRadio('aRadio', array('id' => 'radioTwo')),
+ $radioThree
+);
+
+echo $fieldset->getElementById('radioOne') . "\n\n";
+$fieldset->removeChild($radioOne);
+foreach ($fieldset->getElementsByName('aRadio') as $radio) {
+ echo $radio . "\n";
+}
+]]>
+ </programlisting>
+ will output
+ <screen>
+<![CDATA[
+<input type="radio" value="on" id="radioOne" name="aRadio" />
+
+<input type="radio" value="on" id="radioTwo" name="aRadio" />
+<input type="radio" value="on" id="radioThree" name="aRadio" />
+]]>
+ </screen>
+ </para>
+ <para>
+ A few convenience methods are also available: <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container::getElements">getElements()</phd:pearapi> returns an
+ array with all the Container's elements and <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container::addElement">addElement()</phd:pearapi> creates an
+ element of a given type and adds it to the Container. Thanks to method overloading you can also
+ perform <function>addEltype</function> calls where <literal>'eltype'</literal> is an element type
+ known to <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Factory" /> (see
+ below for the list of such types and examples).
+ </para>
+ <para>
+ Container also implements <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="&url.php.lookup;Countable"><interfacename>Countable</interfacename></link> and
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="&url.php.lookup;IteratorAggregate"><interfacename>IteratorAggregate</interfacename></link>
+ <acronym>SPL</acronym> interfaces, allowing to
+ easily count the immediate children and iterate over them. It also has <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container::getRecursiveIterator">getRecursiveIterator()</phd:pearapi>
+ method which returns an instance of <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_ContainerIterator"/> for recursive iteration over
+ <emphasis>all</emphasis> child elements:
+ <programlisting role="php">
+<![CDATA[
+$outer = new HTML_QuickForm2_Container_Fieldset();
+$inner = $outer->addElement('fieldset')->setId('inner');
+$inner->addElement('text', 'textName')->setId('textId');
+
+echo count($outer) . "\n";
+foreach ($outer as $child) {
+ echo $child->getId() . "\n";
+}
+echo "\n";
+foreach ($outer->getRecursiveIterator() as $child) {
+ echo $child->getId() . "\n";
+}
+]]>
+ </programlisting>
+ The above code will output
+ <screen>
+<![CDATA[
+1
+inner
+
+inner
+textId
+]]>
+ </screen>
+ </para>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.elements.list">
+ <info>
+ <title>List of elements</title>
+ </info>
+ <para>
+ The following is a list of non-abstract descendants of
+ <classname>HTML_QuickForm2_Node</classname>. These elements are pre-registered with <phd:pearapi
+ phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Factory" /> and thus can be
+ instantiated with <phd:pearapi
+ phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Factory::createElement" /> and
+ added to a Container with either <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container::addElement" /> or its overloaded
+ <function>addEltype</function> method using "Type name" from tables below.
+ <programlisting role="php">
+<![CDATA[
+// will create an instance of HTML_QuickForm2_Element_Textarea
+$area = HTML_QuickForm2_Factory::createElement('textarea', 'areaName');
+// will add a new instance of HTML_QuickForm2_Element_Select to $container
+$select = $container->addElement('select', 'selectName');
+// will add a new instance of HTML_QuickForm2_Element_InputText to $container
+$text = $container->addText('textName');
+]]>
+ </programlisting>
+ </para>
+ <table>
+ <title>Standard HTML form elements</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Type name</entry>
+ <entry>Class</entry>
+ <entry>Description, extra <varname>$data</varname> keys</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row valign="top">
+ <entry><literal>'button'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Button"/></entry>
+ <entry>
+ <literal><button></button></literal> elements. <varname>$data</varname> may
+ contain <literal>'content'</literal> key with HTML to add between
+ <literal><button></button></literal> tags.
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'checkbox'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_InputCheckbox"/></entry>
+ <entry>
+ <literal><input type="checkbox" /></literal> elements.
+ <varname>$data</varname> may contain <literal>'content'</literal> key with a label that
+ should be "glued" to checkbox.
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'fieldset'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container_Fieldset"/></entry>
+ <entry><literal><fieldset></fieldset></literal> elements, labels for them will be
+ rendered as <literal><legend></legend></literal>.</entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'file'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_InputFile"/></entry>
+ <entry>
+ <literal><input type="file" /></literal> elements. This element validates
+ itself by checking a relevant <literal>'error'</literal> field in <varname>$_FILES</varname>
+ array. <varname>$data</varname> may contain <literal>'messageProvider'</literal> and
+ <literal>'language'</literal> keys for setting up localized error messages.
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'hidden'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_InputHidden"/></entry>
+ <entry><literal><input type="hidden" /></literal> elements</entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'image'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_InputImage"/></entry>
+ <entry>
+ <literal><input type="image" /></literal> elements
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'inputbutton'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_InputButton"/></entry>
+ <entry><literal><input type="button" /></literal> elements</entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'password'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_InputPassword"/></entry>
+ <entry><literal><input type="password" /></literal> elements</entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'radio'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_InputRadio"/></entry>
+ <entry>
+ <literal><input type="radio" /></literal> elements. <varname>$data</varname>
+ may contain <literal>'content'</literal> key with a label that should be "glued" to
+ radiobutton.
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'reset'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_InputReset"/></entry>
+ <entry><literal><input type="reset" /></literal> elements</entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'select'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Select"/></entry>
+ <entry><para>
+ <literal><select></select></literal> elements. <varname>$data</varname> may
+ contain the following keys
+ <variablelist>
+ <varlistentry>
+ <term><literal>'options'</literal></term>
+ <listitem><simpara>
+ Data to populate element's options with. Passed to
+ <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Select::loadOptions"/>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'intrinsic_validation'</literal></term>
+ <listitem><simpara>
+ By default only submit values corresponding to options present in the element are
+ returned. Setting this to &false; will return all submit values (useful if options are
+ added on client side).
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+ </para></entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'submit'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_InputSubmit"/></entry>
+ <entry><literal><input type="submit" /></literal> elements</entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'text'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_InputText"/></entry>
+ <entry><literal><input type="text" /></literal> elements</entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'textarea'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Textarea"/></entry>
+ <entry><literal><textarea></textarea></literal> elements</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table>
+ <title>Custom elements</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Type name</entry>
+ <entry>Class</entry>
+ <entry>Description, extra <varname>$data</varname> keys</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row valign="top">
+ <entry><literal>'date'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Date"/></entry>
+ <entry><para>
+ Group of selects used to input dates (and times). <varname>$data</varname> may contain
+ <variablelist>
+ <varlistentry>
+ <term><literal>'messageProvider'</literal></term>
+ <listitem><simpara>
+ Message provider for localized names of months and weekdays.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'language'</literal></term>
+ <listitem><simpara>
+ Date language, using <literal>'locale'</literal> will display month / weekday names
+ according to the current locale.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'format'</literal></term>
+ <listitem><simpara>
+ Format of the date, based on PHP's <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="&url.php.lookup;date"><function>date</function></link>. Format characters
+ recognized: <literal>'D'</literal>, <literal>'l'</literal>, <literal>'d'</literal>,
+ <literal>'M'</literal>, <literal>'F'</literal>, <literal>'m'</literal>,
+ <literal>'Y'</literal>, <literal>'y'</literal>, <literal>'h'</literal>,
+ <literal>'H'</literal>, <literal>'i'</literal>, <literal>'s'</literal>,
+ <literal>'a'</literal>, <literal>'A'</literal>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'minYear'</literal></term>
+ <listitem><simpara>
+ Minimum year in year select
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'maxYear'</literal></term>
+ <listitem><simpara>
+ Maximum year in year select
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'addEmptyOption'</literal></term>
+ <listitem><simpara>
+ Whether an empty option should be added to the top of each select box
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'emptyOptionValue'</literal></term>
+ <listitem><simpara>
+ The value passed by the empty option
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'emptyOptionText'</literal></term>
+ <listitem><simpara>
+ The text displayed for the empty option
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'optionIncrement'</literal></term>
+ <listitem><simpara>
+ Step to increase the option values by (works for <literal>'i'</literal> and
+ <literal>'s'</literal>)
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'minHour'</literal></term>
+ <listitem><simpara>
+ Minimum hour in hour select (only for 24 hour format)
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'maxHour'</literal></term>
+ <listitem><simpara>
+ Maximum hour in hour select (only for 24 hour format)
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'minMonth'</literal></term>
+ <listitem><simpara>
+ Minimum month in month select
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'maxMonth'</literal></term>
+ <listitem><simpara>
+ Maximum month in month select
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+ </para></entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'group'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Container_Group"/></entry>
+ <entry>Group of form elements. Several elements may be grouped into a single entity and this
+ entity used as a single element. Date and Hierselect are based on Group.</entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'hierselect'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Hierselect"/></entry>
+ <entry><para>
+ Hierarchical select element. Two or more select elements, selecting the value in the
+ first changes options in the second and so on. <varname>$data</varname> may contain
+ <variablelist>
+ <varlistentry>
+ <term><literal>'options'</literal></term>
+ <listitem><simpara>
+ Data to populate child elements' options with. Passed to <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Hierselect::loadOptions"/>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'size'</literal></term>
+ <listitem><simpara>
+ number of selects in hierselect. If not given will be set from size of options array or
+ size of array passed to <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Hierselect::setValue"/>.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+ Everything else is passed on to created selects.
+ </para></entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'script'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Script"/></entry>
+ <entry>Class for adding inline javascript to the form, based on Static.</entry>
+ </row>
+ <row valign="top">
+ <entry><literal>'static'</literal></entry>
+ <entry><phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Static"/></entry>
+ <entry><para>
+ A pseudo-element used to add text or markup to the form, when that text should be
+ output similar to form element. <varname>$data</varname> may contain
+ <variablelist>
+ <varlistentry>
+ <term><literal>'content'</literal></term>
+ <listitem><simpara>
+ Content of the static element, text or markup.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'tagName'</literal></term>
+ <listitem><simpara>
+ Name of the tag to wrap around content, e.g. <literal>'div'</literal>. The tag will use
+ Static element's attributes.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'forceClosingTag'</literal></term>
+ <listitem><simpara>
+ Whether to output closing tag in case of empty content,
+ <literal><foo></foo></literal> vs. <literal><foo /></literal>.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+
+ </table>
+ </refsection>
+</refentry>
Added: pear/peardoc/trunk/en/package/html/html-quickform2/javascript.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/javascript.xml (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/javascript.xml 2011-10-29 09:34:47 UTC (rev 318550)
@@ -0,0 +1,394 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.html.html-quickform2.javascript"
+>
+ <refnamediv>
+ <refname>Javascript support</refname>
+ <refpurpose>Client-side validation and Javascript-backed elements</refpurpose>
+ </refnamediv>
+ <refsection xml:id="package.html.html-quickform2.javascript.overview">
+ <info>
+ <title>Overview</title>
+ </info>
+ <para>
+ While <package>HTML_QuickForm</package> implemented client-side validation and provided several
+ Javascript-backed elements, support for Javascript there was quite limited. Basically, all
+ scripts were inlined and there were some rudimentary checks to prevent outputting the same
+ (library) code twice.
+ </para>
+ <para>
+ This was addressed in <package>HTML_QuickForm2</package>, Javascript handled by the package is
+ logically split into several parts:
+ <orderedlist>
+ <listitem><simpara>
+ Libraries;
+ </simpara></listitem>
+ <listitem><simpara>
+ Form setup code;
+ </simpara></listitem>
+ <listitem><simpara>
+ Inline script.
+ </simpara></listitem>
+ </orderedlist>
+ A page containing two Javascript-backed forms will look like this:
+ <screen>
+<![CDATA[
+...
+[JS libraries used by form1 and form2]
+...
+[form1 html, including inline javascript]
+[form1 setup code]
+...
+[form2 html, including inline javascript]
+[form2 setup code]
+...
+]]>
+ </screen>
+ An instance of <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_JavascriptBuilder" /> takes care of libraries and setup
+ code, inline code can be added using <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Script" /> element.
+ </para>
+ <para>
+ The new approach allows keeping the code that does not change (libraries) in external files,
+ instead of bloating the resultant HTML. If form's structure does not change either, generated
+ form setup code may also be moved to an external file. Only code that changes from one request to
+ the other (e.g. setting the element's value) has to be inlined.
+ </para>
+ <para>
+ There are currently two library files installed with the package:
+ <variablelist>
+ <varlistentry>
+ <term><filename>quickform.js</filename></term>
+ <listitem><simpara>
+ Helper methods and validation library.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>quickform-hierselect.js</filename></term>
+ <listitem><simpara>
+ Support functions for <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Element_Hierselect">hierselect elements</phd:pearapi>.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+ Human-readable versions of these files are installed into <filename
+ class="directory">HTML_QuickForm2/js</filename> directory under PEAR's
+ <parameter>data_dir</parameter> and minified versions are installed into <filename
+ class="directory">HTML_QuickForm2/js/min</filename>. If you have trouble finding where
+ <parameter>data_dir</parameter> is, you can use <link
+ linkend="guide.users.commandline.config">config-show</link> command of PEAR installer.
+ </para>
+ <para>
+ There is also a <filename>dualselect.php</filename> example showing among other things how to
+ create a custom element with an additional JS library.
+ </para>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.javascript.builder">
+ <info>
+ <title>Javascript builder class</title>
+ </info>
+ <note>
+ <para>
+ <!-- TODO: link to end-user Renderer docs once done -->
+ <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_JavascriptBuilder" /> is
+ used together with <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_Renderer">renderers</phd:pearapi>. Form Javascript is generated
+ in the course of <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2::render" /> call, so that call is mandatory if you are using
+ Javascript in your form.
+ </para>
+ </note>
+ <para>
+ Javascript library files are registered via <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_JavascriptBuilder::addLibrary" />. You will only need to call this
+ directly if you create custom Elements or Rules or maybe want to override validation behaviour
+ (see below). Correct <varname>$webPath</varname> and <varname>$absPath</varname> need to be provided
+ so the builder class can generate both links to external files and inline code.
+ </para>
+ <para>
+ Form setup code usually contains client-side validation rules added with <phd:pearapi
+ phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_JavascriptBuilder::addRule" /> and
+ element setup code added with <phd:pearapi
+ phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_JavascriptBuilder::addElementJavascript" />, the latter dealing
+ with event handlers necessary for element behaviour. For example, built-in <phd:pearapi
+ phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_Element_Hierselect">Hierselect
+ element</phd:pearapi> adds <literal>onchange</literal> handlers for contained selects,
+ <literal>onreset</literal> handler for a containing form and <literal>onload</literal> handler
+ for <varname>window</varname>. Once again, you will only directly call
+ <function>addElementJavascript</function> if you are creating a custom element or want to add
+ some custom setup code. You don't need to call <function>addRule</function> at all, as it is done
+ automatically if you added a Rule to an Element with
+ <constant>HTML_QuickForm2_Rule::CLIENT</constant> flag set.
+ </para>
+ <para>
+ <classname>HTML_QuickForm2_JavascriptBuilder</classname> also contains a static helper method
+ <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_JavascriptBuilder::encode">encode()</phd:pearapi> which encodes a
+ PHP value as a Javascript literal. This is similar to <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="&url.php.lookup;json_encode"><function>json_encode</function></link>, but does not
+ enforce <literal>UTF-8</literal> charset.
+ </para>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.javascript.libraries">
+ <info>
+ <title>Outputting libraries</title>
+ </info>
+ <para>
+ While form setup code and inline Javascript is automatically output when rendering a form,
+ libraries are <emphasis>not</emphasis> output automatically. The main reasons for this are
+ <orderedlist>
+ <listitem><simpara>
+ Links to the library files are usually placed in <literal><head></head></literal>
+ section of HTML document, while renderer outputs only the form itself.
+ </simpara></listitem>
+ <listitem><simpara>
+ If your page contains several forms, you'll only need to have one set of libraries for them.
+ You may use the same instance of <classname>HTML_QuickForm2_JavascriptBuilder</classname> when
+ rendering all forms.
+ </simpara></listitem>
+ </orderedlist>
+ </para>
+ <para>
+ There are two ways to include the library code in your page, both relying on <phd:pearapi
+ phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2_JavascriptBuilder::getLibraries" />:
+ <itemizedlist>
+ <listitem><para>
+ Inline the libraries, including their contents into the page
+ <programlisting role="php">
+<![CDATA[
+require_once 'HTML/QuickForm2/Renderer.php';
+
+$renderer = HTML_QuickForm2_Renderer::factory('default');
+$form->render($renderer);
+
+echo $renderer->getJavascriptBuilder()->getLibraries(true, true);
+echo $renderer;
+]]>
+ </programlisting>
+ </para></listitem>
+ <listitem><para>
+ Copy/symlink <filename>*.js</filename> files installed with the package to some directory under
+ your website's document root and provide this information to JavascriptBuilder:
+ <programlisting role="php">
+<![CDATA[
+require_once 'HTML/QuickForm2/Renderer.php';
+require_once 'HTML/QuickForm2/JavascriptBuilder.php';
+
+$renderer = HTML_QuickForm2_Renderer::factory('default');
+// Here '/path/to/libraries' is whatever directory available via HTTP you copied libraries to
+$renderer->setJavascriptBuilder(new HTML_QuickForm2_JavascriptBuilder('/path/to/libraries'));
+$form->render($renderer);
+
+// This will output necessary <script src="/path/to/libraries/..."></script> tags
+foreach ($renderer->getJavascriptBuilder()->getLibraries() as $link) {
+ echo $link . "\n";
+}
+echo $renderer;
+]]>
+ </programlisting>
+ </para></listitem>
+ </itemizedlist>
+ The latter approach is obviously recommended for production use.
+ </para>
+ <note>
+ <para>
+ Libraries should be output before forms and definitely before form setup code. Both inline
+ scripts and form setup code can contain calls to library functions and changes to library
+ properties.
+ </para>
+ </note>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.javascript.setup">
+ <info>
+ <title>Outputting form setup code</title>
+ </info>
+ <para>
+ Form setup code is returned by <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2_JavascriptBuilder::getFormJavascript" />. This method is
+ automatically called by built-in Renderers and thus the code is included in their output.
+ </para>
+ <para>
+ Note that <package>HTML_QuickForm2</package>'s Javascript library does not use
+ <literal>DOMContentLoaded</literal> event like <package>jQuery</package> and similar libraries
+ do:
+ <programlisting role="javascript">
+<![CDATA[
+$(document).ready(function() {
+ // some code that will be run when complete DOM tree is built
+});
+]]>
+ </programlisting>
+ Instead, form setup code is run immediately and should be output <emphasis>after the
+ form</emphasis>, when form's <acronym>DOM</acronym> tree is already available.
+ </para>
+ </refsection>
+
+ <refsection xml:id="package.html.html-quickform2.javascript.validation">
+ <info>
+ <title>Validation library description</title>
+ </info>
+ <tip>
+ <para>
+ Javascript code has API documentation comments that can be extracted with <link
+ xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.jsdoc;">JsDoc toolkit</link>.
+ <acronym>SVN</acronym> checkout of <package>HTML_QuickForm2</package> contains <link
+ xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.phing;">Phing</link> build file for
+ this.
+ </para>
+ </tip>
+ <para>
+ All Javascript code defined in <package>HTML_QuickForm2</package> lives in <varname>qf</varname>
+ "namespace". Deeper namespaces are used to group related functionality.
+ </para>
+ <para>
+ <varname>qf.Map</varname> is a class for Hash Map data structure. It is used internally to store
+ validation errors and Container values.
+ <programlisting role="javascript">
+<![CDATA[
+var map = new qf.Map();
+map.set('a key', 'a value');
+alert(map.get('a key')); // a value
+alert(map.hasKey('another key') ? 'true' : 'false'); // false
+alert(map.length()); // 1
+
+var map2 = new qf.Map({foo: 'foo value', bar: 'bar value'});
+map.merge(map2);
+map.remove('foo');
+alert(map.getKeys().join(', ')); // a key, bar
+alert(map.getValues().join(', ')); // a value, bar value
+map.clear();
+alert(map.isEmpty() ? 'true' : 'false'); // true
+]]>
+ </programlisting>
+ </para>
+ <para>
+ <varname>qf.form</varname> namespace contains methods for getting and setting elements' values:
+ <function>qf.form.getValue</function>, <function>qf.form.getSubmitValue</function> (shorthand
+ <function>qf.$v</function>), <function>qf.form.getContainerSubmitValue</function> (shorthand
+ <function>qf.$cv</function>), <function>qf.form.setValue</function>.
+ </para>
+ <para>
+ Methods for handling CSS classes on elements live in <varname>qf.classes</varname> namespace:
+ <function>qf.classes.add</function>, <function>qf.classes.remove</function>,
+ <function>qf.classes.has</function>.
+ </para>
+ <para>
+ <varname>qf.events</varname> namespace contains helper methods for crossbrowser events support:
+ <function>qf.events.addListener</function>, <function>qf.events.removeListener</function>,
+ <function>qf.events.fixEvent</function>. The latter is expected to be used in event handlers in
+ the following way
+ <programlisting role="javascript">
+<![CDATA[
+qf.Validator.submitHandler = function(event)
+{
+ event = qf.events.fixEvent(event);
+ // ...
+};
+]]>
+ </programlisting>
+ </para>
+ <note>
+ <para>
+ <package>HTML_QuickForm2</package> does not contain a full-blown crossbrowser event library
+ because it does not need one, the above are simple convenience methods. There are numerous
+ well-known JS frameworks with good crossbrowser events support, use one if needed.
+ </para>
+ </note>
+ <para>
+ <varname>qf.rules</varname> and <varname>qf.elements</varname> namespaces are intended for rule
+ implementations and element support methods, respectively. For example, Hierselect element puts
+ its code into <varname>qf.elements.hierselect</varname>.
+ </para>
+ <para>
+ Client-side validation is performed by an instance of <varname>qf.Validator</varname>. Its
+ constructor accepts <acronym>DOM</acronym> object of a form it needs to validate, sets up
+ necessary event handlers on that object and adds itself as a <varname>validator</varname>
+ property of it.
+ </para>
+ <tip>
+ <para>
+ It is easiest to disable client-side validation for a form by clearing
+ <varname>validator</varname> property from form's <acronym>DOM</acronym> object:
+ <programlisting role="javascript">
+<![CDATA[
+document.getElementById(formId).validator = null;
+]]>
+ </programlisting>
+ </para>
+ </tip>
+ <para>
+ <varname>qf.Validator</varname> exposes several methods which can be overriden to change the way
+ validation results are presented to user:
+ <variablelist>
+ <varlistentry>
+ <term><function>onStart</function></term>
+ <listitem><simpara>
+ Called before starting the validation. May be used e.g. to clear the errors from form
+ elements.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>onFieldError</function></term>
+ <listitem><simpara>
+ Called on setting the element error.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>onFieldValid</function></term>
+ <listitem><simpara>
+ Called on successfully validating the element.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>onFormValid</function></term>
+ <listitem><simpara>
+ Called on successfully validating the whole form.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><function>onFormError</function></term>
+ <listitem><simpara>
+ Called on failed form validation. List of errors is available in
+ <varname>this.errors</varname> property, which is an instance of <varname>qf.Map</varname>.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+ These can be overriden either for a particular instance of <varname>qf.Validator</varname> or for
+ all its instances if <varname>qf.Validator.prototype</varname> is changed.
+ </para>
+ <para>
+ For example, if you want to display a list of validation errors in an <function>alert</function>
+ (as was done in <package>HTML_QuickForm</package> and pre-0.6.0
+ <package>HTML_QuickForm2</package>) you can do the following:
+ <programlisting role="javascript">
+<![CDATA[
+var form = document.getElementById(formId);
+form.validator.onFormError = function() {
+ alert('Invalid information entered:\n - ' +
+ this.errors.getValues().join('\n - ') +
+ '\nPlease correct these fields.');
+};
+// don't set errors on elements
+form.validator.onFieldError = function() {};
+form.validator.onFieldValid = function() {};
+]]>
+ </programlisting>
+ If you want to disable submit button to prevent duplicate form submits:
+ <programlisting role="javascript">
+<![CDATA[
+document.getElementById(formId).validator.onFormValid = function() {
+ document.getElementById(submitId).disabled = true;
+};
+]]>
+ </programlisting>
+ </para>
+ </refsection>
+</refentry>
Modified: pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml 2011-10-29 08:42:40 UTC (rev 318549)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/qf-migration.xml 2011-10-29 09:34:47 UTC (rev 318550)
@@ -347,8 +347,9 @@
</para>
<para>
There is now a javascript library provided with the package which contains code necessary for
- client-side validation to run. This library should be included in the page if you intend to use
- client-side validation.
+ client-side validation to run. This library <link
+ linkend="package.html.html-quickform2.javascript.libraries">should be included in the
+ page</link> if you intend to use client-side validation.
</para>
</refsection>
@@ -402,21 +403,8 @@
</para>
<para>
If you are using client-side validation or javascript-backed elements like hierselect, you should
- take care that necessary javascript libraries are included in the page before the form. The
- easiest (but not the most efficient) way to ensure that:
- <programlisting role="php">
-<![CDATA[
-require_once 'HTML/QuickForm2/Renderer.php';
-
-$renderer = HTML_QuickForm2_Renderer::factory('default');
-// You can customize element templates here
-// $renderer->setTemplateFor...
-$form->render($renderer);
-// This will inline the necessary libraries
-echo $renderer->getJavascriptBuilder()->getLibraries(true, true);
-echo $renderer;
-]]>
- </programlisting>
+ take care that necessary javascript libraries are included in the page before the form. Consult
+ the <link linkend="package.html.html-quickform2.javascript">section on Javascript support</link>.
</para>
</refsection>
</refentry>
Modified: pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml 2011-10-29 08:42:40 UTC (rev 318549)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/rules.xml 2011-10-29 09:34:47 UTC (rev 318550)
@@ -453,6 +453,15 @@
<info>
<title>Client-side validation</title>
</info>
+ <note>
+ <title>Validation library</title>
+ <para>
+ Client-side validation depends on a JS library residing in <filename>quickform.js</filename>
+ file. Neither a link to that file nor its contents is automatically included in the output
+ generated by a renderer, <link linkend="package.html.html-quickform2.javascript">the next
+ section</link> describes how you can properly handle including it.
+ </para>
+ </note>
<para>
You can tell a rule to also generate Javascript necessary for client-side validation. This is
done by passing a <parameter>$runAt</parameter> parameter with
@@ -496,55 +505,5 @@
<classname>HTML_AJAX</classname> to create proxy classes in Javascript.
</para>
</tip>
- <para>
- Javascript for the rules is aggregated by <phd:pearapi phd:package="HTML_QuickForm2"
- phd:linkend="HTML_QuickForm2_JavascriptBuilder" /> class when rendering a form and usually
- output by a renderer. That class also tracks what Javascript libraries should be included in the
- page before the form for client-side validation and javascript-backed elements to work. Libraries
- are not output by default, you need either
- <itemizedlist>
- <listitem><para>
- Call <phd:pearapi phd:package="HTML_QuickForm2"
- phd:linkend="HTML_QuickForm2_JavascriptBuilder::getLibraries" /> to inline the libraries,
- including their contents into the page
- <programlisting role="php">
-<![CDATA[
-require_once 'HTML/QuickForm2/Renderer.php';
-
-$renderer = HTML_QuickForm2_Renderer::factory('default');
-$form->render($renderer);
-
-echo $renderer->getJavascriptBuilder()->getLibraries(true, true);
-echo $renderer;
-]]>
- </programlisting>
- </para></listitem>
- <listitem><para>
- Copy/symlink <filename>*.js</filename> files installed into <filename
- role="dir">HTML_QuickForm2/</filename> directory under PEAR's <parameter>data_dir</parameter>
- to some directory under your website's document root and provide this information to
- JavascriptBuilder:
- <programlisting role="php">
-<![CDATA[
-require_once 'HTML/QuickForm2/Renderer.php';
-require_once 'HTML/QuickForm2/JavascriptBuilder.php';
-
-$renderer = HTML_QuickForm2_Renderer::factory('default');
-// Here '/path/to/libraries' is whatever directory available via HTTP you copied libraries to
-$renderer->setJavascriptBuilder(new HTML_QuickForm2_JavascriptBuilder('/path/to/libraries'));
-$form->render($renderer);
-
-// This will output necessary <script src="/path/to/libraries/..."></script> tags
-foreach ($renderer->getJavascriptBuilder()->getLibraries() as $link) {
- echo $link . "\n";
-}
-echo $renderer;
-]]>
- </programlisting>
- If you have trouble finding where <parameter>data_dir</parameter> is, you can use <link
- linkend="guide.users.commandline.config">config-show</link> command of PEAR installer.
- </para></listitem>
- </itemizedlist>
- </para>
</refsection>
</refentry>
Modified: pear/peardoc/trunk/en/package/html/html-quickform2/tutorial.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2/tutorial.xml 2011-10-29 08:42:40 UTC (rev 318549)
+++ pear/peardoc/trunk/en/package/html/html-quickform2/tutorial.xml 2011-10-29 09:34:47 UTC (rev 318550)
@@ -86,9 +86,11 @@
$form = new HTML_QuickForm2('tutorial');
]]>
</programlisting>
- creates an instance of <phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2"
- /> that will contain objects representing form elements and other necessary information.
- We only pass the form's id to the <phd:pearapi phd:package="HTML_QuickForm2"
+ creates an instance of <phd:pearapi phd:package="HTML_QuickForm2"
+ phd:linkend="HTML_QuickForm2"/> that will contain <link
+ linkend="package.html.html-quickform2.elements">objects representing form elements</link> and
+ other necessary information. We only pass the form's id to the <phd:pearapi
+ phd:package="HTML_QuickForm2"
phd:linkend="HTML_QuickForm2::__construct">constructor</phd:pearapi>, which means that default
values will be used for other parameters. In particular, the form's method will default to
<literal>POST</literal> and the form's action to the current file. When using QuickForm2, it is
@@ -129,9 +131,9 @@
$fieldset->addElement('submit', null, array('value' => 'Send!'));
]]>
</programlisting>
- Note that most of the methods are returning <parameter>$this</parameter>, so it is possible to
- chain method calls. Note also that we can arbitrarily nest fieldsets and other containers (you
- can't nest another <classname>HTML_QuickForm2</classname> instance, however).
+ Note that most of the setter methods are returning <parameter>$this</parameter>, so it is
+ possible to chain method calls. Note also that we can arbitrarily nest fieldsets and other
+ containers (you can't nest another <classname>HTML_QuickForm2</classname> instance, however).
</para>
</refsection>
@@ -185,8 +187,9 @@
</programlisting>
<phd:pearapi phd:package="HTML_QuickForm2" phd:linkend="HTML_QuickForm2::validate" /> method
will consider the form valid (i.e. return &true;) if some data was actually submitted and all
- the rules defined for the form were satisfied. In our case this means that
- <literal>'name'</literal> element was not left empty.
+ <link linkend="package.html.html-quickform2.rules">the rules defined for the form were
+ satisfied</link>. In our case this means that <literal>'name'</literal> element was not left
+ empty.
</para>
<para>
If the form is validated we need to process <link
Modified: pear/peardoc/trunk/en/package/html/html-quickform2.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-quickform2.xml 2011-10-29 08:42:40 UTC (rev 318549)
+++ pear/peardoc/trunk/en/package/html/html-quickform2.xml 2011-10-29 09:34:47 UTC (rev 318550)
@@ -41,8 +41,10 @@
<chapter>
&package.html.html-quickform2.tutorial;
&package.html.html-quickform2.qf-migration;
+ &package.html.html-quickform2.elements;
&package.html.html-quickform2.values-datasources;
&package.html.html-quickform2.rules;
+ &package.html.html-quickform2.javascript;
&package.html.html-quickform2.controller-overview;
&package.html.html-quickform2.controller-migration;
&package.html.html-quickform2.controller-actions;
Modified: pear/peardoc/trunk/entities/global.ent
===================================================================
--- pear/peardoc/trunk/entities/global.ent 2011-10-29 08:42:40 UTC (rev 318549)
+++ pear/peardoc/trunk/entities/global.ent 2011-10-29 09:34:47 UTC (rev 318550)
@@ -79,6 +79,7 @@
<!ENTITY url.maxmind 'http://www.maxmind.com/'>
<!ENTITY url.maxmind.db.free 'http://www.maxmind.com/app/geoip_country'>
<!ENTITY url.maxmind.db.nonfree 'http://www.maxmind.com/app/products'>
+<!ENTITY url.jsdoc "http://code.google.com/p/jsdoc-toolkit/">
<!ENTITY url.pear 'http://pear.php.net/'>
<!ENTITY url.pear.account 'http://pear.php.net/accounts.php'>