cvs: peardoc /en/package/html/html-quickform intro-validation.xml
| From: | Alexey Borzov | Date: | Sun, 18 Jun 2006 13:07:01 +0000 |
| Subject: | cvs: peardoc /en/package/html/html-quickform intro-validation.xml | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-8048@lists.php.net to get a copy of this message | ||
avb Sun Jun 18 13:07:01 2006 UTC
Modified files:
/peardoc/en/package/html/html-quickform intro-validation.xml
Log:
Document format parameters for builtin rules (see request #6688)
http://cvs.php.net/viewcvs.cgi/peardoc/en/package/html/html-quickform/intro-validation.xml?r1=1.7&r2=1.8&diff_format=u Index: peardoc/en/package/html/html-quickform/intro-validation.xml diff -u peardoc/en/package/html/html-quickform/intro-validation.xml:1.7 peardoc/en/package/html/html-quickform/intro-validation.xml:1.8 --- peardoc/en/package/html/html-quickform/intro-validation.xml:1.7 Fri Nov 7 10:30:09 2003 +++ peardoc/en/package/html/html-quickform/intro-validation.xml Sun Jun 18 13:07:01 2006 @@ -1,4 +1,4 @@ -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <refentry id="package.html.html-quickform.intro-validation"> <refnamediv> <refname>Introduction - validation and filters</refname> @@ -68,102 +68,172 @@ <refsect2 id="package.html.html-quickform.intro-validation.rules.builtin"> <title>Built-in validation rules</title> <para> -QuickForm offers a few registered rules that are often used when validating forms. - <variablelist> - <title>Simple validation rules</title> - <varlistentry> - <term><varname>required</varname></term> - <listitem><para>value is not empty</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>maxlength</varname></term> - <listitem><para>value must not exceed <parameter>n</parameter> characters</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>minlength</varname></term> - <listitem><para>value must have more than <parameter>n</parameter> characters</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>rangelength</varname></term> - <listitem><para>value must have between <parameter>m</parameter> and <parameter>n</parameter> characters</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>regex</varname></term> - <listitem><para>value must pass the regular expression</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>email</varname></term> - <listitem><para>value is a correctly formatted email</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>lettersonly</varname></term> - <listitem><para>value must contain only letters</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>alphanumeric</varname></term> - <listitem><para>value must contain only letters and numbers</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>numeric</varname></term> - <listitem><para>value must be a number</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>nopunctuation</varname></term> - <listitem><para>value must not contain punctuation characters</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>nonzero</varname></term> - <listitem><para>value must be a number not starting with 0</para></listitem> - </varlistentry> - </variablelist> - - <variablelist> - <title>Validation rules for file uploads</title> - <varlistentry> - <term><varname>uploadedfile</varname></term> - <listitem><para>Required file upload</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>maxfilesize</varname></term> - <listitem><para>The file size must not exceed the given number of bytes</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>mimetype</varname></term> - <listitem><para>The file must have a correct mimetype</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>filename</varname></term> - <listitem><para>The filename must match the given regex</para></listitem> - </varlistentry> - </variablelist> - - <variablelist> - <title>Other rules</title> - <varlistentry> - <term><varname>callback</varname></term> - <listitem><para>This rule allows to use an external function/method for validation, either by registering it or by passing a callback as a format parameter.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>compare</varname></term> - <listitem><para>The rule allows to compare the values of two form fields. This can be used for e.g. 'Password repeat must match password' kind of rule.</para></listitem> - </varlistentry> - </variablelist> +QuickForm offers a few registered rules that are often used when validating +forms. Some of the rules may need an extra <varname>$format</varname> parameter +passed to <link linkend="package.html.html-quickform.html-quickform.addrule"><function>addRule</function></link> / +<link linkend="package.html.html-quickform.html-quickform.addgrouprule"><function>addGroupRule</function></link> +to work properly. + <table> + <title>List of built-in validation rules</title> + <tgroup cols="3"> + <colspec colname="name" /> + <colspec colname="desc" /> + <colspec colname="format" /> + <spanspec spanname="hspan" namest="name" nameend="format" align="center" /> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + <entry><varname>$format</varname> parameter</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><varname>required</varname></entry> + <entry>value is not empty</entry> + <entry></entry> + </row> + <row> + <entry><varname>maxlength</varname></entry> + <entry>value must not exceed given number of characters</entry> + <entry>number of characters, integer</entry> + </row> + <row> + <entry><varname>minlength</varname></entry> + <entry>value must have more than given number of characters</entry> + <entry>number of characters, integer</entry> + </row> + <row> + <entry><varname>rangelength</varname></entry> + <entry>value must have between min and max characters</entry> + <entry>array(min characters, max characters)</entry> + </row> + <row> + <entry><varname>regex</varname></entry> + <entry>value must pass the regular expression</entry> + <entry>regular expression to check, string</entry> + </row> + <row> + <entry><varname>email</varname></entry> + <entry>value is a correctly formatted email</entry> + <entry>whether to perform an additional domain check via <ulink url="&url.php.lookup;checkdnsrr"><function>checkdnsrr</function></ulink> function, boolean</entry> + </row> + <row> + <entry><varname>lettersonly</varname></entry> + <entry>value must contain only letters</entry> + <entry></entry> + </row> + <row> + <entry><varname>alphanumeric</varname></entry> + <entry>value must contain only letters and numbers</entry> + <entry></entry> + </row> + <row> + <entry><varname>numeric</varname></entry> + <entry>value must be a number</entry> + <entry></entry> + </row> + <row> + <entry><varname>nopunctuation</varname></entry> + <entry>value must not contain punctuation characters</entry> + <entry></entry> + </row> + <row> + <entry><varname>nonzero</varname></entry> + <entry>value must be a number not starting with 0</entry> + <entry></entry> + </row> + <row> + <entry><varname>compare</varname></entry> + <entry> + The rule allows to compare the values of two form fields. + This can be used for e.g. 'Password repeat must match + password' kind of rule. Please note that you need to pass an + array of elements' names to compare as a first parameter to + <link linkend="package.html.html-quickform.html-quickform.addrule"><function>addRule</function></link>. + </entry> + <entry><para>Type of comparison to perform, string: + <variablelist> + <varlistentry> + <term><parameter>'eq'</parameter> or <parameter>'=='</parameter></term> + <listitem><simpara>(default) the elements should have the same values</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>'neq'</parameter> or <parameter>'!='</parameter></term> + <listitem><simpara>the elements should have different values</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>'gt'</parameter> or <parameter>'>'</parameter></term> + <listitem><simpara>first element's value should be greater (compared as numbers)</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>'gte'</parameter> or <parameter>'>='</parameter></term> + <listitem><simpara>first element's value should be greater or equal (compared as numbers)</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>'lt'</parameter> or <parameter>'<'</parameter></term> + <listitem><simpara>first element's value should be smaller (compared as numbers)</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>'lte'</parameter> or <parameter>'<='</parameter></term> + <listitem><simpara>first element's value should be smaller or equal (compared as numbers)</simpara></listitem> + </varlistentry> + </variablelist> + </para></entry> + </row> + <row> + <entry><varname>callback</varname></entry> + <entry> + This rule allows to use an external function/method for + validation. This can be done either explicitly, by passing a + callback as a format parameter or implicitly, by registering + it via <link linkend="package.html.html-quickform.html-quickform.registerrule"><function>registerRule</function></link>. + </entry> + <entry>Function/method to use, <ulink url="&url.php.callback;"><type>callback</type></ulink>.</entry> + </row> + <row> + <entry spanname="hspan">Validation rules for file uploads</entry> + </row> + <row> + <entry><varname>uploadedfile</varname></entry> + <entry>required file upload</entry> + <entry></entry> + </row> + <row> + <entry><varname>maxfilesize</varname></entry> + <entry>the file size must not exceed the given number of bytes</entry> + <entry>maximum file size, integer</entry> + </row> + <row> + <entry><varname>mimetype</varname></entry> + <entry>the file must have a correct MIME type</entry> + <entry>either a string for single allowed MIME type, or an array of allowed MIME types</entry> + </row> + <row> + <entry><varname>filename</varname></entry> + <entry>the filename must match the given regex</entry> + <entry>regular expression to test, string</entry> + </row> + </tbody> + </tgroup> + </table> </para> - <note> - <title>On rules for file uploads</title> - <para> -These rules are defined in <filename>HTML/QuickForm/file.php</filename>, and are automatically registered when a <varname>file</varname> type element is added to the form. These rules are server-side only, for obvious reasons. - </para> - </note> + <note> + <title>On rules for file uploads</title> + <para> +These rules are defined in <filename>HTML/QuickForm/file.php</filename>, and are automatically registered when a <varname>file</varname> type element is added to the form. These rules are server-side only, for obvious reasons. + </para> + </note> + <para> -Some of these rules require an extra <varname>format</varname> parameter in order to work correctly. For example, the <varname>regex</varname> rule can be used this way to validate a signed integer: -<programlisting role="php"> -<![CDATA[ -$form->addRule('amount', 'Amount incorrect', 'regex', '/^[+-]?\d+$/'); -]]> -</programlisting> + Usage of builtin rules is covered in <filename>rules-builtin.php</filename> + example provided with the package. The <filename>rules-custom.php</filename> + example covers the usage of custom rule classes and <varname>callback</varname> + type rules. It also contains a <classname>NumericRange</classname> class for + checking whether a number is between a maximum and a minimum. </para> + </refsect2> <refsect2 id="package.html.html-quickform.intro-validation.rules.classes"> <title>Validation classes</title>
http://cvs.php.net/viewcvs.cgi/peardoc/en/package/html/html-quickform/intro-validation.xml?r1=1.7&r2=1.8&diff_format=u Index: peardoc/en/package/html/html-quickform/intro-validation.xml diff -u peardoc/en/package/html/html-quickform/intro-validation.xml:1.7 peardoc/en/package/html/html-quickform/intro-validation.xml:1.8 --- peardoc/en/package/html/html-quickform/intro-validation.xml:1.7 Fri Nov 7 10:30:09 2003 +++ peardoc/en/package/html/html-quickform/intro-validation.xml Sun Jun 18 13:07:01 2006 @@ -1,4 +1,4 @@ -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <refentry id="package.html.html-quickform.intro-validation"> <refnamediv> <refname>Introduction - validation and filters</refname> @@ -68,102 +68,172 @@ <refsect2 id="package.html.html-quickform.intro-validation.rules.builtin"> <title>Built-in validation rules</title> <para> -QuickForm offers a few registered rules that are often used when validating forms. - <variablelist> - <title>Simple validation rules</title> - <varlistentry> - <term><varname>required</varname></term> - <listitem><para>value is not empty</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>maxlength</varname></term> - <listitem><para>value must not exceed <parameter>n</parameter> characters</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>minlength</varname></term> - <listitem><para>value must have more than <parameter>n</parameter> characters</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>rangelength</varname></term> - <listitem><para>value must have between <parameter>m</parameter> and <parameter>n</parameter> characters</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>regex</varname></term> - <listitem><para>value must pass the regular expression</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>email</varname></term> - <listitem><para>value is a correctly formatted email</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>lettersonly</varname></term> - <listitem><para>value must contain only letters</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>alphanumeric</varname></term> - <listitem><para>value must contain only letters and numbers</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>numeric</varname></term> - <listitem><para>value must be a number</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>nopunctuation</varname></term> - <listitem><para>value must not contain punctuation characters</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>nonzero</varname></term> - <listitem><para>value must be a number not starting with 0</para></listitem> - </varlistentry> - </variablelist> - - <variablelist> - <title>Validation rules for file uploads</title> - <varlistentry> - <term><varname>uploadedfile</varname></term> - <listitem><para>Required file upload</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>maxfilesize</varname></term> - <listitem><para>The file size must not exceed the given number of bytes</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>mimetype</varname></term> - <listitem><para>The file must have a correct mimetype</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>filename</varname></term> - <listitem><para>The filename must match the given regex</para></listitem> - </varlistentry> - </variablelist> - - <variablelist> - <title>Other rules</title> - <varlistentry> - <term><varname>callback</varname></term> - <listitem><para>This rule allows to use an external function/method for validation, either by registering it or by passing a callback as a format parameter.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>compare</varname></term> - <listitem><para>The rule allows to compare the values of two form fields. This can be used for e.g. 'Password repeat must match password' kind of rule.</para></listitem> - </varlistentry> - </variablelist> +QuickForm offers a few registered rules that are often used when validating +forms. Some of the rules may need an extra <varname>$format</varname> parameter +passed to <link linkend="package.html.html-quickform.html-quickform.addrule"><function>addRule</function></link> / +<link linkend="package.html.html-quickform.html-quickform.addgrouprule"><function>addGroupRule</function></link> +to work properly. + <table> + <title>List of built-in validation rules</title> + <tgroup cols="3"> + <colspec colname="name" /> + <colspec colname="desc" /> + <colspec colname="format" /> + <spanspec spanname="hspan" namest="name" nameend="format" align="center" /> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + <entry><varname>$format</varname> parameter</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><varname>required</varname></entry> + <entry>value is not empty</entry> + <entry></entry> + </row> + <row> + <entry><varname>maxlength</varname></entry> + <entry>value must not exceed given number of characters</entry> + <entry>number of characters, integer</entry> + </row> + <row> + <entry><varname>minlength</varname></entry> + <entry>value must have more than given number of characters</entry> + <entry>number of characters, integer</entry> + </row> + <row> + <entry><varname>rangelength</varname></entry> + <entry>value must have between min and max characters</entry> + <entry>array(min characters, max characters)</entry> + </row> + <row> + <entry><varname>regex</varname></entry> + <entry>value must pass the regular expression</entry> + <entry>regular expression to check, string</entry> + </row> + <row> + <entry><varname>email</varname></entry> + <entry>value is a correctly formatted email</entry> + <entry>whether to perform an additional domain check via <ulink url="&url.php.lookup;checkdnsrr"><function>checkdnsrr</function></ulink> function, boolean</entry> + </row> + <row> + <entry><varname>lettersonly</varname></entry> + <entry>value must contain only letters</entry> + <entry></entry> + </row> + <row> + <entry><varname>alphanumeric</varname></entry> + <entry>value must contain only letters and numbers</entry> + <entry></entry> + </row> + <row> + <entry><varname>numeric</varname></entry> + <entry>value must be a number</entry> + <entry></entry> + </row> + <row> + <entry><varname>nopunctuation</varname></entry> + <entry>value must not contain punctuation characters</entry> + <entry></entry> + </row> + <row> + <entry><varname>nonzero</varname></entry> + <entry>value must be a number not starting with 0</entry> + <entry></entry> + </row> + <row> + <entry><varname>compare</varname></entry> + <entry> + The rule allows to compare the values of two form fields. + This can be used for e.g. 'Password repeat must match + password' kind of rule. Please note that you need to pass an + array of elements' names to compare as a first parameter to + <link linkend="package.html.html-quickform.html-quickform.addrule"><function>addRule</function></link>. + </entry> + <entry><para>Type of comparison to perform, string: + <variablelist> + <varlistentry> + <term><parameter>'eq'</parameter> or <parameter>'=='</parameter></term> + <listitem><simpara>(default) the elements should have the same values</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>'neq'</parameter> or <parameter>'!='</parameter></term> + <listitem><simpara>the elements should have different values</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>'gt'</parameter> or <parameter>'>'</parameter></term> + <listitem><simpara>first element's value should be greater (compared as numbers)</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>'gte'</parameter> or <parameter>'>='</parameter></term> + <listitem><simpara>first element's value should be greater or equal (compared as numbers)</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>'lt'</parameter> or <parameter>'<'</parameter></term> + <listitem><simpara>first element's value should be smaller (compared as numbers)</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>'lte'</parameter> or <parameter>'<='</parameter></term> + <listitem><simpara>first element's value should be smaller or equal (compared as numbers)</simpara></listitem> + </varlistentry> + </variablelist> + </para></entry> + </row> + <row> + <entry><varname>callback</varname></entry> + <entry> + This rule allows to use an external function/method for + validation. This can be done either explicitly, by passing a + callback as a format parameter or implicitly, by registering + it via <link linkend="package.html.html-quickform.html-quickform.registerrule"><function>registerRule</function></link>. + </entry> + <entry>Function/method to use, <ulink url="&url.php.callback;"><type>callback</type></ulink>.</entry> + </row> + <row> + <entry spanname="hspan">Validation rules for file uploads</entry> + </row> + <row> + <entry><varname>uploadedfile</varname></entry> + <entry>required file upload</entry> + <entry></entry> + </row> + <row> + <entry><varname>maxfilesize</varname></entry> + <entry>the file size must not exceed the given number of bytes</entry> + <entry>maximum file size, integer</entry> + </row> + <row> + <entry><varname>mimetype</varname></entry> + <entry>the file must have a correct MIME type</entry> + <entry>either a string for single allowed MIME type, or an array of allowed MIME types</entry> + </row> + <row> + <entry><varname>filename</varname></entry> + <entry>the filename must match the given regex</entry> + <entry>regular expression to test, string</entry> + </row> + </tbody> + </tgroup> + </table> </para> - <note> - <title>On rules for file uploads</title> - <para> -These rules are defined in <filename>HTML/QuickForm/file.php</filename>, and are automatically registered when a <varname>file</varname> type element is added to the form. These rules are server-side only, for obvious reasons. - </para> - </note> + <note> + <title>On rules for file uploads</title> + <para> +These rules are defined in <filename>HTML/QuickForm/file.php</filename>, and are automatically registered when a <varname>file</varname> type element is added to the form. These rules are server-side only, for obvious reasons. + </para> + </note> + <para> -Some of these rules require an extra <varname>format</varname> parameter in order to work correctly. For example, the <varname>regex</varname> rule can be used this way to validate a signed integer: -<programlisting role="php"> -<![CDATA[ -$form->addRule('amount', 'Amount incorrect', 'regex', '/^[+-]?\d+$/'); -]]> -</programlisting> + Usage of builtin rules is covered in <filename>rules-builtin.php</filename> + example provided with the package. The <filename>rules-custom.php</filename> + example covers the usage of custom rule classes and <varname>callback</varname> + type rules. It also contains a <classname>NumericRange</classname> class for + checking whether a number is between a maximum and a minimum. </para> + </refsect2> <refsect2 id="package.html.html-quickform.intro-validation.rules.classes"> <title>Validation classes</title>