You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by bu...@apache.org on 2015/08/01 23:19:50 UTC
svn commit: r960452 - in /websites/production/tapestry/content:
cache/main.pageCache forms-and-validation.html
Author: buildbot
Date: Sat Aug 1 21:19:50 2015
New Revision: 960452
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/forms-and-validation.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/forms-and-validation.html
==============================================================================
--- websites/production/tapestry/content/forms-and-validation.html (original)
+++ websites/production/tapestry/content/forms-and-validation.html Sat Aug 1 21:19:50 2015
@@ -67,7 +67,7 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><p><strong>Form input and validation</strong> is the most effective way for most web applications to gather significant information from the user. Whether it's a search form, a login screen or a multi-page registration wizard, forms are how the user really expresses themselves to the application.</p><div class="aui-label" style="float:right" title="Related Articles">
+<div id="ConfluenceContent"><p><strong>Forms</strong> are the traditional way for most web applications to gather significant information from the user. Whether it's a search form, a login screen or a multi-page registration wizard, Tapestry uses standard HTML forms, with HTTP POST actions by default. In addition, AJAX-based form submission is supported using <a shape="rect" href="ajax-and-zones.html">Zones</a>.</p><div class="aui-label" style="float:right" title="Related Articles">
@@ -106,19 +106,24 @@
</div>
</li></ul>
-</div><p>Tapestry excels at creating forms and validating input. Input validation is declarative, meaning you simply tell Tapestry what validations to apply to a given field, and it takes care of it on the server and (once implemented) on the client as well.</p><p>Finally, Tapestry is able to not only present the errors back to the user, but to decorate the fields and the labels for the fields, marking them as containing errors (primarily, using CSS effects).</p><p><strong>Contents</strong></p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1437945581375 {padding: 0px;}
-div.rbtoc1437945581375 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1437945581375 li {margin-left: 0px;padding-left: 0px;}
+</div><p> </p><p>Tapestry provides support for creating and rendering forms, populating their fields, and validating user input. For simple cases, input validation is declarative, meaning you simply tell Tapestry what validations to apply to a given field, and it takes care of it on the server and (optionally) on the client as well. In addition, you can provide event handler methods in your page or component classes to handle more complex validation scenarios.</p><p>Finally, Tapestry not only makes it easy to present errors messages to the user, but it can also automatically highlight form fields when validation fails.</p><p><strong>Contents</strong></p><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1438463978457 {padding: 0px;}
+div.rbtoc1438463978457 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1438463978457 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1437945581375">
+/*]]>*/</style></p><div class="toc-macro rbtoc1438463978457">
<ul class="toc-indentation"><li>Related Articles</li></ul>
<ul><li><a shape="rect" href="#FormsandValidation-TheFormComponent">The Form Component</a>
-<ul class="toc-indentation"><li><a shape="rect" href="#FormsandValidation-FormEvents">Form Events</a></li><li><a shape="rect" href="#FormsandValidation-TrackingValidationErrors">Tracking Validation Errors</a></li><li><a shape="rect" href="#FormsandValidation-StoringDataBetweenRequests">Storing Data Between Requests</a></li><li><a shape="rect" href="#FormsandValidation-ConfiguringFieldsandLabels">Configuring Fields and Labels</a></li><li><a shape="rect" href="#FormsandValidation-CentralizingValidationwith@Validate">Centralizing Validation with @Validate</a></li><li><a shape="rect" href="#FormsandValidation-ServerSideValidation">Server Side Validation</a></li><li><a shape="rect" href="#FormsandValidation-CustomizingValidationMessages">Customizing Validation Messages</a>
+<ul class="toc-indentation"><li><a shape="rect" href="#FormsandValidation-FormEvents">Form Events</a></li><li><a shape="rect" href="#FormsandValidation-HandlingEvents">Handling Events</a></li><li><a shape="rect" href="#FormsandValidation-TrackingValidationErrors">Tracking Validation Errors</a></li><li><a shape="rect" href="#FormsandValidation-StoringDataBetweenRequests">Storing Data Between Requests</a></li><li><a shape="rect" href="#FormsandValidation-ConfiguringFieldsandLabels">Configuring Fields and Labels</a></li><li><a shape="rect" href="#FormsandValidation-CentralizingValidationwith@Validate">Centralizing Validation with @Validate</a></li><li><a shape="rect" href="#FormsandValidation-ServerSideValidation">Server Side Validation</a></li><li><a shape="rect" href="#FormsandValidation-CustomizingValidationMessages">Customizing Validation Messages</a>
<ul class="toc-indentation"><li><a shape="rect" href="#FormsandValidation-CustomizingValidationMessagesforBeanEditForm">Customizing Validation Messages for BeanEditForm</a></li></ul>
</li><li><a shape="rect" href="#FormsandValidation-ConfiguringValidatorContraintsintheMessageCatalog">Configuring Validator Contraints in the Message Catalog</a></li><li><a shape="rect" href="#FormsandValidation-ValidationMacros">Validation Macros</a></li><li><a shape="rect" href="#FormsandValidation-OverridingtheTranslatorwithEvents">Overriding the Translator with Events</a></li></ul>
-</li></ul></div><h1 id="FormsandValidation-TheFormComponent">The Form Component</h1><p>The core of Tapestry's form support is the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html">Form</a> component. The Form component encloses (wraps around) all the other <em>field components</em> such as <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextField.html">TextField</a>, <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextArea.html">TextArea</a>, <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Checkbox.html">Checkbox</a>, etc.</p><h2 id="FormsandValidation-FormEvents">Form Events</h2><p>The Form component emits a number of <a shape="rect" href="component-events.html">
component events</a>. You'll need to provide event handler methods for some of these.</p><p>When rendering, the Form component emits two notifications: first, "prepareForRender", then "prepare". These allow the Form's container to setup any fields or properties that will be referenced in the form. For example, this is a good place to create a temporary entity object to be rendered, or to load an entity from a database to be edited.</p><p>When user submits the form on the client, a series of steps occur on the server.</p><p>First, the Form emits a "prepareForSubmit" notification, then a "prepare" notification. These allow the container to ensure that objects are set up and ready to receive information from the form submission.</p><p>Next, all the fields inside the form are activated to pull values out of the incoming request, validate them and (if valid) store the changes.</p><div class="navmenu" style="float:right; width:25%; background:#eee; margin:3px; padding:3px">
-<p><em>For Tapestry 4 Users:</em> Tapestry 5 does not use the fragile "form rewind" approach from Tapestry 4. Instead, a hidden field generated during the render stores the information needed to process the form submission.</p></div>After the fields have done their processing, the Form emits a "validate" event. This is a chance to perform cross-form validation that can't be described declaratively.<p>Note: For compatibility with release 5.1 and earlier, the Form component also emits a "validateForm" event. (See <a shape="rect" class="external-link" href="https://issues.apache.org/jira/browse/TAP5-760">TAP5-760</a>.)</p><p>Next, the Form determines if there have been any validation errors. If there have been, then the submission is considered a failure, and a "failure" event is emitted. If there have been no validation errors, then a "success" event is emitted.</p><p>Finally, the Form emits a "submit" event, for logic that doesn't care about success or failure.</p><div class="table-w
rap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Form Event (in order)</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Phase</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>When emitted</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Typical use</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>prepareForRender</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Render</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before rendering the form</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Load an entity from a database to be edited</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>prepare</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Render</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before rendering the form, but after <em>prepareForRender</em></p></td><td colspan="1" rowspan="1" class="confluenceTd
"><p> </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>prepareForSubmit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before the submitted form is processed</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>prepare</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before the submitted form is processed, but after <em>prepareForSubmit</em></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>validate</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After fields have been populated from submitted values and validated</p></td><td colspan="1" rowspan="1" class="co
nfluenceTd"><p>Perform cross-field validation</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>validateForm</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>same as <em>validate</em></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><em>deprecated</em></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>failure</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After one or more validation errors have occurred</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>success</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>When validation has completed <em>without</em> any errors</p></td><td colspan="1" rowspan="1" class="confluence
Td"><p>Save changes to the database</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After all validation (success or failure) has finished</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr></tbody></table></div><p>Note that the "prepare" event is emitted during both form rendering and form submission.</p><h2 id="FormsandValidation-TrackingValidationErrors">Tracking Validation Errors</h2><p>Associated with the Form is a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValidationTracker.html">ValidationTracker</a> that tracks all the provided user input and validation errors for every field in the form. The tracker can be provided to the Form via the Form's tracker parameter, but this is rarely necessary.</p><p>The Form includes methods <code>is
Valid()</code> and <code>getHasErrors()</code>, which are used to see if the Form's validation tracker contains any errors.</p><p>In your own logic, it is possible to record your own errors. Form includes two different versions of method <code>recordError()</code>, one of which specifies a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Field.html">Field</a> (an interface implemented by all form element components), and one of which is for "global" errors, unassociated with any particular field.</p><h2 id="FormsandValidation-StoringDataBetweenRequests">Storing Data Between Requests</h2><p></p><div class="navmenu" style="float:right; width:40%; background:white; margin:3px; padding:3px">
+</li></ul></div><h1 id="FormsandValidation-TheFormComponent">The Form Component</h1><p>The core of Tapestry's form support is the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html">Form</a> component. The Form component encloses (wraps around) all the other <em>field components</em> such as <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextField.html">TextField</a>, <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextArea.html">TextArea</a>, <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Checkbox.html">Checkbox</a>, etc.</p><h2 id="FormsandValidation-FormEvents">Form Events</h2><p>The Form component emits a number of <a shape="rect" href="component-events.html">
component events</a>. You'll want to provide event handler methods for some of these.</p><p>When rendering, the Form component emits two events: first, "prepareForRender", then "prepare". These allow the Form's container to set up any fields or properties that will be referenced in the form. For example, this is a good place to create a temporary entity object to be rendered, or to load an entity from a database to be edited.</p><p>When user submits the form on the client, a series of steps occur on the server.</p><p>First, the Form emits a "prepareForSubmit" event, then a "prepare" event. These allow the container to ensure that objects are set up and ready to receive information from the form submission.</p><p>Next, all the fields inside the form are <em>activated</em> to pull values out of the incoming request, validate them and (if valid) store the changes.</p><div class="navmenu" style="float:right; width:25%; background:#eee; margin:3px; padding:3px">
+<p><em>For Tapestry 4 Users:</em> Tapestry 5 does not use the fragile "form rewind" approach from Tapestry 4. Instead, a hidden field generated during the render stores the information needed to process the form submission.</p></div> <p>After the fields have done their processing, the Form emits a "validate" event. This is your chance to perform any cross-form validation that can't be described declaratively.</p><p>Next, the Form determines if there have been any validation errors. If there have been, then the submission is considered a failure, and a "failure" event is emitted. If there have been no validation errors, then a "success" event is emitted.</p><p>Finally, the Form emits a "submit" event, for logic that doesn't care about success or failure.</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Form Event (in order)</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Phase</p></th><th colspan
="1" rowspan="1" class="confluenceTh"><p>When emitted (and typical use)</p></th><th colspan="1" rowspan="1" class="confluenceTh">Method Name</th><th colspan="1" rowspan="1" class="confluenceTh">@OnEvent Constant</th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>prepareForRender</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Render</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before rendering the form (e.g. load an entity from a database to be edited)</p></td><td colspan="1" rowspan="1" class="confluenceTd">onPrepareForRender()</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.PREPARE_FOR_RENDER</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>prepare</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Render</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before rendering the form, but after <em>prepareForRender</em></p></td><td colspan="1" rowspan="1" c
lass="confluenceTd">onPrepare()</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.PREPARE</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>prepareForSubmit</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before the submitted form is processed</p></td><td colspan="1" rowspan="1" class="confluenceTd">onPrepareForSubmit()</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.PREPARE_FOR_SUBMIT</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>prepare</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before the submitted form is processed, but after <em>prepareForSubmit</em></p></td><td colspan="1" rowspan="1" class="confluenceTd">onPrepare()</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.PREPARE</td></tr><tr><td cols
pan="1" rowspan="1" class="confluenceTd"><p><strong>validate</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After fields have been populated from submitted values and validated (e.g. perform cross-field validation)</p></td><td colspan="1" rowspan="1" class="confluenceTd">onValidate</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.VALIDATE</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>validateForm</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>same as <em>validate (deprecated – do not use)<br clear="none"></em></p></td><td colspan="1" rowspan="1" class="confluenceTd"><em>onValidateForm</em></td><td colspan="1" rowspan="1" class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>failure</strong></p></td><td colspan=
"1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After one or more validation errors have occurred</p></td><td colspan="1" rowspan="1" class="confluenceTd">onFailure()</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.FAILURE</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>success</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>When validation has completed <em>without</em> any errors (e.g. save changes to the database)</p></td><td colspan="1" rowspan="1" class="confluenceTd">onSuccess()</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.SUCCESS</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>submit</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After all validation (s
uccess or failure) has finished</p></td><td colspan="1" rowspan="1" class="confluenceTd">onSubmit()</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.SUBMIT</td></tr></tbody></table></div><p>Note that the "prepare" event is emitted during both form rendering and form submission.</p><h2 id="FormsandValidation-HandlingEvents">Handling Events</h2><p>Main Article: <a shape="rect" href="component-events.html">Component Events</a></p><p>You handle events by providing methods in your page or component class, either following the on<strong><em>Event</em></strong>From<strong><em>Component</em></strong>() naming convention or using the OnEvent annotation. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Event Handler Using Naming Convention</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> void onValidateFromPassword() { ...}</pre>
+</div></div><p>or the equivalent using @OnEvent:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Event Handler Using @OnEvent Annotation</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @OnEvent(value=EventConstants.VALIDATE, component="password")
+ void verifyThePassword() { ...}</pre>
+</div></div><h2 id="FormsandValidation-TrackingValidationErrors">Tracking Validation Errors</h2><p>Associated with the Form is a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValidationTracker.html">ValidationTracker</a> that tracks all the provided user input and validation errors for every field in the form. The tracker can be provided to the Form via the Form's tracker parameter, but this is rarely necessary.</p><p>The Form includes methods <code>isValid()</code> and <code>getHasErrors()</code>, which are used to see if the Form's validation tracker contains any errors.</p><p>In your own logic, it is possible to record your own errors. Form includes two different versions of method <code>recordError()</code>, one of which specifies a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Field.html">Field</a> (an interface implemented by all form element components),
and one of which is for "global" errors, not associated with any particular field. If the error concerns only a single field, you should use the first version so that the field will be highlighted.</p><h2 id="FormsandValidation-StoringDataBetweenRequests">Storing Data Between Requests</h2><p></p><div class="navmenu" style="float:right; width:40%; background:white; margin:3px; padding:3px">
<div class="confluence-information-macro confluence-information-macro-information"><p class="title">New in Tapestry 5.4</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
<p>Starting in Tapestry 5.4, the default behavior for server-side validation failures is to re-render the page within the same request (rather than emitting a redirect). This removes the need to use a session-persistent field to store the validation tracker when validation failures occur.</p></div></div></div>As with other action requests, the result of a form submission (except when using <a shape="rect" href="ajax-and-zones.html">Zones</a>) is to send a redirect to the client, which results in a second request (to re-render the page). The ValidationTracker must be <a shape="rect" href="persistent-page-data.html">persisted</a> (generally in the HttpSession) across these two requests in order to prevent the loss of validation information. Fortunately, the default ValidationTracker provided by the Form component is persistent, so you don't normally have to worry about it.<p>However, for the same reason, the individual fields updated by the components should also be persisted across r
equests, and this is something you <strong>do</strong> need to do yourself – generally with the @Persist annotation.</p><p>For example, a Login page, which collects a user name and a password, might look like:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package com.example.newapp.pages;