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 2014/01/18 19:21:06 UTC
svn commit: r894647 [5/9] - in /websites/production/tapestry/content: ./
cache/
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 18 18:21:05 2014
@@ -29,6 +29,7 @@
<link href='http://cxf.apache.org/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
<script src='http://cxf.apache.org/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
<script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
<script type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -99,22 +100,12 @@
</div>
</li></ul>
-</div>
-
-<p>The life's blood of any application is form input; this is the most effective way 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>
-
-<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>
+</div><p>The life's blood of any application is form input; this is the most effective way 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><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.rbtoc1390069255484 {padding: 0px;}
+div.rbtoc1390069255484 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1390069255484 li {margin-left: 0px;padding-left: 0px;}
-<style type="text/css">/*<![CDATA[*/
-div.rbtoc1387423369964 {padding: 0px;}
-div.rbtoc1387423369964 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1387423369964 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style><div class="toc-macro rbtoc1387423369964">
+/*]]>*/</style></p><div class="toc-macro rbtoc1390069255484">
<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-ErrorsandDecorations">Errors and Decorations</a></li></ul>
@@ -122,51 +113,8 @@ div.rbtoc1387423369964 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect" href="#FormsandValidation-AvailableValidators">Available Validators</a></li><li><a shape="rect" href="#FormsandValidation-CentralizingValidationwith@Validate">Centralizing Validation with @Validate</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>
-
-<p>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>
-
-<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-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 </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 co
lspan="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 a
nd validated </p></td><td colspan="1" rowspan="1" class="confluenceTd"><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="confluenceTd"><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>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, unassociated with any particular field.</p>
-
-<h2 id="FormsandValidation-StoringDataBetweenRequests">Storing Data Between Requests</h2>
-
-<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 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><p>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><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-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</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="confl
uenceTd"><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" cl
ass="confluenceTd"><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="con
fluenceTd"><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>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, unassociated with any particular field.</p><h2 id="FormsandValidation-StoringDataBetweenRequests">Storing Data Between Requests</h2><div class="navmenu" style="float:right; width:40%; background:white; margin:3px; padding:3px">
<div class="aui-message hint shadowed information-macro">
<p class="title">New in Tapestry 5.4</p>
<span class="aui-icon icon-hint">Icon</span>
@@ -175,17 +123,8 @@ div.rbtoc1387423369964 li {margin-left:
<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 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>
-
-<p>However, for the same reason, the individual fields updated 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, 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">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class Login
+</div><p>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><p>However, for the same reason, the individual fields updated 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, 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">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class Login
{
@Persist
@Property
@@ -224,9 +163,7 @@ public class Login
}
}
]]></script>
-</div></div>
-
-<div class="navmenu" style="float:right; width:40%; background:white; margin:3px; padding:3px">
+</div></div><div class="navmenu" style="float:right; width:40%; background:white; margin:3px; padding:3px">
<div class="aui-message hint shadowed information-macro">
<span class="aui-icon icon-hint">Icon</span>
<div class="message-content">
@@ -234,30 +171,14 @@ public class Login
<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 shape="rect" 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>
-
- <div class="aui-message success shadowed information-macro">
+</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 shape="rect" 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> <div class="aui-message success shadowed information-macro">
<span class="aui-icon icon-success">Icon</span>
<div class="message-content">
-
-<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>
+ <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 errors to the user.</p>
-
-<h2 id="FormsandValidation-ConfiguringFieldsandLabels">Configuring Fields and Labels</h2>
-
-<p>The template for the Login page contains a minimal amount of Tapestry instrumentation:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: html; gutter: false" type="syntaxhighlighter"><![CDATA[
-<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">
+<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 errors to the user.</p><h2 id="FormsandValidation-ConfiguringFieldsandLabels">Configuring Fields and Labels</h2><p>The template for the Login page contains a minimal amount of Tapestry instrumentation:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">
<head>
<title>Login</title>
</head>
@@ -279,117 +200,14 @@ public class Login
</body>
</html>
]]></script>
-</div></div>
-
-<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>The <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Errors.html">Errors</a> component must be placed inside a Form, it outputs all of the errors for all the fields within the Form as a single list. It uses some simple styling to make the result more presentable.</p>
-
-<p>Each field component, such as the TextField, is paired with a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Label.html">Label</a> component. The Label will render out a <label> element connected to the field. This is very important for usability, especially for users with visual disabilities. It also means you can click on the label text to move the cursor to the corresponding field.</p>
-
-<p>The <code>for</code> parameter of the Label is the id of a component.</p>
-
-<p>For the TextField, we provide a component id, userName. We could specify the <code>value</code> 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.</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 <code>validate</code> parameter identifies what validations should occur for the field. This is a list of validator names. Validators are configured within Tapestry, and the list of available validators is extensible. "required" is a name of one of the built-in validators, that ensures that the submitted value is not the empty string. Likewise, "minlen" ensures that the value has the specified minimum length.</p>
-
-<p>The <code>validate</code> parameter was placed within the Tapestry namespace using the <code>t:</code> prefix. This is not strictly necessary, as the template is <em>well formed</em> either way. However, putting the Tapestry specific values into the Tapestry namespace ensures that the template will itself be <em>valid</em>.</p>
-
-<h2 id="FormsandValidation-ErrorsandDecorations">Errors and Decorations</h2>
-
-<p><strong>Note: This section has not been updated to reflect the introduction of client-side input validation.</strong></p>
-
-<p>When you first activate the Login page, the fields and forms will render normally, awaiting input:</p>
-
-
-<p><img class="confluence-embedded-image" src="https://cwiki.apache.org/confluence/download/attachments/22872109/validation_initial.png?version=1&modificationDate=1276677599000&api=v2" data-image-src="/confluence/download/attachments/22872109/validation_initial.png?version=1&modificationDate=1276677599000&api=v2" title="Initial form presentation"></p>
-
-<p>Notice how the Label components are displaying the textual names for the fields. Given that we have not done any explicit configuration, what's happened is that the component's ids ("userName" and "password") have been converted to "User Name" and "Password".</p>
-
-<p>If you just submit the form as is, the fields will violate the "required" constraint and the page will be redisplayed to present those errors to the user:</p>
-
-<p><img class="confluence-embedded-image" src="https://cwiki.apache.org/confluence/download/attachments/22872109/validation_errors.png?version=1&modificationDate=1276677599000&api=v2" data-image-src="/confluence/download/attachments/22872109/validation_errors.png?version=1&modificationDate=1276677599000&api=v2" title="Errors and decorations"></p>
-
-<p>There's a couple of subtle things going on here. First, Tapestry tracks <em>all</em> the errors for <em>all</em> the fields. The Errors component has displayed them at the top of the form. Further, the <em>default validation decorator</em> has added decorations to the labels and the fields, adding "t-error" to the CSS class for the fields and labels. Tapestry provides a default CSS stylesheet that combines with the "t-error" class to make things turn red.</p>
-
-<p>Next, we'll fill in the user name but not provide enough characters for password.</p>
-
-
-<p><img class="confluence-embedded-image" src="https://cwiki.apache.org/confluence/download/attachments/22872109/validation_minlength.png?version=1&modificationDate=1276677600000&api=v2" data-image-src="/confluence/download/attachments/22872109/validation_minlength.png?version=1&modificationDate=1276677600000&api=v2" title="Minlength error message"></p>
-
-<p>The user name field is OK, but there's an error on just the password field. The PasswordField component always displays a blank value by default, otherwise we'd see the partial password displayed inside.</p>
-
-<p>If you type in enough characters and submit, we see how the logic inside the Login page can attach errors to fields:</p>
-
-<p><img class="confluence-embedded-image" src="https://cwiki.apache.org/confluence/download/attachments/22872109/validation_password.png?version=1&modificationDate=1276677600000&api=v2" data-image-src="/confluence/download/attachments/22872109/validation_password.png?version=1&modificationDate=1276677600000&api=v2" title="Application supplied errors"></p>
-
-<p>This is nice and seamless; the same look and feel and behavior for both the built-in validators, and for errors generated based on application logic.</p>
-
-<h1 id="FormsandValidation-FormValidation">Form Validation</h1>
-
-<h2 id="FormsandValidation-AvailableValidators">Available Validators</h2>
-
-<p>Tapestry provides the following built-in validators:</p>
-
-<div class="table-wrap"><table class="confluenceTable"><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="email" validate="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" r
owspan="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></tbody></table></div>
-
-
-<h2 id="FormsandValidation-CentralizingValidationwith@Validate">Centralizing Validation with @Validate</h2>
-
-<p>The @<a shape="rect" 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, 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>
-
-<h2 id="FormsandValidation-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 shape="rect" 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"<br clear="none">
-If there is not message for that key, a second check is made, for <em>fieldId</em>-<em>validatorName</em>-message.</li></ul>
-
-
-<p>If that does not match a message, then the built-in default validation message is used.</p>
-
-<h3 id="FormsandValidation-CustomizingValidationMessagesforBeanEditForm">Customizing Validation Messages for BeanEditForm</h3>
-
-<p>The <a shape="rect" 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">
-<script class="theme: Default; brush: html; gutter: false" type="syntaxhighlighter"><![CDATA[
- <t:textfield t:id="ssn" validate="required,regexp"/>
+</div></div><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>The <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Errors.html">Errors</a> component must be placed inside a Form, it outputs all of the errors for all the fields within the Form as a single list. It uses some simple styling to make the result more presentable.</p><p>Each field component, such as the TextField, is paired with a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Label.html">Label</a> component. The Label will render out a <label> element connected to the field. This is very important for usability, especially for users with visual disabilities. It also means you can click on the label text to move the cursor to the corresponding field.</p><p>Th
e <code>for</code> parameter of the Label is the id of a component.</p><p>For the TextField, we provide a component id, userName. We could specify the <code>value</code> 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.</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 <code>validate</code> parameter identifies what validations should occur for the field. This is a list of validator names. Validators are configured within Tapestry, and the list of available validators is extensible. "required" is a name of one of the built-in validators, that ensures that the submitted value is not the empty string. Likewise, "minlen" ensures that the value has the specified m
inimum length.</p><p>The <code>validate</code> parameter was placed within the Tapestry namespace using the <code>t:</code> prefix. This is not strictly necessary, as the template is <em>well formed</em> either way. However, putting the Tapestry specific values into the Tapestry namespace ensures that the template will itself be <em>valid</em>.</p><h2 id="FormsandValidation-ErrorsandDecorations">Errors and Decorations</h2><p><strong>Note: This section has not been updated to reflect the introduction of client-side input validation.</strong></p><p>When you first activate the Login page, the fields and forms will render normally, awaiting input:</p><p><img class="confluence-embedded-image" src="https://cwiki.apache.org/confluence/download/attachments/22872109/validation_initial.png?version=1&modificationDate=1276677599000&api=v2" data-image-src="/confluence/download/attachments/22872109/validation_initial.png?version=1&modificationDate=1276677599000&api=v2" title="Init
ial form presentation"></p><p>Notice how the Label components are displaying the textual names for the fields. Given that we have not done any explicit configuration, what's happened is that the component's ids ("userName" and "password") have been converted to "User Name" and "Password".</p><p>If you just submit the form as is, the fields will violate the "required" constraint and the page will be redisplayed to present those errors to the user:</p><p><img class="confluence-embedded-image" src="https://cwiki.apache.org/confluence/download/attachments/22872109/validation_errors.png?version=1&modificationDate=1276677599000&api=v2" data-image-src="/confluence/download/attachments/22872109/validation_errors.png?version=1&modificationDate=1276677599000&api=v2" title="Errors and decorations"></p><p>There's a couple of subtle things going on here. First, Tapestry tracks <em>all</em> the errors for <em>all</em> the fields. The Errors component has displayed them at the top
of the form. Further, the <em>default validation decorator</em> has added decorations to the labels and the fields, adding "t-error" to the CSS class for the fields and labels. Tapestry provides a default CSS stylesheet that combines with the "t-error" class to make things turn red.</p><p>Next, we'll fill in the user name but not provide enough characters for password.</p><p><img class="confluence-embedded-image" src="https://cwiki.apache.org/confluence/download/attachments/22872109/validation_minlength.png?version=1&modificationDate=1276677600000&api=v2" data-image-src="/confluence/download/attachments/22872109/validation_minlength.png?version=1&modificationDate=1276677600000&api=v2" title="Minlength error message"></p><p>The user name field is OK, but there's an error on just the password field. The PasswordField component always displays a blank value by default, otherwise we'd see the partial password displayed inside.</p><p>If you type in enough characters and s
ubmit, we see how the logic inside the Login page can attach errors to fields:</p><p><img class="confluence-embedded-image" src="https://cwiki.apache.org/confluence/download/attachments/22872109/validation_password.png?version=1&modificationDate=1276677600000&api=v2" data-image-src="/confluence/download/attachments/22872109/validation_password.png?version=1&modificationDate=1276677600000&api=v2" title="Application supplied errors"></p><p>This is nice and seamless; the same look and feel and behavior for both the built-in validators, and for errors generated based on application logic.</p><h1 id="FormsandValidation-FormValidation">Form Validation</h1><h2 id="FormsandValidation-AvailableValidators">Available Validators</h2><p>Tapestry provides the following built-in validators:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Validator</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Con
straint 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="email" validate="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><t
d 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 v
alue="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></tbody></table></div><h2 id="FormsandValidation-CentralizingValidationwith@Validate">Centralizing Validation with @Validate</h2><p>The @<a shape="rect" 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, 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><h2 id="FormsandValidation-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 shape="rect" 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"<br clear="none"> If there is not message for that key, a second check is made, for <em>fieldId</em>-<em>validatorName</em>-message.</li></ul><p>If that does not match a message, then the built-in default v
alidation message is used.</p><h3 id="FormsandValidation-CustomizingValidationMessagesforBeanEditForm">Customizing Validation Messages for BeanEditForm</h3><p>The <a shape="rect" 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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <t:textfield t:id="ssn" validate="required,regexp"/>
]]></script>
-</div></div>
-
-<p>And your message catalog can contain:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-ssn-regexp=\d{3}-\d{2}-\d{4}
+</div></div><p>And your message catalog can contain:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ssn-regexp=\d{3}-\d{2}-\d{4}
ssn-regexp-message=Social security numbers are in the format 12-34-5678.
]]></script>
-</div></div>
-
-<p>This technique also works with the BeanEditForm; as with validation messages, the formId is the BeanEditForm component's id, and the fieldId is the name of the property being editted.</p>
-
-<h2 id="FormsandValidation-ValidationMacros">Validation Macros</h2>
-
-
+</div></div><p>This technique also works with the BeanEditForm; as with validation messages, the formId is the BeanEditForm component's id, and the fieldId is the name of the property being editted.</p><h2 id="FormsandValidation-ValidationMacros">Validation Macros</h2>
<div class="aui-message hint shadowed information-macro">
<p class="title">Added in 5.2</p>
@@ -401,49 +219,21 @@ ssn-regexp-message=Social security numbe
</div>
<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid #D8E4F1;">
-</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="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Contribute(ValidatorMacro.class)
+<p> </p></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="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Contribute(ValidatorMacro.class)
public static void combinePasswordValidators(MappedConfiguration<String, String> configuration) {
configuration.add("password","required,minlength=5,maxlength=15,");
}
]]></script>
-</div></div>
-
-<p>Then, you can use this new macro in component templates and classes:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: html; gutter: false" type="syntaxhighlighter"><![CDATA[
-<input t:type="textField" t:id="password" t:validate="password" />
+</div></div><p>Then, you can use this new macro in component templates and classes:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<input t:type="textField" t:id="password" t:validate="password" />
]]></script>
-</div></div>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Validate("password")
+</div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Validate("password")
private String password;
]]></script>
-</div></div>
-
-<h2 id="FormsandValidation-OverridingtheTranslatorwithEvents">Overriding the Translator with Events</h2>
-
-<p>The TextField, PasswordField and TextArea components all have a translate parameter, a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/FieldTranslator.html">FieldTranslator</a> object that is used to convert values on the server side to strings on the client side.</p>
-
-<p>In most cases, the translate parameter is not set explicitly; Tapestry derives an appropriate value based on the type of property being editted by the field.</p>
-
-<p>In certain cases, you may want to override the translator. This can be accomplished using two events triggered on the component, "toclient" and "parseclient".</p>
-
-<p>The "toclient" event is passed the current object value and returns a string, which will be the default value for the field. When there is no event handler, or when the event handler returns null, the default Translator is used to convert the server side value to a string.</p>
-
-<p>For example, you may have a quantity field that you wish to display as blank, rather than zero, initially:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- <t:textfield t:id="quantity" size="10"/>
+</div></div><h2 id="FormsandValidation-OverridingtheTranslatorwithEvents">Overriding the Translator with Events</h2><p>The TextField, PasswordField and TextArea components all have a translate parameter, a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/FieldTranslator.html">FieldTranslator</a> object that is used to convert values on the server side to strings on the client side.</p><p>In most cases, the translate parameter is not set explicitly; Tapestry derives an appropriate value based on the type of property being editted by the field.</p><p>In certain cases, you may want to override the translator. This can be accomplished using two events triggered on the component, "toclient" and "parseclient".</p><p>The "toclient" event is passed the current object value and returns a string, which will be the default value for the field. When there is no event handler, or when the event handler returns null, the default Translato
r is used to convert the server side value to a string.</p><p>For example, you may have a quantity field that you wish to display as blank, rather than zero, initially:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ <t:textfield t:id="quantity" size="10"/>
. . .
@@ -456,45 +246,21 @@ private String password;
return null;
}
]]></script>
-</div></div>
-
-<p>This is good so far, but if the field is optional and the user submits the form, you'll get a validation error, because the empty string is not valid as an integer.</p>
-
-<p>That's where the "parseclient" event comes in:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- Object onParseClientFromQuantity(String input)
+</div></div><p>This is good so far, but if the field is optional and the user submits the form, you'll get a validation error, because the empty string is not valid as an integer.</p><p>That's where the "parseclient" event comes in:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ Object onParseClientFromQuantity(String input)
{
if ("".equals(input)) return 0;
return null;
}
]]></script>
-</div></div>
-
-<p>The event handler method has precedence over the translator. Here it checks for the empty string (and note that the input may be null!) and evaluates that as zero.</p>
-
-<p>Again, returning null lets the normal translator do its work.</p>
-
-<p>The event handler may also throw a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValidationException.html">ValidationException</a> to indicate a value that can't be parsed.</p>
-
-<p>Now, what if you want to perform your own custom validation? That's another event: "validate":</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- void onValidateFromCount(Integer value) throws ValidationException
+</div></div><p>The event handler method has precedence over the translator. Here it checks for the empty string (and note that the input may be null!) and evaluates that as zero.</p><p>Again, returning null lets the normal translator do its work.</p><p>The event handler may also throw a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValidationException.html">ValidationException</a> to indicate a value that can't be parsed.</p><p>Now, what if you want to perform your own custom validation? That's another event: "validate":</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ void onValidateFromCount(Integer value) throws ValidationException
{
if (value.equals(13)) throw new ValidationException("Thirteen is an unlucky number.");
}
]]></script>
-</div></div>
-
-<p>This event gets fired <strong>after</strong> the normal validators. It is passed the <em>parsed</em> value (not the string from the client, but the object value from the translator, or from the "parseclient" event handler).</p>
-
-<p>The method may not return a value, but may throw a ValidationException to indicate a problem with the value.</p>
-
-<p><strong>Caution:</strong> These events are exclusively on the <em>server side</em>. This means that, in certain circumstances, an input value will be rejected on the client side even though it is valid on the server side. You may need to disable client-side validation in order to use this feature.</p></div>
+</div></div><p>This event gets fired <strong>after</strong> the normal validators. It is passed the <em>parsed</em> value (not the string from the client, but the object value from the translator, or from the "parseclient" event handler).</p><p>The method may not return a value, but may throw a ValidationException to indicate a problem with the value.</p><p><strong>Caution:</strong> These events are exclusively on the <em>server side</em>. This means that, in certain circumstances, an input value will be rejected on the client side even though it is valid on the server side. You may need to disable client-side validation in order to use this feature.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/https.html
==============================================================================
--- websites/production/tapestry/content/https.html (original)
+++ websites/production/tapestry/content/https.html Sat Jan 18 18:21:05 2014
@@ -69,81 +69,27 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><h1 id="HTTPS-SecuringyourapplicationwithHTTPS">Securing your application with HTTPS</h1>
-
-<p>Tapestry assumes your application will be primarily deployed as a standard web application, using HTTP (not HTTPS) as the transport mechanism.</p>
-
-<p>However, many applications will need to have some of their pages secured: only accessible via HTTPS. This could be a login page, or a product ordering wizard, or administrative pages.</p>
-
-<p>All that is necessary to mark a page as secure is to add the @Secure annotation to the page class:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Secure
+<div id="ConfluenceContent"><h1 id="HTTPS-SecuringyourapplicationwithHTTPS">Securing your application with HTTPS</h1><p>Tapestry assumes your application will be primarily deployed as a standard web application, using HTTP (not HTTPS) as the transport mechanism.</p><p>However, many applications will need to have some of their pages secured: only accessible via HTTPS. This could be a login page, or a product ordering wizard, or administrative pages.</p><p>All that is necessary to mark a page as secure is to add the @Secure annotation to the page class:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Secure
public class ProcessOrder
{
. . .
}
]]></script>
-</div></div>
-
-<p>When a page is marked as secure, Tapestry will ensure that access to that page uses HTTPS. All links to the page will use the "https" protocol.</p>
-
-<p>If an attempt is made to access a secure page using a non-secure request (a normal HTTP request), Tapestry will send an HTTPS redirect to the client.</p>
-
-<p>Links to non-secure pages from a secure page will do the reverse: a complete URL with an "http" protocol will be used. In other words, Tapestry manages the transition from insecure to secure and back again.</p>
-
-<p>Links to other (secure) pages <em>and to assets</em> will be based on relative URLs and, therefore, secure.</p>
-
-<p>The rationale behind using secure links to assets from secure pages is that it prevents the client web browser from reporting a mixed security level.</p>
-
-<h2 id="HTTPS-SecuringMultiplePages">Securing Multiple Pages</h2>
-
-<p>Rather than placing an @Secure annotation on individual pages, it is possible to enable security for folders of pages. All pages in or beneath the folder will be secured.</p>
-
-<p>This is accomplished by making a contribution to the MetaDataLocator service configuration. For example, to secure all pages in the "admin" folder:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public void contributeMetaDataLocator(MappedConfiguration<String,String> configuration)
+</div></div><p>When a page is marked as secure, Tapestry will ensure that access to that page uses HTTPS. All links to the page will use the "https" protocol.</p><p>If an attempt is made to access a secure page using a non-secure request (a normal HTTP request), Tapestry will send an HTTPS redirect to the client.</p><p>Links to non-secure pages from a secure page will do the reverse: a complete URL with an "http" protocol will be used. In other words, Tapestry manages the transition from insecure to secure and back again.</p><p>Links to other (secure) pages <em>and to assets</em> will be based on relative URLs and, therefore, secure.</p><p>The rationale behind using secure links to assets from secure pages is that it prevents the client web browser from reporting a mixed security level.</p><h2 id="HTTPS-SecuringMultiplePages">Securing Multiple Pages</h2><p>Rather than placing an @Secure annotation on individual pages, it is possible to enable security for folders of pages. All pages
in or beneath the folder will be secured.</p><p>This is accomplished by making a contribution to the MetaDataLocator service configuration. For example, to secure all pages in the "admin" folder:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public void contributeMetaDataLocator(MappedConfiguration<String,String> configuration)
{
configuration.add("admin:" + MetaDataConstants.SECURE_PAGE, "true");
}
]]></script>
-</div></div>
-
-<p>Here "admin" is the folder name, and the colon is a separator between the folder name and the the meta data key. SECURE_PAGE is a public constant for value "tapestry.secure-page";</p>
-
-<p>When Tapestry is determining if a page is secure or not, it starts by checking for the @Secure annotation, then it consults the MetaDataLocator service.</p>
-
-<p>If you want to make your entire application secure:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public void contributeMetaDataLocator(MappedConfiguration<String,String> configuration)
+</div></div><p>Here "admin" is the folder name, and the colon is a separator between the folder name and the the meta data key. SECURE_PAGE is a public constant for value "tapestry.secure-page";</p><p>When Tapestry is determining if a page is secure or not, it starts by checking for the @Secure annotation, then it consults the MetaDataLocator service.</p><p>If you want to make your entire application secure:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public void contributeMetaDataLocator(MappedConfiguration<String,String> configuration)
{
configuration.add(MetaDataConstants.SECURE_PAGE, "true");
}
]]></script>
-</div></div>
-
-<p>With no colon, the meta data applies to the entire application (including any component libraries used in the application).</p>
-
-<h2 id="HTTPS-BaseURLSupport">Base URL Support</h2>
-
-<p>When Tapestry switches back and forth between secure and unsecure mode, it must create a full URL (rather than a relative URL) that identifies the protocol, server host name and perhaps even a port number.</p>
-
-<p>That can be a stumbling point, especially the server host name. In a cluster, behind a fire wall, the server host name available to Tapestry, via the <code>HttpServletRequest.getServerName()</code> method, is often <em>not</em> the server name the client web browser sees ... instead it is the name of the internal server behind the firewall. The firewall server has the correct name from the web browser's point of view.</p>
-
-<p>Because of this, Tapestry includes a hook to allow you to override how these default URLs are created: the BaseURLSource service.</p>
-
-<p>The default implementation is based on just the getServerName() method; it's often not the correct choice even for development.</p>
-
-<p>Fortunately, it is very easy to override this implementation. Here's an example of an override that uses the default port numbers that the <a shape="rect" class="external-link" href="http://jetty.codehaus.org/jetty/" >Jetty servlet container</a> uses for normal HTTP (port 8080) and for secure HTTPS (port 8443):</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- public static void contributeServiceOverride(MappedConfiguration<Class,Object> configuration)
+</div></div><p>With no colon, the meta data applies to the entire application (including any component libraries used in the application).</p><h2 id="HTTPS-BaseURLSupport">Base URL Support</h2><p>When Tapestry switches back and forth between secure and unsecure mode, it must create a full URL (rather than a relative URL) that identifies the protocol, server host name and perhaps even a port number.</p><p>That can be a stumbling point, especially the server host name. In a cluster, behind a fire wall, the server host name available to Tapestry, via the <code>HttpServletRequest.getServerName()</code> method, is often <em>not</em> the server name the client web browser sees ... instead it is the name of the internal server behind the firewall. The firewall server has the correct name from the web browser's point of view.</p><p>Because of this, Tapestry includes a hook to allow you to override how these default URLs are created: the BaseURLSource service.</p><p>The default implementatio
n is based on just the getServerName() method; it's often not the correct choice even for development.</p><p>Fortunately, it is very easy to override this implementation. Here's an example of an override that uses the default port numbers that the <a shape="rect" class="external-link" href="http://jetty.codehaus.org/jetty/" >Jetty servlet container</a> uses for normal HTTP (port 8080) and for secure HTTPS (port 8443):</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ public static void contributeServiceOverride(MappedConfiguration<Class,Object> configuration)
{
BaseURLSource source = new BaseURLSource()
{
@@ -160,23 +106,7 @@ public void contributeMetaDataLocator(Ma
configuration.add(BaseURLSource.class, source);
}
]]></script>
-</div></div>
-
-<p>This override is hardcoded to generate URLs for localhost; as such you might use it for development but certainly not in production.</p>
-
-<h2 id="HTTPS-DevelopmentMode">Development Mode</h2>
-
-<p>When working in development mode, the Secure annotation is ignored. This is controlled by the tapestry.secure-enabled <a shape="rect" href="configuration.html#Configuration-Configuration-ConfigurationSymbols">configuration symbol</a>.</p>
-
-<h2 id="HTTPS-ApplicationServerConfiguration">Application Server Configuration</h2>
-
-<p>Setting up HTTPS support varies from application server to application server.</p>
-
-<ul><li>Jetty:
- <ul><li><a shape="rect" class="external-link" href="http://docs.codehaus.org/display/JETTY/How+to+configure+SSL" >Jetty 6</a></li></ul>
- </li><li>Tomcat:
- <ul><li><a shape="rect" class="external-link" href="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html">Version 6.0</a></li><li><a shape="rect" class="external-link" href="http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html">Version 5.5</a></li></ul>
- </li></ul></div>
+</div></div><p>This override is hardcoded to generate URLs for localhost; as such you might use it for development but certainly not in production.</p><h2 id="HTTPS-DevelopmentMode">Development Mode</h2><p>When working in development mode, the Secure annotation is ignored. This is controlled by the tapestry.secure-enabled <a shape="rect" href="configuration.html#Configuration-Configuration-ConfigurationSymbols">configuration symbol</a>.</p><h2 id="HTTPS-ApplicationServerConfiguration">Application Server Configuration</h2><p>Setting up HTTPS support varies from application server to application server.</p><ul><li>Jetty:<ul><li><a shape="rect" class="external-link" href="http://docs.codehaus.org/display/JETTY/How+to+configure+SSL" >Jetty 6</a></li></ul></li><li>Tomcat:<ul><li><a shape="rect" class="external-link" href="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html">Version 6.0</a></li><li><a shape="rect" class="external-link" href="http://tomcat.apache.org/tomcat-5.5-doc/ssl-
howto.html">Version 5.5</a></li></ul></li></ul></div>
</div>
<div class="clearer"></div>