Author: hlship
Date: Sat Dec 17 09:20:59 2005
New Revision: 357350
URL: http://svn.apache.org/viewcvs?rev=357350&view=rev
Log:
Tweak Jesse's validation documentation
Modified:
jakarta/tapestry/branches/4.0/src/documentation/content/xdocs/UsersGuide/validation.xml
jakarta/tapestry/branches/4.0/status.xml
Modified:
jakarta/tapestry/branches/4.0/src/documentation/content/xdocs/UsersGuide/validation.xml
URL:
http://svn.apache.org/viewcvs/jakarta/tapestry/branches/4.0/src/documentation/content/xdocs/UsersGuide/validation.xml?rev=357350&r1=357349&r2=357350&view=diff
==============================================================================
---
jakarta/tapestry/branches/4.0/src/documentation/content/xdocs/UsersGuide/validation.xml
(original)
+++
jakarta/tapestry/branches/4.0/src/documentation/content/xdocs/UsersGuide/validation.xml
Sat Dec 17 09:20:59 2005
@@ -14,7 +14,6 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
"./dtd/document-v12.dtd"
[
<!ENTITY projectroot '../'>
@@ -32,8 +31,10 @@
<p>
The tapestry validation system provides a very powerful means of validating
data intuitively on most
- <link href="&apiroot;/form/IFormComponent.html">IFormComponent</link>
classes provided when working
- with form submissions.
+ of the form element components, such as &TextField;, &TextArea;, &Checkbox;,
and so forth. All of these
+ components implement the interface
+ <link href="&apiroot;/form/IFormComponent.html">IFormComponent</link>, and
include the necessary hooks to fit into
+ the overall validation framework.
</p>
<p>
Localization, server-side, and client side validation are handled by the
framework,
@@ -41,65 +42,210 @@
you see fit.
</p>
-<section id="validation.validfield">
- <title>ValidField component</title>
- <fixme author="Jesse Kuhnert" >
- The ValidField component and it's associated validators under
org.apache.tapestry.valid should be considered
- deprecated in favor of the new system found under
org.apache.tapestry.form.validator.
- </fixme>
-</section> <!-- validation.validfield -->
+ <p>
+ Validation has evolved over time (the first attempt at proper validation
using Tapestry occured back in 2001).
+ Through Tapestry 3, validation was limited to the &ValidField; component
(which is now deprecated).
+ For Tapestry 4, the APIs related to validation were effectively rewritten,
resulting in a more powerful, more
+ extensible approach that can be used with all kinds of form element
components.
+ </p>
<section id="validation.fieldlabel">
<title>FieldLabel component</title>
<p>
- By itself the <link href="&apiroot;/valid/FieldLabel.html">FieldLabel</link>
component doesn't do very much
- other than render the requisite labeling of form input fields as in:
+Generally speaking, every form input component (&TextField;, etc.) will be
paired with a &FieldLabel; component.
+The FieldLabel is responsible for generating the HTML <label> element,
which is extremely effective for
+accessible user interfaces (user interfaces that work for people with visual
disabilities). Typical usage:
</p>
- <source>
- <label>Password<label/>
- <input type="password" />
- </source>
+<source><![CDATA[
+<tr>
+ <td><label jwcid="@FieldLabel" field="component:userName">User
Name</label></td>
+ <td><input jwcid="[EMAIL PROTECTED]" value="ognl:userName"
validators="validators:required" displayName="User Name" size="30"/>
+</tr>
+]]></source>
+
<p>
- Combined with the validation system and some clever extensions to the
- <link
href="&apiroot;/valid/ValidationDelegate.html">ValidationDelegate</link> form
parameter(which can be used
- to decorate both the label <strong>and</strong> the field) it becomes very
- useful in applying formatting decorations to your fields when they contain
validation errors.
+ At runtime, this may render as:
+ </p>
+
+ <source><![CDATA[
+<tr>
+ <td><label for="userName">User Name</label></td>
+ <td><input name="userName" id="userName" value="" size="30"/>
+</tr>
+]]></source>
+
+ <p>
+ However, this is not all there is to FieldLabel. An important part of
validation is <em>decoration</em> of fields, to mark
+ when they contain errors. This is one of the responsibilities
&IValidationDelegate; ... decorating fields and labels.
+ </p>
+
+ <p>
+ If the above form is submitted without specifying a user name, the
userName field will be in error. The page will be redisplayed
+ to show the user the error message and the decorated fields and labels.
The <em>default</em> decoration is primitive, but effective:
</p>
+
+ <source><![CDATA[
+<tr>
+ <td><font color="red"><label for="userName">User Name</label></font></td>
+ <td><input name="userName" id="userName" value="" size="30"/> <font
color="red">**</font>
+</tr>
+]]></source>
+
+ <p>
+ By subclassing the default implementation of &IValidationDelegate; (the
&ValidationDelegate; class), you can change how these
+ decorations are rendered. It then becomes a matter of providing this custom
validation delegate to the &Form; component, via
+ its delegate parameter. This is covered in more detail shortly.
+ </p>
+
+ </section> <!-- validation.fieldlabel -->
+
+ <section id="validation.fields">
+ <title>Field validation</title>
+
+ <p>
+ Validation for form element components, such as &TextField;, is
controlled by two common component parameters
+ provided by all such components: validators and displayName.
+ </p>
+
+ <p>
+ The validators parameter provides a list of validator objects, objects
that implement the &Validator; interface.
+ Why a list? Unlike Tapestry 3 validation, each individual validator
checks just a single <em>constraint</em>.
+ Contraints are things like minimum string length, maximum string length,
minimum numeric value, etc. This is a very fine
+ grained approach, and one that is easily extensible to new contraints.
+ </p>
+
+ <p>
+ The displayName parameter is used to provide the label for the component
(perhaps some day, this parameter will be renamed to "label"; why
+ it has such a cumbersome name has been forgotten). In any case, this
label is used by the matching &FieldLabel; component,
+ and is also incorporated into an error messages created for the
component.
+ </p>
+
+ <section id="validation.validators">
+ <title>validators: binding prefix</title>
+
+
+ <p>
+ The validators: binding prefix is a powerful shorthand for
+ constructing a list of configured &Validator; objects. It allows a very
declarative style; for
+ example, to state that a field is required with a minimum length of four
characters,
+ the following parameter binding could be used (in a page or component
specification):
+ </p>
+ <source><![CDATA[
+<binding name="validators" value="validators:required,minLength=4"/>
+ ]]></source>
+
+ <p>
+ Notice that the actual type of the data isn't specified in this
instance, it is implied by which parameters
+ you specify. A specification is a comma-seperated list of entries. Each
entry is in one of the following forms:
+ </p>
+
+ <ul>
+ <li><em>name</em></li>
+ <li><em>name</em>=<em>value</em></li>
+ <li><em>name[<em>message</em>]</em></li>
+ <li><em>name</em>=<em>value</em>[<em>message</em>]</li>
+ <li>$<em>name</em></li>
+ </ul>
+
+ <p>
+ Most validator classes are <em>configurable</em>: they have a property
that matches their
+ name. For example, <link
href="&apiroot;/form/validator/MinDate.html">MinDate</link> (which is named
"minDate"
+ has a <code>minDate</code> property. A few validators are not
configurable ("required" =>
+ <link href="&apiroot;/form/validator/Required.html">Required</link>, for
example).
+ </p>
+ <p>
+ Validators are expected to have a public no-args constructor. They are
also expected to have a
+ <code>message</code> property which is set from the value in brackets.
+ The message is either a literal string, or may be prefixed with a '%'
character, to indicate
+ a localized key, resolved using the component's message catalog.
+ </p>
+ <p>
+ When the name is prefixed with a dollary sign, it indicates a reference
to a &spec.bean;
+ with the given name.
+ </p>
+ <p>
+ A full validator specification might be:
+ <code>required,email[%email-format],minLength=20[Email addresses must be
at least 20 characters long.]</code>
+ </p>
+
+ <p>
+ Here is a partial list of the validator classes provided and their
configurable attributes.
+ </p>
+ <fixme author="Jesse Kuhnert">
+ Fill in all of the possible attributes started in the table below.
+ </fixme>
+ <table>
+ <tr>
+ <th>&Validator;</th>
+ <th>attributes</th>
+ </tr>
+ <tr>
+ <td><link
href="&apiroot;/form/validator/BaseValidator.html">BaseValidator</link></td>
+ <td><code>message</code></td>
+ </tr>
+ <tr>
+ <td><link href="&apiroot;/form/validator/Email.html">Email</link></td>
+ <td><code>none, uses standard email regexp "[EMAIL
PROTECTED],6}$"</code></td>
+ </tr>
+ <tr>
+ <td><link href="&apiroot;/form/validator/Max.html">Max</link></td>
+ <td><code>max=<maximum value, 10></code></td>
+ </tr>
+ <tr>
+ <td><link
href="&apiroot;/form/validator/MaxDate.html">MaxDate</link></td>
+ <td><code>maxDate=<maximum date, 06/09/2010></code></td>
+ </tr>
+ <tr>
+ <td><link
href="&apiroot;/form/validator/MaxLength.html">MaxLength</link></td>
+ <td><code>maxLength=<maximum length, 23></code></td>
+ </tr>
+ <tr>
+ <td><link href="&apiroot;/form/validator/Min.html">Min</link></td>
+ <td><code>min=<minimum value, 0.718></code></td>
+ </tr>
+ <tr>
+ <td><link
href="&apiroot;/form/validator/MinDate.html">MinDate</link></td>
+ <td><code>minDate=<minimum date, 04/23/05></code></td>
+ </tr>
+ <tr>
+ <td><link
href="&apiroot;/form/validator/MinLength.html">MinLength</link></td>
+ <td><code>minLength=<minmum length, 15></code></td>
+ </tr>
+ </table>
+
+ <fixme author="Jesse Kuhnert">
+ Examples!
+ </fixme>
+
+ <fixme author="Jesse Kuhnert">
+ Write about how the validation constraints specified with the above
syntax are universally
+ applied on both the client and server-side, as well as how to override
the default behaviour
+ for displaying client-side validation messages via subclassing the
Tapestry.default_invalid_field_handler
+ javascript prototyped method.
+ </fixme>
+
+ </section> <!-- validation.validators -->
+
+ </section> <!-- validation.fields -->
+
+
<section id="validation.delegate">
<title>Extending ValidationDelegate</title>
- <p>
- By default all tapestry <link
href="&apiroot;/form/IForm.html">IForm</link> components come with a built-in
- validation delegate that will take a label similar to the example given
above and apply the
- following decorations to it:
- </p>
-
- <source>
- <font color="red"><label>Password<label/></font>
- <input type="password" /><font color="red">**</font>
- </source>
-
- <p>
- The <code>delegate</code> parameter of the form component allows you to
override the default
- <link
href="&apiroot;/valid/ValidationDelegate.html">ValidationDelegate</link> with
one of your own,
- in most cases simply extending the existing class to provide a little
extra functionality.
-
+
+ <p>
There are a lot of scenerios where you may wish to do something more
than that provided by the
- default, like apply a css class to labels in error, or even provide the
ability to render the error
- message directly in or around the label somehow.
+ default, like apply a CSS class to labels in error, or even provide the
ability to render the error
+ message directly in or around the label or field.
</p>
<p>
- Luckily the functionality of the <link
href="&apiroot;/valid/ValidationDelegate.html">ValidationDelegate</link>
- component is almost identical to what you would do with any other
component. Here is an example of a class
- that does exactly what we suggested above, extends the existing delegate
in order to apply a css class to
- the label instead of decorating it with red font elements, as well as
outputting the actual error message
- in question next to the field.
+ Below is a typical subclass of ValidationDelegate that provides more
application-specific decorations:
</p>
- <source>
+ <source><![CDATA[
/**
* Provides more intelligent validation delegate support.
*/
@@ -120,7 +266,7 @@
IFieldTracking ft = getCurrentFieldTracking();
//there is a default error renderer for fields which simply
//writes the message, which is what we want to have happen in this case
- if (ft != null && ft.getErrorRenderer() != null)
+ if (ft != null && ft.getErrorRenderer() != null)
ft.getErrorRenderer().render(writer, cycle);
}
@@ -135,186 +281,90 @@
}
}
- }
- </source>
+ }]]></source>
</section> <!-- validation.delegate -->
-</section> <!-- validation.fieldlabel -->
-
-<section id="validation.validators">
- <title>Validators/validators: binding prefix</title>
- <p>
- The new and improved validation system based off of the <link
href="&apiroot;/form/Validator.html">Validator</link> interface
- and <code>validators:</code> binding prefix provide a lot of functionality
while also minimizing the amount of
- code that needs to be written to support validation.
- </p>
-
- <p>
- The <code>validators: binding prefix</code> is a powerful shorthand for
- specifying validation properties that should be applied to a specific input
field. Such an expression might
- look something like:
- </p>
- <source>validators:required,minLength=4</source>
-
- <p>
- Notice that the actual type of the data isn't specified in this instance, it
is implied by which parameters
- you specify. A specification is a comma-seperated list of entries. Each
entry is in one of the following forms:
- </p>
-
- <ul>
- <li><em>name</em></li>
- <li><em>name</em>=<em>value</em></li>
- <li><em>name[<em>message</em>]</em></li>
- <li><em>name</em>=<em>value</em>[<em>message</em>]</li>
- <li>$<em>name</em></li>
- </ul>
-
- <p>
- Most validator classes are <em>configurable</em>: they have a property that
matches their
- name. For example, <link
href="&apiroot;/form/validator/MinDate.html">MinDate</link> (which is named
"minDate"
- has a <code>minDate</code> property. A few validators are not configurable
("required" =>
- <link href="&apiroot;/form/validator/Required.html">Required</link>, for
example).
- </p>
- <p>
- Validators are expected to have a public no-args constructor. They are also
expected to have a
- <code>message</code> property which is set from the value in brackets.
- The message is either a literal string, or may be prefixed with a '%'
character, to indicate
- a localized key, resolved using the component's message catalog.
- </p>
- <p>
- When the name is prefixed with a dollary sign, it indicates a reference to a
&spec.bean;
- with the given name.
- </p>
- <p>
- A full validator specification might be:
- <code>required,email[%email-format],minLength=20[Email addresses must be at
least 20 characters long.]</code>
- </p>
-
- <p>
- Here is a partial list of the validator classes provided and their
configurable attributes.
- </p>
- <fixme author="Jesse Kuhnert">
- Fill in all of the possible attributes started in the table below.
- </fixme>
- <table>
- <tr>
- <th>&Validator;</th>
- <th>attributes</th>
- </tr>
- <tr>
- <td><link
href="&apiroot;/form/validator/BaseValidator.html">BaseValidator</link></td>
- <td><code>message</code></td>
- </tr>
- <tr>
- <td><link href="&apiroot;/form/validator/Email.html">Email</link></td>
- <td><code>none, uses standard email regexp "[EMAIL
PROTECTED],6}$"</code></td>
- </tr>
- <tr>
- <td><link href="&apiroot;/form/validator/Max.html">Max</link></td>
- <td><code>max=<maximum value, 10></code></td>
- </tr>
- <tr>
- <td><link href="&apiroot;/form/validator/MaxDate.html">MaxDate</link></td>
- <td><code>maxDate=<maximum date, 06/09/2010></code></td>
- </tr>
- <tr>
- <td><link
href="&apiroot;/form/validator/MaxLength.html">MaxLength</link></td>
- <td><code>maxLength=<maximum length, 23></code></td>
- </tr>
- <tr>
- <td><link href="&apiroot;/form/validator/Min.html">Min</link></td>
- <td><code>min=<minimum value, 0.718></code></td>
- </tr>
- <tr>
- <td><link href="&apiroot;/form/validator/MinDate.html">MinDate</link></td>
- <td><code>minDate=<minimum date, 04/23/05></code></td>
- </tr>
- <tr>
- <td><link
href="&apiroot;/form/validator/MinLength.html">MinLength</link></td>
- <td><code>minLength=<minmum length, 15></code></td>
- </tr>
- </table>
-
- <fixme author="Jesse Kuhnert">
- Examples!
- </fixme>
-
- <fixme author="Jesse Kuhnert">
- Write about how the validation constraints specified with the above syntax
are universally
- applied on both the client and server-side, as well as how to override the
default behaviour
- for displaying client-side validation messages via subclassing the
Tapestry.default_invalid_field_handler
- javascript prototyped method.
- </fixme>
-</section> <!-- validation.validators -->
-
-<section id="validation.validator-binding">
- <title>(deprecated)validator: binding prefix </title>
-
- <fixme author="Jesse Kuhnert">
- The <code>validator:</code> binding prefix is actually valid, but causes
endless amounts of confusion and
- frustration as it is not obvious that this refers to the old validators( ie
- <link href="&apiroot;/valid/IValidator.html">IValidator</link> ), while
assumedly it is much preferred that
- people use the new validators via the <link
href="&apiroot;/form/Validator.html">Validator</link> interface
- instead. I don't even really understand what all the nuances and differences
are between them. Only that
- using the validators in here isn't really possible with any but the
ValidField component because of the
- interface changes.
- </fixme>
-
-<p>The validator: <link href="bindings.html">binding prefix</link> is a
powerful shorthand for specifying validators.
- The string provided does two things: it identifies (by a short logical
name) the Java class of the validator to create, and
- it specifies (as a comma seperated list) the properties of the validator to
set. The form of the string is:
- </p>
-
- <source>
-validator:<em>name</em>[,<em>property</em>[=<em>value</em>]]*
- </source>
+ <section id="validation.validfield">
+ <title>ValidField component</title>
+ <warning >
+ The ValidField component and it's associated validators under
org.apache.tapestry.valid should be considered
+ deprecated in favor of the new system found under
org.apache.tapestry.form.validator.
+ </warning>
+
+ <section id="validation.validator-binding">
+ <title>validator: binding prefix </title>
+
+ <p>
+ For &ValidField;, validation is specified through a single parameter,
validator.
+ The validator parameter is an object that implements the &IValidator;
interface. In Tapestry 3.0, it was necessary to
+ provide a configured Java object as the validator, using Java code, or
+ the specification's <bean> element.
+ </p>
+
+ <p>
+ Although the ValidField component is deprecated in release 4.0 (and
likely to be removed in a later release),
+ some legacy support for ValidField was added in release 4.0 ... a
special binding prefix, "validator:", that streamlines
+ the process of assembling a validator object for the validator
parameter.
+ </p>
+
+ <p>The validator: <link href="bindings.html">binding prefix</link> is a
powerful shorthand for specifying validators.
+ The string provided does two things: it identifies (by a short
logical name) the Java class of the validator to create, and
+ it specifies (as a comma seperated list) the properties of the
validator to set. The form of the string is:
+ </p>
+
+ <source>
+ validator:<em>name</em>[,<em>property</em>[=<em>value</em>]]*
+ </source>
+
+ <p>
+ The name corresponds to contributions to the tapestry.valid.Validators
configuration point. After the name is a list of properties to set.
+ A simple conversion from string value to actual data type is
performed. For boolean properties, the value can be skipped and will default
to true.
+ Alternatively, the value can be prefixed with an exclamation point,
and the property will be set to false. Example:
+ </p>
+
+ <source>
+ validator:string,required,minimumLength=5
+ </source>
+
+ <p>
+ In some cases, this is insufficiently powerful to set the properties
of the validator instance, in which case the &spec.bean; element can be used
+ instead.
+ </p>
+
+ <p>
+ The following validator names are defined:
+ </p>
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>&IValidator; implementation class</th>
+ </tr>
+ <tr>
+ <td>string</td> <td><link
href="&apiroot;/valid/StringValidator.html">StringValidator</link></td>
+ </tr>
+ <tr>
+ <td>date</td>
+ <td><link
href="&apiroot;/valid/DateValidator.html">DateValidator</link></td>
+ </tr>
+ <tr>
+ <td>email</td>
+ <td><link
href="&apiroot;/valid/EmailValidator.html">EmailValidator</link></td>
+ </tr>
+ <tr>
+ <td>url</td>
+ <td><link
href="&apiroot;/valid/UrlValidator.html">UrlValidator</link></td>
+ </tr>
+ <tr>
+ <td>int</td>
+ <td><link
href="&apiroot;/valid/IntValidator.html">IntValidator</link></td>
+ </tr>
+ </table>
+
+ </section> <!-- validation.validfield -->
+ </section> <!-- validation.validfield -->
-<p>
-The name corresponds to contributions to the tapestry.valid.Validators
configuration point. After the name is a list of properties to set.
-A simple conversion from string value to actual data type is performed. For
boolean properties, the value can be skipped and will default to true.
-Alternatively, the value can be prefixed with an exclamation point, and the
property will be set to false. Example:
-</p>
-
-<source>
-validator:string,required,minimumLength=5
-</source>
-
-<p>
-In some cases, this is insufficiently powerful to set the properties of the
validator instance, in which case the &spec.bean; element can be used
-instead.
-</p>
-<p>
-The following validator names are defined:
-</p>
-
-<table>
- <tr>
- <th>Name</th>
- <th>&IValidator; implementation class</th>
- </tr>
- <tr>
- <td>string</td> <td><link
href="&apiroot;/valid/StringValidator.html">StringValidator</link></td>
- </tr>
- <tr>
- <td>date</td>
- <td><link
href="&apiroot;/valid/DateValidator.html">DateValidator</link></td>
- </tr>
- <tr>
- <td>email</td>
- <td><link
href="&apiroot;/valid/EmailValidator.html">EmailValidator</link></td>
- </tr>
- <tr>
- <td>url</td>
- <td><link href="&apiroot;/valid/UrlValidator.html">UrlValidator</link></td>
- </tr>
- <tr>
- <td>int</td>
- <td><link href="&apiroot;/valid/IntValidator.html">IntValidator</link></td>
- </tr>
-</table>
-
-</section>
</body>
</document>
Modified: jakarta/tapestry/branches/4.0/status.xml
URL:
http://svn.apache.org/viewcvs/jakarta/tapestry/branches/4.0/status.xml?rev=357350&r1=357349&r2=357350&view=diff
==============================================================================
--- jakarta/tapestry/branches/4.0/status.xml (original)
+++ jakarta/tapestry/branches/4.0/status.xml Sat Dec 17 09:20:59 2005
@@ -60,6 +60,7 @@
<action type="fix" dev="HLS" fixes-bug="TAPESTRY-808">Engine Service
proxies don't correctly forward "post" parameter of
IEngineService.getLink</action>
<action type="add" dev="HLS" fixes-bug="TAPESTRY-790">Add Tapestry @
JavaForge as related project</action>
<action type="fix" dev="HLS" fixes-bug="TAPESTRY-760">Application
startup fails occasionally because of undefined order of contributions</action>
+ <action type="add" dev="JK">Document validation inside the Users
Guide</action>
</release>
<release version="4.0-rc-1" date="Dec 6 2005">
<action type="update" dev="HLS">Make default binding prefix
configurable</action>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
