tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r946234 [3/3] - in /websites/production/tapestry/content: ./ cache/ development-dashboard.data/ forms-and-validation.data/
Date Fri, 03 Apr 2015 20:19:44 GMT
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 20:19:44 2015
@@ -98,14 +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.rbtoc1428088772174 {padding: 0px;}
-div.rbtoc1428088772174 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1428088772174 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1428092366722 {padding: 0px;}
+div.rbtoc1428092366722 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1428092366722 li {margin-left: 0px;padding-left: 0px;}
 
-/*]]>*/</style></p><div class="toc-macro rbtoc1428088772174">
+/*]]>*/</style></p><div class="toc-macro rbtoc1428092366722">
 <ul class="toc-indentation"><li>Related Articles</li></ul>
 <ul><li><a shape="rect" href="#FormsandValidation-TheFormComponent">The
Form Component</a>
-<ul class="toc-indentation"><li><a shape="rect" href="#FormsandValidation-FormEvents">Form
Events</a></li><li><a shape="rect" href="#FormsandValidation-TrackingValidationErrors">Tracking
Validation Errors</a></li><li><a shape="rect" href="#FormsandValidation-StoringDataBetweenRequests">Storing
Data Between Requests</a></li><li><a shape="rect" href="#FormsandValidation-ConfiguringFieldsandLabels">Configuring
Fields and Labels</a></li><li><a shape="rect" href="#FormsandValidation-CentralizingValidationwith@Validate">Centralizing
Validation with @Validate</a></li><li><a shape="rect" href="#FormsandValidation-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-ServerSideValidation">Server
Side Validation</a></li><li><a shape="rect" href="#FormsandValidation-CustomizingValidationMessages">Customizing
Validation Messages</a>
 <ul class="toc-indentation"><li><a shape="rect" href="#FormsandValidation-CustomizingValidationMessagesforBeanEditForm">Customizing
Validation Messages for BeanEditForm</a></li></ul>
 </li><li><a shape="rect" href="#FormsandValidation-ConfiguringValidatorContraintsintheMessageCatalog">Configuring
Validator Contraints in the Message Catalog</a></li><li><a shape="rect"
href="#FormsandValidation-ValidationMacros">Validation Macros</a></li><li><a
shape="rect" href="#FormsandValidation-OverridingtheTranslatorwithEvents">Overriding the
Translator with Events</a></li></ul>
 </li></ul></div><h1 id="FormsandValidation-TheFormComponent">The
Form Component</h1><p>The core of Tapestry's form support is the <a shape="rect"
class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html">Form</a>
component. The Form component encloses (wraps around) all the other <em>field components</em>
such as <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextField.html">TextField</a>,
<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextArea.html">TextArea</a>,
<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Checkbox.html">Checkbox</a>,
etc.</p><h2 id="FormsandValidation-FormEvents">Form Events</h2><p>The
Form component emits a number of <a shape="rect" href="component-events.html">
 component events</a>. You'll need to provide event handler methods for some of these.</p><p>When
rendering, the Form component emits two notifications: first, "prepareForRender", then "prepare".
These allow the Form's container to setup any fields or properties that will be referenced
in the form. For example, this is a good place to create a temporary entity object to be rendered,
or to load an entity from a database to be edited.</p><p>When user submits the
form on the client, a series of steps occur on the server.</p><p>First, the Form
emits a "prepareForSubmit" notification, then a "prepare" notification. These allow the container
to ensure that objects are set up and ready to receive information from the form submission.</p><p>Next,
all the fields inside the form are activated to pull values out of the incoming request, validate
them and (if valid) store the changes.</p><div class="navmenu" style="float:right;
width:25%; background:#eee; margin:3px; padding:3px">
@@ -197,7 +197,7 @@ public class Login {
 
 &lt;/html&gt;
 ]]></script>
-</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">
+</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=3&amp;modificationDate=1428088849224&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;
@@ -211,7 +211,25 @@ public class Login {
   @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">
+</div></div><p>Now, rebuild the app, refresh the browser, and just hit
enter:</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=3&amp;modificationDate=1428088849224&amp;api=v2"></p><p>The
form has updated, in place, to present the errors. You will not be able to submit the form
until some value is provided for each field.</p><h2 id="FormsandValidation-ServerSideValidation">Server
Side Validation</h2><p>Some validation can't, or shouldn't, be done on the client
side. How do we know if the password is correct? Short of downloading all users and passwords
to the client, we really need to do the validation on the server.</p><p>In fact,
all client-side validation (via the validate parameter, or&#160;@Validate annotation)
is performed again on the server.</p><p>It is also possible to perform extr
 a validation there.</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[
 /**
+     * Do the cross-field validation
+     */
+    void onValidateFromLoginForm() {
+        if (!authenticator.isValid(userName, password)) {
+            // record an error, and thereby prevent Tapestry from emitting a &quot;success&quot;
event
+            loginForm.recordError(passwordField, &quot;Invalid user name or password.&quot;);
+        }
+    }
+
+]]></script>
+</div></div><p>This is the validate event handler from the loginForm component.
It is invoked once all the components have had a chance to read values out of the request,
do their own validations, and update the properties they are bound to.</p><p>In
this case, the authenticator is used to decide if the userName and password is valid. In a
real application, this would be where a database or other external service was consulted.</p><p>If
the combination is not valid, then the password field is marked as in error. The form is used
to record an error, about a component (the passwordField) with an error message.</p><p>Entering
any two values into the form and submitting will cause a round trip; the form will re-render
to present the error to the user:</p><p><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?v
 ersion=3&amp;modificationDate=1428088849224&amp;api=v2"></p><p>Notice
that the cursor is placed directly into the password field.</p>    <div class="aui-message
warning shadowed information-macro">
+                            <span class="aui-icon icon-warning">Icon</span>
+                <div class="message-content">
+                            <p>In versions of Tapestry prior to 5.4, a form with validation
errors would result in a redirect response to the client; often, temporary server-side data
(such as the userName field) would be lost. Starting in 5.4, submitting a form with validation
errors results in the new page being rendered in the same request as the form submission.</p>
+                    </div>
+    </div>
+<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 not message for that key,
a second check is made, for <em>fieldId</em>-<em>validat
 orName</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 w
 ith 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