You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bu...@apache.org on 2020/01/11 14:19:50 UTC
svn commit: r1055133 - in /websites/production/tapestry/content:
cache/main.pageCache forms-and-validation.html getting-started.html
project-layout.html
Author: buildbot
Date: Sat Jan 11 14:19:50 2020
New Revision: 1055133
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/forms-and-validation.html
websites/production/tapestry/content/getting-started.html
websites/production/tapestry/content/project-layout.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 Jan 11 14:19:50 2020
@@ -121,12 +121,12 @@
</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.rbtoc1578179971927 {padding: 0px;}
-div.rbtoc1578179971927 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1578179971927 li {margin-left: 0px;padding-left: 0px;}
+<p><br clear="none"></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.rbtoc1578752367938 {padding: 0px;}
+div.rbtoc1578752367938 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1578752367938 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1578179971927">
+/*]]>*/</style></p><div class="toc-macro rbtoc1578752367938">
<ul class="toc-indentation"><li>Related Articles</li></ul>
<ul><li><a href="#FormsandValidation-TheFormComponent">The Form Component</a>
<ul class="toc-indentation"><li><a href="#FormsandValidation-FormEvents">Form Events</a></li><li><a href="#FormsandValidation-HandlingEvents">Handling Events</a></li><li><a href="#FormsandValidation-TrackingValidationErrors">Tracking Validation Errors</a></li><li><a href="#FormsandValidation-StoringDataBetweenRequests">Storing Data Between Requests</a></li><li><a href="#FormsandValidation-ConfiguringFieldsandLabels">Configuring Fields and Labels</a></li></ul>
@@ -135,14 +135,14 @@ div.rbtoc1578179971927 li {margin-left:
<ul class="toc-indentation"><li><a href="#FormsandValidation-CustomizingValidationMessagesforBeanEditForm">Customizing Validation Messages for BeanEditForm</a></li></ul>
</li><li><a href="#FormsandValidation-ConfiguringValidatorContraintsintheMessageCatalog">Configuring Validator Contraints in the Message Catalog</a></li><li><a href="#FormsandValidation-ValidationMacros">Validation Macros</a></li><li><a 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 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 class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextField.html">TextField</a>, <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextArea.html">TextArea</a>, <a 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 href="component-events.html">component events</a>. You'll want to provide event handler m
ethods 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> </p><p><br clear="none"></p><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"><colgroup span="1"><col span="1"><col span="1"><col span="1"><col span="1"><col span="1"></colgroup><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" rowsp
an="1" class="confluenceTd"><p>Before rendering the form, but after <em>prepareForRender</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 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 colspan="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 (success 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><tr><td colspan="1" rowspan="1" class="confluenceTd"><strong>canceled</strong></td><td colspan="1" rowspan="1" class="confluenceTd">Submit</td><td colspan="1" rowspan="1" class="confluenceTd">Whenever a <em>Submit</em> or <em>LinkSubmit</em> component containing <em>mode="cancel"</em> or <em>mode="unconditional"</em> is clicked</td><td colspan="1" rowspan="1" class="confluenceTd">onCanceled()</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.CANCELED</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
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">
+<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><br clear="none"><p><br clear="none"></p><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="wrapped confluenceTable"><colgroup span="1"><col span="1"><col span="1"><col span="1"><col span="1"><col span="1"></colgroup><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 colsp
an="1" rowspan="1" class="confluenceTd"><p>Before rendering the form, but after <em>prepareForRender</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 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 colspan="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"><br clear="none"></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</stro
ng></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">onSubmit()</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.SUBMIT</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><strong>canceled</strong></td><td colspan="1" rowspan="1" class="confluenceTd">Submit</td><td colspan="1" rowspan="1" class="confluenceTd">Whenever a <em>Submit</em> or <em>LinkSubmit</em> component containing <em>mode="cancel"</em> or <em>mode="unconditional"</em> is clicked</td><td colspan="1" rowspan="1" class="confluenceTd">onCanceled()</td><td colspan="1" rowspan="1" class="confluenceTd">EventConstants.CANCELED</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 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="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default"> 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="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default"> @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 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 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><br clear="none"></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><p>As with other action requests, the result of a form submission (except when using <a href="forms-and-validation.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 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><p><br clear="none"></p><p>However, for the same reason, the individual fields updated by the components should also be persi
sted across requests, and this is something you <strong>do</strong> need to do yourself – generally with the @Persist annotation.</p><p>For example, a Login page class, which collects a user name and a password, might look like:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Login.java Example</b></div><div class="codeContent panelContent pdl">
+<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 href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=84805477">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 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><br clear="none"></p><p>However, for the same reason, the individual fields updat
ed by the components should also be persisted across requests, and this is something you <strong>do</strong> need to do yourself – generally with the @Persist annotation.</p><p>For example, a Login page class, which collects a user name and a password, might look like:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Login.java Example</b></div><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default">package com.example.newapp.pages;
@@ -192,7 +192,7 @@ public class Login {
</pre>
</div></div><p><br clear="none"></p><div class="navmenu" style="float:right; width:40%; background:white; margin:3px; padding:3px">
<div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
-<p>Note that the onValidateFromLoginForm() and onSuccess() methods are not public; event handler methods can have any visibility, even private. Package private (that is, no modifier) is the typical use, as it allows the component to be tested, from a test case class in the same package.</p></div></div></div><p>Because a form submission is really <em>two</em> requests: the submission itself (which results in a redirect response), then a second request for the page (which results in a re-rendering of the page), it is necessary to persist the userName field between the two requests, by using the @Persist annotation. This would be necessary for the password field as well, except that the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/PasswordField.html">PasswordField</a> component never renders a value.</p><p><br clear="none"></p><div class="confluence-information-macro confluence-information-macro-tip"><span class="aui
-icon aui-icon-small aui-iconfont-approve confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>To avoid data loss, fields whose values are stored in the HttpSession (such as userName, above) must be serializable, particularly if you want to be able to cluster your application or preserve sessions across server restarts.</p></div></div><p>The Form only emits a "success" event if the there are no prior validation errors. This means it is not necessary to write <code>if (form.getHasErrors()) return;</code> as the first line of the method.</p><p>Finally, notice how business logic fits into validation. The UserAuthenticator service is responsible for ensuring that the userName and (plaintext) password are valid. When it returns false, we ask the Form component to record an error. We provide the PasswordField instance as the first parameter; this ensures that the password field, and its label, are decorated when the Form is re-rendered, to present th
e errors to the user.</p><h2 id="FormsandValidation-ConfiguringFieldsandLabels">Configuring Fields and Labels</h2><p>The Login page template below contains a minimal amount of Tapestry instrumentation and references some of the <a class="external-link" href="http://getbootstrap.com" rel="nofollow">Bootstrap</a> CSS classes (Bootstrap is automatically integrated into each page by default, starting with Tapestry 5.4).</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Login.tml Example</b></div><div class="codeContent panelContent pdl">
+<p>Note that the onValidateFromLoginForm() and onSuccess() methods are not public; event handler methods can have any visibility, even private. Package private (that is, no modifier) is the typical use, as it allows the component to be tested, from a test case class in the same package.</p></div></div></div>Because a form submission is really <em>two</em> requests: the submission itself (which results in a redirect response), then a second request for the page (which results in a re-rendering of the page), it is necessary to persist the userName field between the two requests, by using the @Persist annotation. This would be necessary for the password field as well, except that the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/PasswordField.html">PasswordField</a> component never renders a value.<p><br clear="none"></p><div class="confluence-information-macro confluence-information-macro-tip"><span class="aui-icon a
ui-icon-small aui-iconfont-approve confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>To avoid data loss, fields whose values are stored in the HttpSession (such as userName, above) must be serializable, particularly if you want to be able to cluster your application or preserve sessions across server restarts.</p></div></div><p>The Form only emits a "success" event if the there are no prior validation errors. This means it is not necessary to write <code>if (form.getHasErrors()) return;</code> as the first line of the method.</p><p>Finally, notice how business logic fits into validation. The UserAuthenticator service is responsible for ensuring that the userName and (plaintext) password are valid. When it returns false, we ask the Form component to record an error. We provide the PasswordField instance as the first parameter; this ensures that the password field, and its label, are decorated when the Form is re-rendered, to present the error
s to the user.</p><h2 id="FormsandValidation-ConfiguringFieldsandLabels">Configuring Fields and Labels</h2><p>The Login page template below contains a minimal amount of Tapestry instrumentation and references some of the <a class="external-link" href="http://getbootstrap.com" rel="nofollow">Bootstrap</a> CSS classes (Bootstrap is automatically integrated into each page by default, starting with Tapestry 5.4).</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Login.tml Example</b></div><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: xml; gutter: false; theme: Default" data-theme="Default"><html t:type="layout" title="newapp com.example"
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
@@ -209,15 +209,15 @@ public class Login {
</html>
</pre>
-</div></div><p>Rendering the page gives a reasonably pleasing first pass:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border image-center" width="500" src="https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2" data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2"></span></p><p>The Tapestry Form component is responsible for creating the necessary URL for the form submission (this is Tapestry's responsibility, not yours).</p><p><span>For the TextField, we provide a component id, userName. We could specify the </span><code>value</code><span> parameter, but the default is to match the TextField's id against a property of the cont
ainer, the Login page, if such a property exists. </span></p><p>As a rule of thumb, you should always give your fields a specific id (this id will be used to generate the <code>name</code> and <code>id</code> attributes of the rendered tag). Being allowed to omit the value parameter helps to keep the template from getting too cluttered.</p><p>The FormGroup mixin decorates the field with some additional markup, including a <label> element; this leverages more of Bootstrap.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>userName component as rendered</b></div><div class="codeContent panelContent pdl">
+</div></div><p>Rendering the page gives a reasonably pleasing first pass:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border image-center" width="500" src="forms-and-validation.data/newapp_com_example.png" data-image-src="https://cwiki.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2"></span></p><p>The Tapestry Form component is responsible for creating the necessary URL for the form submission (this is Tapestry's responsibility, not yours).</p><p><span>For the TextField, we provide a component id, userName. We could specify the </span><code>value</code><span> parameter, but the default is to match the TextField's id against a property of the container, the Login page, if such a property exists. </span></p><p>As a rule of thumb, you should always
give your fields a specific id (this id will be used to generate the <code>name</code> and <code>id</code> attributes of the rendered tag). Being allowed to omit the value parameter helps to keep the template from getting too cluttered.</p><p>The FormGroup mixin decorates the field with some additional markup, including a <label> element; this leverages more of Bootstrap.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>userName component as rendered</b></div><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: xml; gutter: false; theme: Default" data-theme="Default"><div class="form-group">
<label for="userName" class="control-label">User Name</label>
<input id="userName" class="form-control" name="userName" type="text">
</div></pre>
-</div></div><p> </p><h1 id="FormsandValidation-FormValidation"><span style="color: rgb(83,145,38);">Form Validation</span></h1><p>The above example is a very basic form which allows the fields to be empty. However, with a little more effort we can add client-side validation to prevent the user from submitting the form with either field empty.</p><p>Validation in Tapestry involves associating one or more <em>validators</em> with a form element component, such as TextField or PasswordField. This is done using the <strong>validate</strong> parameter:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p><br clear="none"></p><h1 id="FormsandValidation-FormValidation"><span style="color: rgb(83,145,38);">Form Validation</span></h1><p>The above example is a very basic form which allows the fields to be empty. However, with a little more effort we can add client-side validation to prevent the user from submitting the form with either field empty.</p><p>Validation in Tapestry involves associating one or more <em>validators</em> with a form element component, such as TextField or PasswordField. This is done using the <strong>validate</strong> parameter:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: xml; gutter: false; theme: Default" data-theme="Default"><t:textfield t:id="userName" validate="required" t:mixins="formgroup"/>
<t:passwordfield t:id="password" value="password" validate="required" t:mixins="formgroup"/></pre>
-</div></div><h2 id="FormsandValidation-AvailableValidators"><span style="color: rgb(83,145,38);">Available Validators</span></h2><p>Tapestry provides the following built-in validators:</p><div class="table-wrap"><table class="confluenceTable"><colgroup span="1"><col span="1"><col span="1"><col span="1"><col span="1"></colgroup><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Validator</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Constraint Type</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Example</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>email</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>–</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Ensures that the given input looks like a valid e-mail address</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="userEmail" validate="ema
il" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>max</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>long</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Enforces a maximum integer value</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="age" validate="max=120,min=0" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>maxLength</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Makes sure that a string value has a maximum length</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="zip" validate="maxlength=7" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>min</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>long</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Enforces a minimum integer value</
p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="age" validate="max=120,min=0" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>minLength</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Makes sure that a string value has a minimum length</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="somefield" validate="minlength=1" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>none</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>–</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Does nothing (used to override a @Validate annotation)</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="somefield" validate="none" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>regexp</p></td><td c
olspan="1" rowspan="1" class="confluenceTd"><p>pattern</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Makes sure that a string value conforms to a given pattern</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="letterfield" validate="regexp=^</code><code>[A-Za-z]+$" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>required</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>–</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Makes sure that a string value is not null and not the empty string</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="name" validate="required" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">checked <em>(Since 5.4.5)</em></td><td colspan="1" rowspan="1" class="confluenceTd">boolean</td><td colspan="1" rowspan="1" class="confluenceTd">Makes sure that the boolean is true (checkbox is che
cked)</td><td colspan="1" rowspan="1" class="confluenceTd"><code><t:Checkbox value="value" validate="checked" /></code></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">unchecked <em>(Since 5.4.5)</em></td><td colspan="1" rowspan="1" class="confluenceTd">boolean</td><td colspan="1" rowspan="1" class="confluenceTd"><span>Makes sure that the boolean is false (checkbox is unchecked)</span></td><td colspan="1" rowspan="1" class="confluenceTd"><code><t:Checkbox value="value" validate="unchecked" /></code></td></tr></tbody></table></div><h2 id="FormsandValidation-CentralizingValidationwith@Validate">Centralizing Validation with @Validate</h2><p>The @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html">Validate</a> annotation can take the place of the validate parameter of TextField, PasswordField, TextArea and other components. When the validate parameter is not bound in the template file, the co
mponent will check for the @Validate annotation and use its value as the validation definition.</p><p>The annotation may be placed on the getter or setter method, or on the field itself.</p><p>Let's update the two fields of the Login page:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h2 id="FormsandValidation-AvailableValidators"><span style="color: rgb(83,145,38);">Available Validators</span></h2><p>Tapestry provides the following built-in validators:</p><div class="table-wrap"><table class="wrapped confluenceTable"><colgroup span="1"><col span="1"><col span="1"><col span="1"><col span="1"></colgroup><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Validator</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Constraint Type</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Example</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>email</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>–</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Ensures that the given input looks like a valid e-mail address</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="userEmail" valid
ate="email" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>max</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>long</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Enforces a maximum integer value</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="age" validate="max=120,min=0" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>maxLength</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Makes sure that a string value has a maximum length</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="zip" validate="maxlength=7" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>min</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>long</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Enforces a minimum integer
value</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="age" validate="max=120,min=0" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>minLength</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Makes sure that a string value has a minimum length</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="somefield" validate="minlength=1" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>none</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>–</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Does nothing (used to override a @Validate annotation)</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="somefield" validate="none" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>regexp</p></
td><td colspan="1" rowspan="1" class="confluenceTd"><p>pattern</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Makes sure that a string value conforms to a given pattern</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="letterfield" validate="regexp=^</code><code>[A-Za-z]+$" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>required</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>–</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Makes sure that a string value is not null and not the empty string</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="name" validate="required" /></code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">checked <em>(Since 5.4.5)</em></td><td colspan="1" rowspan="1" class="confluenceTd">boolean</td><td colspan="1" rowspan="1" class="confluenceTd">Makes sure that the boolean is true (checkbo
x is checked)</td><td colspan="1" rowspan="1" class="confluenceTd"><code><t:Checkbox value="value" validate="checked" /></code></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">unchecked <em>(Since 5.4.5)</em></td><td colspan="1" rowspan="1" class="confluenceTd">boolean</td><td colspan="1" rowspan="1" class="confluenceTd"><span>Makes sure that the boolean is false (checkbox is unchecked)</span></td><td colspan="1" rowspan="1" class="confluenceTd"><code><t:Checkbox value="value" validate="unchecked" /></code></td></tr></tbody></table></div><h2 id="FormsandValidation-CentralizingValidationwith@Validate">Centralizing Validation with @Validate</h2><p>The @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html">Validate</a> annotation can take the place of the validate parameter of TextField, PasswordField, TextArea and other components. When the validate parameter is not bound in the template file
, the component will check for the @Validate annotation and use its value as the validation definition.</p><p>The annotation may be placed on the getter or setter method, or on the field itself.</p><p>Let's update the two fields of the Login page:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default"> @Persist
@Property
@Validate("required")
@@ -226,7 +226,7 @@ public class Login {
@Property
@Validate("required")
private String password;</pre>
-</div></div><p>Now, we'll rebuild the app, refresh the browser, and just hit enter:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border image-center" width="500" src="https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2" data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2"></span></p><p>The form has updated, in place, to present the errors. You will not be able to submit the form until some value is provided for each field.</p><h2 id="FormsandValidation-HTML5Client-sideValidation">HTML5 Client-side Validation</h2><p>When the <a href="configuration.html"><code>tapestry.enable-html5-support</code></a> <span class="conflue
nce-link">configuration symbol</span> is set to true (it is <strong><em>false</em></strong> by default), the Tapestry's built-in validators will automatically enable the HTML5-specific "type" and validation attributes to the rendered HTML of Tapestry's form components, triggering the HTML5 client-side validation behavior built into most modern browsers. For example, if you use the "email" and "required" validators, like this:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Now, we'll rebuild the app, refresh the browser, and just hit enter:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border image-center" width="500" src="forms-and-validation.data/newapp_com_example.png" data-image-src="https://cwiki.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2"></span></p><p>The form has updated, in place, to present the errors. You will not be able to submit the form until some value is provided for each field.</p><h2 id="FormsandValidation-HTML5Client-sideValidation">HTML5 Client-side Validation</h2><p>When the <a href="configuration.html"><code>tapestry.enable-html5-support</code></a> <span class="confluence-link">configuration symbol</span> is set to true (it is <strong><em>false</em></strong> by default), t
he Tapestry's built-in validators will automatically enable the HTML5-specific "type" and validation attributes to the rendered HTML of Tapestry's form components, triggering the HTML5 client-side validation behavior built into most modern browsers. For example, if you use the "email" and "required" validators, like this:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: xml; gutter: false; theme: Default" data-theme="Default"><t:textfield validate="email,required" .../></pre>
</div></div><p>then the output HTML will look like this:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: xml; gutter: false; theme: Default" data-theme="Default"><input type="email" required ...></pre>
@@ -242,7 +242,7 @@ public class Login {
}
</pre>
-</div></div><p>This is the validate event handler from the loginForm component. It is invoked once all the components have had a chance to read values out of the request, do their own validations, and update the properties they are bound to.</p><p>In this case, the authenticator is used to decide if the userName and password is valid. In a real application, this would be where a database or other external service was consulted.</p><p>If the combination is not valid, then the password field is marked as in error. The form is used to record an error, about a component (the passwordField) with an error message.</p><p>Entering any two values into the form and submitting will cause a round trip; the form will re-render to present the error to the user:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border image-center" width="500" src="htt
ps://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2" data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2"></span></p><p>Notice that the cursor is placed directly into the password field.</p><div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>In versions of Tapestry prior to 5.4, a form with validation errors would result in a redirect response to the client; often, temporary server-side data (such as the userName field) would be lost. Starting in 5.4, submitting a form with validation errors results in the new page being rendered in the same request as the form submission.</p></div></div><h2 id="FormsandVal
idation-CustomizingValidationMessages">Customizing Validation Messages</h2><p>Each validator (such as "required" or "minlength") has a default message used (on the client side and the server side) when the constraint is violated; that is, when the user input is not valid.</p><p>The message can be customized by adding an entry to the page's <a href="localization.html">message catalog</a> (or the containing component's message catalog). As with any localized property, this can also go into the application's message catalog.</p><p>The first key checked is <em>formId</em>-<em>fieldId</em>-<em>validatorName</em>-message.</p><ul><li>formId: the local component id of the Form component</li><li>fieldId: the local component id of the field (TextField, etc.)</li><li>validatorName: the name of the validator, i.e., "required" or "minlength"</li></ul><p>If there is no message for that key, a second check is made, for <em>fieldId</em>-<em>validatorName</em>-message. <span>If</span><span>
60;that does not match a message, then the built-in default validation message is used.</span></p><p><span>For example, if the form ID is "loginForm", the field ID is "userName", and the validator is "required" then Tapestry will first look for a "loginForm-userName-required-message" key in the message catalog, and then for a "<span>userName-required-message" key.</span></span></p><p>The validation message in the message catalog may contain <a class="external-link" href="https://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html" rel="nofollow">printf-style format strings</a> (such as %s) to indicate where the validate parameter's value will be inserted. For example, if the validate parameter in the template is minLength=3 and the validation message is "User name must be at least %s characters" then the corresponding error message would be <span>"User name must be at least 5 characters".</span></p><h3 id="FormsandValidation-CustomizingValidationMessagesforBeanEdit
Form">Customizing Validation Messages for BeanEditForm</h3><p>The <a href="beaneditform-guide.html">BeanEditForm</a> component also supports validation message customizing. The search for messages is similar; the <em>formId</em> is the component id of the BeanEditForm component (not the Form component it contains). The <em>fieldId</em> is the property name.</p><h2 id="FormsandValidation-ConfiguringValidatorContraintsintheMessageCatalog">Configuring Validator Contraints in the Message Catalog</h2><p>It is possible to omit the validation constraint from the validate parameter (or @Validator annotation), in which case it is expected to be stored in the message catalog.</p><p>This is useful when the validation constraint is awkward to enter inline, such as a regular expression for use with the regexp validator.</p><p>The key here is similar to customizing the validation message: <em>formId</em>-<em>fieldId</em>-<em>validatorName</em> or just <em>fieldId</em>-<em>validatorName</em>.</p>
<p>For example, your template may have the following:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This is the validate event handler from the loginForm component. It is invoked once all the components have had a chance to read values out of the request, do their own validations, and update the properties they are bound to.</p><p>In this case, the authenticator is used to decide if the userName and password is valid. In a real application, this would be where a database or other external service was consulted.</p><p>If the combination is not valid, then the password field is marked as in error. The form is used to record an error, about a component (the passwordField) with an error message.</p><p>Entering any two values into the form and submitting will cause a round trip; the form will re-render to present the error to the user:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border image-center" width="500" src="for
ms-and-validation.data/newapp_com_example.png" data-image-src="https://cwiki.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2"></span></p><p>Notice that the cursor is placed directly into the password field.</p><div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>In versions of Tapestry prior to 5.4, a form with validation errors would result in a redirect response to the client; often, temporary server-side data (such as the userName field) would be lost. Starting in 5.4, submitting a form with validation errors results in the new page being rendered in the same request as the form submission.</p></div></div><h2 id="FormsandValidation-CustomizingValidationMessages">Customizing Validation Messages</h2><p>Each validator (such as "req
uired" or "minlength") has a default message used (on the client side and the server side) when the constraint is violated; that is, when the user input is not valid.</p><p>The message can be customized by adding an entry to the page's <a href="localization.html">message catalog</a> (or the containing component's message catalog). As with any localized property, this can also go into the application's message catalog.</p><p>The first key checked is <em>formId</em>-<em>fieldId</em>-<em>validatorName</em>-message.</p><ul><li>formId: the local component id of the Form component</li><li>fieldId: the local component id of the field (TextField, etc.)</li><li>validatorName: the name of the validator, i.e., "required" or "minlength"</li></ul><p>If there is no message for that key, a second check is made, for <em>fieldId</em>-<em>validatorName</em>-message. <span>If</span><span> that does not match a message, then the built-in default validation message is used.</span></p><p><span
>For example, if the form ID is "loginForm", the field ID is "userName", and the validator is "required" then Tapestry will first look for a "loginForm-userName-required-message" key in the message catalog, and then for a "<span>userName-required-message" key.</span></span></p><p>The validation message in the message catalog may contain <a class="external-link" href="https://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html" rel="nofollow">printf-style format strings</a> (such as %s) to indicate where the validate parameter's value will be inserted. For example, if the validate parameter in the template is minLength=3 and the validation message is "User name must be at least %s characters" then the corresponding error message would be <span>"User name must be at least 5 characters".</span></p><h3 id="FormsandValidation-CustomizingValidationMessagesforBeanEditForm">Customizing Validation Messages for BeanEditForm</h3><p>The <a href="beaneditform-guide.html">BeanE
ditForm</a> component also supports validation message customizing. The search for messages is similar; the <em>formId</em> is the component id of the BeanEditForm component (not the Form component it contains). The <em>fieldId</em> is the property name.</p><h2 id="FormsandValidation-ConfiguringValidatorContraintsintheMessageCatalog">Configuring Validator Contraints in the Message Catalog</h2><p>It is possible to omit the validation constraint from the validate parameter (or @Validator annotation), in which case it is expected to be stored in the message catalog.</p><p>This is useful when the validation constraint is awkward to enter inline, such as a regular expression for use with the regexp validator.</p><p>The key here is similar to customizing the validation message: <em>formId</em>-<em>fieldId</em>-<em>validatorName</em> or just <em>fieldId</em>-<em>validatorName</em>.</p><p>For example, your template may have the following:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: xml; gutter: false; theme: Default" data-theme="Default"> <t:textfield t:id="ssn" validate="required,regexp"/>
</pre>
</div></div><p>And your message catalog can contain:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
@@ -254,6 +254,7 @@ ssn-regexp-message=Social security numbe
<div class="aui-message aui-message-info macro-since"><b class="param-since">Added in 5.2</b>
+ <div class="param-body"><br clear="none"></div>
</div><p>Lists of validators can be combined into <em>validation macros</em>. This mechanism is convenient for ensuring consistent validation rules across an application. To create a validation macro, just contribute to the ValidatorMacro Service in your module class (normally AppModule.java), by adding a new entry to the configuration object, as shown below. The first parameter is the name of your macro, the second is a comma-separated list of validators:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>AppModule.java (partial)</b></div><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default">@Contribute(ValidatorMacro.class)
Modified: websites/production/tapestry/content/getting-started.html
==============================================================================
--- websites/production/tapestry/content/getting-started.html (original)
+++ websites/production/tapestry/content/getting-started.html Sat Jan 11 14:19:50 2020
@@ -219,7 +219,7 @@ Application 'app' (version 1.0-SNAPSHOT-
[INFO] Started SelectChannelConnector@0.0.0.0:8080
[INFO] Started Jetty Server</pre>
-</div></div><p><br clear="none"></p><p>After some more one-time downloads you can open your browser to <a class="external-link" href="http://localhost:8080/newapp" rel="nofollow">http://localhost:8080/newapp</a> to see the application running:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border image-center" height="488" width="500" src="https://cwiki-test.apache.org/confluence/download/attachments/23334911/newapp_Index.png?version=1&modificationDate=1428074330000&api=v2" data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/23334911/newapp_Index.png?version=1&modificationDate=1428074330000&api=v2"></span></p><p>The application consists of three pages sharing a common look and feel. The initial page, Index, allows you to perform some basic operations.</p><p>You can also load the newly-created
project it into any IDE and start coding. See the next section on where to find the different components of the application.</p><h2 id="GettingStarted-Exploringthegeneratedproject">Exploring the generated project</h2><p>The archetype creates the following files:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+</div></div><p><br clear="none"></p><p>After some more one-time downloads you can open your browser to <a class="external-link" href="http://localhost:8080/newapp" rel="nofollow">http://localhost:8080/newapp</a> to see the application running:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border image-center" height="488" width="500" src="getting-started.data/newapp_Index.png" data-image-src="https://cwiki.apache.org/confluence/download/attachments/23334911/newapp_Index.png?version=1&modificationDate=1428074330000&api=v2"></span></p><p>The application consists of three pages sharing a common look and feel. The initial page, Index, allows you to perform some basic operations.</p><p>You can also load the newly-created project it into any IDE and start coding. See the next section on where to find the different components of th
e application.</p><h2 id="GettingStarted-Exploringthegeneratedproject">Exploring the generated project</h2><p>The archetype creates the following files:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>newapp/
├── build.gradle
├── gradle
Modified: websites/production/tapestry/content/project-layout.html
==============================================================================
--- websites/production/tapestry/content/project-layout.html (original)
+++ websites/production/tapestry/content/project-layout.html Sat Jan 11 14:19:50 2020
@@ -67,7 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h1 id="ProjectLayout-ProjectLayout">Project Layout</h1><p>This is the <em>suggested</em> layout for your Tapestry project; it is the layout of folders and files created by the <a href="getting-started.html">Tapestry Quickstart Archetype</a>. If you are creating your own build using Ant, you may use whatever conventions work for you ... as long as everything gets packaged up into the right place in the target WAR.</p><p>Parts of this project layout mimics the format of an <em>exploded WAR</em> (a WAR file unpackaged onto the file system). This will often enable you to run your application directly from your workspace, without any special build or packaging process, while developing. Each of the major IDEs has plugins to allow you to accomplish this task ... and it's one of the factors (combined with <a href="class-reloading.html">live class reloading</a>) that makes working with Tapestry a breeze.</p><p>Below is a sample project, whose r
oot package is <code>com.example.myapp</code>:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="project-layout.data/projectlayout.png"></span></p><h2 id="ProjectLayout-Mainsourcefiles-src/main/java">Main source files - src/main/java</h2><p>Main Java source files, the files that will be compiled into the WAR file, are in <code>src/main/java</code>. This is <em>only</em> Java source files. You can see the <code>Index.java</code> source file inside the <code>pages</code> subpackage, and the <code>Layout.java</code> source file inside the <code>components</code> subpackage. The package names demonstrated here are required, dictated by the rules for <a href="component-classes.html">component classes</a></p><p>.</p><p>Compiled Java classes will ultimately be packaged in the WAR inside the <code>WEB-INF/classes</code> folder.</p><h2 id="ProjectLayout-ClasspathResources-src/main/resources">Classpath Resources - src/main/resources</h2><p>Resou
rce files are under <code>src/main/resources</code>. This includes the <a href="localization.html">message catalog</a> for the Index page (<code>Index.properties</code>), as well as the message catalog and <a href="component-templates.html">component template</a> for the Layout component (<code>Layout.tml</code>). These files will also be packaged into the <code>WEB-INF/classes</code> folder of the WAR.</p><p>Component templates will always be stored in the resources folder. Templates for pages may be packaged in the WAR proper instead.</p><h2 id="ProjectLayout-ContextResources-src/main/webapp">Context Resources - src/main/webapp</h2><p>The WAR is built primarily from the <code>src/main/webapp</code> folder; this is where ordinary files are stored (such as images and stylesheets). Page templates may also be stored here (<code>Index.tml</code>). The file <code>src/main/webapp/WEB-INF/web.xml</code> is the servlet container deployment descriptor, which has a very specific <a href="
configuration.html">configuration</a> for Tapestry.</p><p>The build tool (usually Maven) will be responsible for putting compiled classes and resources into the <code>WEB-INF/classes</code> folder of the WAR, and for putting the Tapestry library, and its dependencies (as well as any additional libraries defined by your application) into the <code>WEB-INF/lib</code> folder.</p><h2 id="ProjectLayout-Testing-src/test">Testing - src/test</h2><p>The folders <code>src/test/java</code> and <code>src/test/resources</code> are used when compiling and executing tests. Files in these folders are <em>not</em> packaged into the final WAR.</p><p> </p><p></p></div>
+ <div id="ConfluenceContent"><h1 id="ProjectLayout-ProjectLayout">Project Layout</h1><p>This is the <em>suggested</em> layout for your Tapestry project; it is the layout of folders and files created by the <a href="getting-started.html">Tapestry Quickstart Archetype</a>. If you are creating your own build using Ant, you may use whatever conventions work for you ... as long as everything gets packaged up into the right place in the target WAR.</p><p>Parts of this project layout mimics the format of an <em>exploded WAR</em> (a WAR file unpackaged onto the file system). This will often enable you to run your application directly from your workspace, without any special build or packaging process, while developing. Each of the major IDEs has plugins to allow you to accomplish this task ... and it's one of the factors (combined with <a href="class-reloading.html">live class reloading</a>) that makes working with Tapestry a breeze.</p><p>Below is a sample project, whose r
oot package is <code>com.example.myapp</code>:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="project-layout.data/projectlayout.png"></span></p><h2 id="ProjectLayout-Mainsourcefiles-src/main/java">Main source files - src/main/java</h2><p>Main Java source files, the files that will be compiled into the WAR file, are in <code>src/main/java</code>. This is <em>only</em> Java source files. You can see the <code>Index.java</code> source file inside the <code>pages</code> subpackage, and the <code>Layout.java</code> source file inside the <code>components</code> subpackage. The package names demonstrated here are required, dictated by the rules for <a href="component-classes.html">component classes</a>.</p><p>Compiled Java classes will ultimately be packaged in the WAR inside the <code>WEB-INF/classes</code> folder.</p><h2 id="ProjectLayout-ClasspathResources-src/main/resources">Classpath Resources - src/main/resources</h2><p>Resource fil
es are under <code>src/main/resources</code>. This includes the <a href="localization.html">message catalog</a> for the Index page (<code>Index.properties</code>), as well as the message catalog and <a href="component-templates.html">component template</a> for the Layout component (<code>Layout.tml</code>). These files will also be packaged into the <code>WEB-INF/classes</code> folder of the WAR.</p><p>Component templates will always be stored in the resources folder. Templates for pages may be packaged in the WAR proper instead.</p><h2 id="ProjectLayout-ContextResources-src/main/webapp">Context Resources - src/main/webapp</h2><p>The WAR is built primarily from the <code>src/main/webapp</code> folder; this is where ordinary files are stored (such as images and stylesheets). Page templates may also be stored here (<code>Index.tml</code>). The file <code>src/main/webapp/WEB-INF/web.xml</code> is the servlet container deployment descriptor, which has a very specific <a href="configu
ration.html">configuration</a> for Tapestry.</p><p>The build tool (usually Maven) will be responsible for putting compiled classes and resources into the <code>WEB-INF/classes</code> folder of the WAR, and for putting the Tapestry library, and its dependencies (as well as any additional libraries defined by your application) into the <code>WEB-INF/lib</code> folder.</p><h2 id="ProjectLayout-Testing-src/test">Testing - src/test</h2><p>The folders <code>src/test/java</code> and <code>src/test/resources</code> are used when compiling and executing tests. Files in these folders are <em>not</em> packaged into the final WAR.</p><p><br clear="none"></p><p></p></div>
</div>
<div class="clearer"></div>