tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r946224 - in /websites/production/tapestry/content: cache/main.pageCache forms-and-validation.data/newapp_com_example.png forms-and-validation.html
Date Fri, 03 Apr 2015 19:19:50 GMT
Author: buildbot
Date: Fri Apr  3 19:19:49 2015
New Revision: 946224

Log:
Production update by buildbot for tapestry

Added:
    websites/production/tapestry/content/forms-and-validation.data/newapp_com_example.png
  (with props)
Modified:
    websites/production/tapestry/content/cache/main.pageCache
    websites/production/tapestry/content/forms-and-validation.html

Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.

Added: websites/production/tapestry/content/forms-and-validation.data/newapp_com_example.png
==============================================================================
Binary file - no diff available.

Propchange: websites/production/tapestry/content/forms-and-validation.data/newapp_com_example.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

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 Fri Apr  3 19:19:49 2015
@@ -98,16 +98,14 @@
                             </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><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1427879985369 {padding: 0px;}
-div.rbtoc1427879985369 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1427879985369 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1428088772174 {padding: 0px;}
+div.rbtoc1428088772174 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1428088772174 li {margin-left: 0px;padding-left: 0px;}
 
-/*]]>*/</style></p><div class="toc-macro rbtoc1427879985369">
+/*]]>*/</style></p><div class="toc-macro rbtoc1428088772174">
 <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>
-</li><li><a shape="rect" href="#FormsandValidation-FormValidation">Form
Validation</a>
-<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-FormEvents">Form
Events</a></li><li><a shape="rect" href="#FormsandValidation-TrackingValidationErrors">Tracking
Validation Errors</a></li><li><a shape="rect" href="#FormsandValidation-StoringDataBetweenRequests">Storing
Data Between Requests</a></li><li><a shape="rect" href="#FormsandValidation-ConfiguringFieldsandLabels">Configuring
Fields and Labels</a></li><li><a shape="rect" href="#FormsandValidation-CentralizingValidationwith@Validate">Centralizing
Validation with @Validate</a></li><li><a shape="rect" href="#FormsandValidation-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">
@@ -121,10 +119,19 @@ div.rbtoc1427879985369 li {margin-left:
                     </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 &#8211;
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
-{
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[package
com.example.newapp.pages;
+
+
+import com.example.newapp.services.UserAuthenticator;
+import org.apache.tapestry5.annotations.*;
+import org.apache.tapestry5.corelib.components.Form;
+import org.apache.tapestry5.corelib.components.PasswordField;
+import org.apache.tapestry5.ioc.annotations.Inject;
+
+
+public class Login {
     @Persist
-    @Property
+    @Property 
     private String userName;
 
     @Property
@@ -137,28 +144,27 @@ div.rbtoc1427879985369 li {margin-left:
     private PasswordField passwordField;
 
     @Component
-    private Form form;
+    private Form loginForm;
 
     /**
      * Do the cross-field validation
      */
-    void onValidateFromLoginForm()
-    {
-        if (!authenticator.isValid(userName, password))
-        {
+    void onValidateFromLoginForm() {
+        if (!authenticator.isValid(userName, password)) {
             // record an error, and thereby prevent Tapestry from emitting a &quot;success&quot;
event
-            form.recordError(passwordField, &quot;Invalid user name or password.&quot;);
+            loginForm.recordError(passwordField, &quot;Invalid user name or password.&quot;);
         }
     }
 
     /**
      * Validation passed, so we&#39;ll go to the &quot;PostLogin&quot; page
      */
-    Object onSuccess()
-    {
+    Object onSuccess() {
         return PostLogin.class;
     }
 }
+
+
 ]]></script>
 </div></div><div class="navmenu" style="float:right; width:40%; background:white;
margin:3px; padding:3px">
     <div class="aui-message hint shadowed information-macro">
@@ -174,30 +180,38 @@ div.rbtoc1427879985369 li {margin-left:
                             <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: xml; gutter: false" type="syntaxhighlighter"><![CDATA[&lt;html
xmlns:t=&quot;http://tapestry.apache.org/schema/tapestry_5_1_0.xsd&quot;&gt;
-    &lt;head&gt;
-        &lt;title&gt;Login&lt;/title&gt;
-    &lt;/head&gt;
-    &lt;body&gt;
-        &lt;h1&gt;Please Login&lt;/h1&gt;
-
-        &lt;form t:type=&quot;form&quot; t:id=&quot;loginForm&quot;&gt;
-
-            &lt;t:errors/&gt;
-
-            &lt;t:label for=&quot;userName&quot;/&gt;:
-            &lt;input t:type=&quot;TextField&quot; t:id=&quot;userName&quot;
t:validate=&quot;required,minlength=3&quot; size=&quot;30&quot;/&gt;
-            &lt;br/&gt;
-            &lt;t:label for=&quot;password&quot;/&gt;:
-            &lt;input t:type=&quot;PasswordField&quot; t:id=&quot;password&quot;
t:validate=&quot;required,minlength=3&quot; size=&quot;30&quot;/&gt;
-            &lt;br/&gt;
-            &lt;input type=&quot;submit&quot; value=&quot;Login&quot;/&gt;
-        &lt;/form&gt;
-    &lt;/body&gt;
+<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 and references some of the <a shape="rect" class="external-link"
href="http://getbootstrap.com" >Bootstrap</a> CSS classes (Bootstrap is automatically
integrated into each T
 apestry page):</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[&lt;html
t:type=&quot;layout&quot; title=&quot;newapp com.example&quot;
+      xmlns:t=&quot;http://tapestry.apache.org/schema/tapestry_5_4.xsd&quot;&gt;
+
+    &lt;div class=&quot;row&quot;&gt;
+        &lt;div class=&quot;span4 offset3&quot;&gt;
+            &lt;t:form t:id=&quot;loginForm&quot;&gt;
+                &lt;h2&gt;Please sign in&lt;/h2&gt;
+                &lt;t:textfield t:id=&quot;userName&quot; t:mixins=&quot;formgroup&quot;/&gt;
+                &lt;t:passwordfield t:id=&quot;password&quot; value=&quot;password&quot;
t:mixins=&quot;formgroup&quot;/&gt;
+                &lt;t:submit class=&quot;btn btn-large btn-primary&quot; value=&quot;Sign
in&quot;/&gt;
+            &lt;/t:form&gt;
+        &lt;/div&gt;
+    &lt;/div&gt;
+
 &lt;/html&gt;
 ]]></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 &lt;label&gt; 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, "minlength 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="forms-and-validation.data/validation_initial.png" data-image-src="/confluence/download/attachments/22872109/validation_initial.png?version=1&amp;modificationDate=1276677599000&amp;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="forms-and-validation.data/validation_errors.png"
data-image-src="/confluence/download/attachments/22872109/validation_errors.png?version=1&amp;modificationDate=1276677599000&amp;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 prov
 ides 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="forms-and-validation.data/validation_minlength.png"
data-image-src="/confluence/download/attachments/22872109/validation_minlength.png?version=1&amp;modificationDate=1276677600000&amp;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="forms-and-validation.data/validation_password.png"
data-image-src="/confluence/download/attachments/22872109/validation_password.png?version=1&amp;modificati
 onDate=1276677600000&amp;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>&#8211;</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Ensures that the given inp
 ut looks like a valid e-mail address</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>&lt;t:textfield
value="email" validate="email" /&gt;</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>&lt;t:textfield value="age"
validate="max=120,min=0" /&gt;</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>&lt;t:textfield
value="zip" validate="maxlength=7" /&gt;</code></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>min</p></td><td c
 olspan="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>&lt;t:textfield value="age"
validate="max=120,min=0" /&gt;</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>&lt;t:textfield
value="somefield" validate="minlength=1" /&gt;</code></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>none</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>&#8211;</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>&lt;t:
 textfield value="somefield" validate="none" /&gt;</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>&lt;t:textfield
value="letterfield" validate="regexp=^</code><code>[A-Za-z]+$" /&gt;</code></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>required</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>&#8211;</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>&lt;t:textfield
value="name" validate="required" /&gt;</code></p></td></tr></tbody></table></div><h2
id="FormsandValidation-CentralizingValidationwith@Validate">Centralizing Valid
 ation 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 ca
 talog). 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 com
 ponent (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>Rendering the page gives a reasonable pleasing first pass:</p><p><img
class="confluence-embedded-image confluence-content-image-border image-center" width="500"
src="forms-and-validation.data/newapp_com_example.png" data-image-src="/confluence/download/attachments/22872109/newapp_com_example.png?version=2&amp;modificationDate=1428088329843&amp;api=v2"></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 style="line-height:
1.4285715;">For the TextField, we provide a component id, userName. We could specify the
</span><code style="line-height: 1.4285715;">value</code><span style="line-height:
1.4285715;"> 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.&#160;</span></p><p>As
a rule of thumb, you should always give your fields a specific id (this id will be used to
generat
 e 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 &lt;label&gt; 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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[&lt;div
class=&quot;form-group&quot;&gt;
+  &lt;label for=&quot;userName&quot; class=&quot;control-label&quot;&gt;User
Name&lt;/label&gt;
+  &lt;input id=&quot;userName&quot; class=&quot;form-control&quot; name=&quot;userName&quot;
type=&quot;text&quot;&gt;
+&lt;/div&gt;]]></script>
+</div></div><p>&#160;</p><p><span style="color: rgb(83,145,38);font-size:
24.0px;line-height: 1.25;">Form Validation</span></p><p>So, this is a
basic (very basic!) form and you can leave the fields blank and submit the form. With very
little effort we can add client-side validation, to prevent the user from submitting the form
with either field left blank.</p><p>Validation in Tapestry involves associating
one or more&#160;<em>validators</em> with a form element component, such as
TextField or PasswordField. This can be done using the validate parameter of the component
itself.</p><p><span style="color: rgb(83,145,38);font-size: 20.0px;line-height:
1.5;">Available Validators</span></p><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>&#8211;</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>&lt;t:textfield
value="email" validate="email" /&gt;</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>&lt;t:textfield value="age"
validate="max=120,min=0" /&gt;</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>&lt;t:textfield value="zip" validate="maxlength=7"
/&gt;</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>&lt;t:textfield value="age"
validate="max=120,min=0" /&gt;</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>&lt;t:textfield
value="somefield" validate="minlength=1" /&gt;</code></
 p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>none</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>&#8211;</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>&lt;t:textfield
value="somefield" validate="none" /&gt;</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>&lt;t:textfield
value="letterfield" validate="regexp=^</code><code>[A-Za-z]+$" /&gt;</code></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>required</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>&#8211;</p></td><td
colspan="1" rowspan="1" class="co
 nfluenceTd"><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>&lt;t:textfield value="name"
validate="required" /&gt;</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><p>Update
the two fields of the Login page:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelCont
 ent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
 @Persist
+  @Property
+  @Validate(&quot;required&quot;)
+  private String userName;
+
+  @Property
+  @Validate(&quot;required&quot;)
+ private String password;]]></script>
+</div></div><p>Now, rebuild the app, refresh the browser, and just hit
enter:</p><p>&#160;</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 n
 ot 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 validat
 ion 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[
 &lt;t:textfield t:id=&quot;ssn&quot; validate=&quot;required,regexp&quot;/&gt;
 ]]></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">



Mime
View raw message