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 Wed Sep 20
12:29:16 2017
@@ -27,6 +27,16 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,14 +77,68 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Forms</strong> are the
traditional way for most web applications to gather significant information
from the user. Whether it's a search form, a login screen or a multi-page
registration wizard, Tapestry uses standard HTML forms, with HTTP POST actions
by default. In addition, AJAX-based form submission is supported using <a
href="ajax-and-zones.html">Zones</a>.</p><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label in ("validation","forms")
and space = currentSpace()</parameter></rich-text-body><p> </p><p>Tapestry
provides support for creating and rendering forms, populating their fields, and
validating user input. For simple ca
ses, input validation is declarative, meaning you simply tell Tapestry what
validations to apply to a given field, and it takes care of it on the server
and (optionally) on the client as well. In addition, you can provide event
handler methods in your page or component classes to handle more complex
validation scenarios.</p><p>Finally, Tapestry not only makes it easy to present
errors messages to the user, but it can also automatically highlight form
fields when validation fails.</p><p><strong>Contents</strong></p><p></p><h2
id="FormsandValidation-TheFormComponent">The Form Component</h2><p>The core of
Tapestry's form support is the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html";>Form</a>
component. The Form component encloses (wraps around) all the other <em>field
components</em> such as <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components
/TextField.html">TextField</a>, <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextArea.html";>TextArea</a>,
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Checkbox.html";>Checkbox</a>,
etc.</p><h2 id="FormsandValidation-FormEvents">Form Events</h2><p>The Form
component emits a number of <a href="component-events.html">component
events</a>. You'll want to provide event handler methods for some of
these.</p><p>When rendering, the Form component emits two events: first,
"prepareForRender", then "prepare". These allow the Form's container to set up
any fields or properties that will be referenced in the form. For example, this
is a good place to create a temporary entity object to be rendered, or to load
an entity from a database to be edited.</p><p>When user submits the form on the
client, a series of steps occur on the server.</p><p>First, the Form em
its a "prepareForSubmit" event, then a "prepare" event. These allow the
container to ensure that objects are set up and ready to receive information
from the form submission.</p><p>Next, all the fields inside the form are
<em>activated</em> to pull values out of the incoming request, validate them
and (if valid) store the
changes.<plain-text-body>{float:right|width=25%|background=#eee}
-_For Tapestry 4 Users:_ 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.
-{float}</plain-text-body> </p><p>After the fields have done their
processing, the Form emits a "validate" event. This is your chance to perform
any cross-form validation that can't be described declaratively.</p><p>Next,
the Form determines if there have been any validation errors. If there have
been, then the submission is considered a failure, and a "failure" event is
emitted. If there have been no validation errors, then a "success" event is
emitted.</p><p>Finally, the Form emits a "submit" event, for logic that doesn't
care about success or failure.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Form Event (in order)</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Phase</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>When emitted (and typical use)</p></th><th colspan="1"
rowspan="1" class="confluenceTh">Method Name</th><th colspan="1" rowspan="1"
class="confluenceTh">@OnEvent C
onstant</th></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>prepareForRender</strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Render</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Before rendering the form (e.g. load an
entity from a database to be edited)</p></td><td colspan="1" rowspan="1"
class="confluenceTd">onPrepareForRender()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.PREPARE_FOR_RENDER</td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><strong>prepare</strong></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Render</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Before rendering the form, but after
<em>prepareForRender</em></p></td><td colspan="1" rowspan="1"
class="confluenceTd">onPrepare()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.PREPARE</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>prepareForSubmit</stron
g></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Before the submitted form is processed</p></td><td
colspan="1" rowspan="1" class="confluenceTd">onPrepareForSubmit()</td><td
colspan="1" rowspan="1"
class="confluenceTd">EventConstants.PREPARE_FOR_SUBMIT</td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><strong>prepare</strong></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Before the submitted form is processed, but after
<em>prepareForSubmit</em></p></td><td colspan="1" rowspan="1"
class="confluenceTd">onPrepare()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.PREPARE</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>validate</strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>After f
ields have been populated from submitted values and validated (e.g. perform
cross-field validation)</p></td><td colspan="1" rowspan="1"
class="confluenceTd">onValidate</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.VALIDATE</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>validateForm</strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>same as <em>validate (deprecated – do
not use)<br clear="none"></em></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><em>onValidateForm</em></td><td colspan="1" rowspan="1"
class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>failure</strong></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>After one or more validation errors have
occurred</p></td><td colspan="1" rowspan="1" class="conf
luenceTd">onFailure()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.FAILURE</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>success</strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>When validation has completed
<em>without</em> any errors (e.g. save changes to the database)</p></td><td
colspan="1" rowspan="1" class="confluenceTd">onSuccess()</td><td colspan="1"
rowspan="1" class="confluenceTd">EventConstants.SUCCESS</td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><strong>submit</strong></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>After all validation (success or failure) has
finished</p></td><td colspan="1" rowspan="1"
class="confluenceTd">onSubmit()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.SUBMIT</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><strong>canceled</strong></td><td colspan="1"
rowspan="1" class="confluenceTd">Submit</td><td colspan="1" rowspan="1"
class="confluenceTd">Whenever a <em>Submit</em> or <em>LinkSubmit</em>
component containing <em>mode="cancel"</em> or <em>mode="unconditional"</em> is
clicked</td><td colspan="1" rowspan="1"
class="confluenceTd">onCanceled()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.CANCELED</td></tr></tbody></table></div><p>Note
that the "prepare" event is emitted during both form rendering and form
submission.</p><h2 id="FormsandValidation-HandlingEvents">Handling
Events</h2><p>Main Article: <a href="component-events.html">Component
Events</a></p><p>You handle events by providing methods in your page or
component class, either following the
on<strong><em>Event</em></strong>From<strong><em>Component</em></strong>()
naming convention or using the OnEvent annotation. For example:</p><parameter
ac:name="language">java</paramet
er><parameter ac:name="title">Event Handler Using Naming
Convention</parameter><plain-text-body> void onValidateFromPassword() {
...}</plain-text-body><p>or the equivalent using @OnEvent:</p><parameter
ac:name="language">java</parameter><parameter ac:name="title">Event Handler
Using @OnEvent Annotation</parameter><plain-text-body>
@OnEvent(value=EventConstants.VALIDATE, component="password")
- void verifyThePassword() { ...}</plain-text-body><h2
id="FormsandValidation-TrackingValidationErrors">Tracking Validation
Errors</h2><p>Associated with the Form is a <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValidationTracker.html";>ValidationTracker</a>
that tracks all the provided user input and validation errors for every field
in the form. The tracker can be provided to the Form via the Form's tracker
parameter, but this is rarely necessary.</p><p>The Form includes methods
<code>isValid()</code> and <code>getHasErrors()</code>, which are used to see
if the Form's validation tracker contains any errors.</p><p>In your own logic,
it is possible to record your own errors. Form includes two different versions
of method <code>recordError()</code>, one of which specifies a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Field.html";>Field</a>
(an interface implemented by all form ele
ment components), and one of which is for "global" errors, not associated with
any particular field. If the error concerns only a single field, you should use
the first version so that the field will be highlighted.</p><h2
id="FormsandValidation-StoringDataBetweenRequests">Storing Data Between
Requests</h2><p><plain-text-body>{float:right|width=40%}
-{info:title=New in Tapestry 5.4}
-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.
-{info}
-{float}</plain-text-body>As with other action requests, the result of a form
submission (except when using <a 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
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 class, which collects a user name
and a password, might look like:</p><parameter
ac:name="language">java</parameter><parameter ac:name="title">Login.ja
va Example</parameter><plain-text-body>package com.example.newapp.pages;
+ <div id="ConfluenceContent"><p><strong>Forms</strong> are the
traditional way for most web applications to gather significant information
from the user. Whether it's a search form, a login screen or a multi-page
registration wizard, Tapestry uses standard HTML forms, with HTTP POST actions
by default. In addition, AJAX-based form submission is supported using <a
href="ajax-and-zones.html">Zones</a>.</p><div class="aui-label"
style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="forms-and-validation.html">Forms and
Validation</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="forms-and-form-components-faq.html">Forms
and Form Components FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="bean-validation.html">Bean Validation</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p> </p><p>Tapestry provides support for creating and rendering forms,
populating their fields, and validating user input. For simple cases, input
validation is declarative, meaning you simply tell Tapestry what validations to
apply to a given field, and it takes care of it on the server and (optionally)
on the client as well. In addition, you can provide event handler
methods in your page or component classes to handle more complex
validation scenarios.</p><p>Finally, Tapestry not only makes it easy to present
errors messages to the user, but it can also automatically highlight form
fields when validation fails.</p><p><strong>Contents</strong></p><p><style
type="text/css">/*<![CDATA[*/
+div.rbtoc1499639542745 {padding: 0px;}
+div.rbtoc1499639542745 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1499639542745 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></p><div class="toc-macro rbtoc1499639542745">
+<ul class="toc-indentation"><li>Related Articles</li></ul>
+<ul><li><a href="#FormsandValidation-TheFormComponent">The Form
Component</a></li><li><a href="#FormsandValidation-FormEvents">Form
Events</a></li><li><a href="#FormsandValidation-HandlingEvents">Handling
Events</a></li><li><a
href="#FormsandValidation-TrackingValidationErrors">Tracking Validation
Errors</a></li><li><a
href="#FormsandValidation-StoringDataBetweenRequests">Storing Data Between
Requests</a></li><li><a
href="#FormsandValidation-ConfiguringFieldsandLabels">Configuring Fields and
Labels</a></li><li><a
href="#FormsandValidation-CentralizingValidationwith@Validate">Centralizing
Validation with @Validate</a></li><li><a
href="#FormsandValidation-ServerSideValidation">Server Side
Validation</a></li><li><a
href="#FormsandValidation-CustomizingValidationMessages">Customizing Validation
Messages</a>
+<ul class="toc-indentation"><li><a
href="#FormsandValidation-CustomizingValidationMessagesforBeanEditForm">Customizing
Validation Messages for BeanEditForm</a></li></ul>
+</li><li><a
href="#FormsandValidation-ConfiguringValidatorContraintsintheMessageCatalog">Configuring
Validator Contraints in the Message Catalog</a></li><li><a
href="#FormsandValidation-ValidationMacros">Validation Macros</a></li><li><a
href="#FormsandValidation-OverridingtheTranslatorwithEvents">Overriding the
Translator with Events</a></li></ul>
+</div><h2 id="FormsandValidation-TheFormComponent">The Form
Component</h2><p>The core of Tapestry's form support is the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html";>Form</a>
component. The Form component encloses (wraps around) all the other <em>field
components</em> such as <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextField.html";>TextField</a>,
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/TextArea.html";>TextArea</a>,
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Checkbox.html";>Checkbox</a>,
etc.</p><h2 id="FormsandValidation-FormEvents">Form Events</h2><p>The Form
component emits a number of <a href="component-events.html">component
events</a>. You'll want to provide event handler methods for
some of these.</p><p>When rendering, the Form component emits two events:
first, "prepareForRender", then "prepare". These allow the Form's container to
set up any fields or properties that will be referenced in the form. For
example, this is a good place to create a temporary entity object to be
rendered, or to load an entity from a database to be edited.</p><p>When user
submits the form on the client, a series of steps occur on the
server.</p><p>First, the Form emits a "prepareForSubmit" event, then a
"prepare" event. These allow the container to ensure that objects are set up
and ready to receive information from the form submission.</p><p>Next, all the
fields inside the form are <em>activated</em> to pull values out of the
incoming request, validate them and (if valid) store the changes.</p><div
class="navmenu" style="float:right; width:25%; background:#eee; margin:3px;
padding:3px">
+<p><em>For Tapestry 4 Users:</em> Tapestry 5 does not use the fragile "form
rewind" approach from Tapestry 4. Instead, a hidden field generated during the
render stores the information needed to process the form
submission.</p></div> <p>After the fields have done their processing, the
Form emits a "validate" event. This is your chance to perform any cross-form
validation that can't be described declaratively.</p><p>Next, the Form
determines if there have been any validation errors. If there have been, then
the submission is considered a failure, and a "failure" event is emitted. If
there have been no validation errors, then a "success" event is
emitted.</p><p>Finally, the Form emits a "submit" event, for logic that doesn't
care about success or failure.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Form Event (in order)</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Phase</p></th><th colspan
="1" rowspan="1" class="confluenceTh"><p>When emitted (and typical
use)</p></th><th colspan="1" rowspan="1" class="confluenceTh">Method
Name</th><th colspan="1" rowspan="1" class="confluenceTh">@OnEvent
Constant</th></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>prepareForRender</strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Render</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Before rendering the form (e.g. load an
entity from a database to be edited)</p></td><td colspan="1" rowspan="1"
class="confluenceTd">onPrepareForRender()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.PREPARE_FOR_RENDER</td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><strong>prepare</strong></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Render</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Before rendering the form, but after
<em>prepareForRender</em></p></td><td colspan="1" rowspan="1" c
lass="confluenceTd">onPrepare()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.PREPARE</td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><strong>prepareForSubmit</strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Before the submitted form is
processed</p></td><td colspan="1" rowspan="1"
class="confluenceTd">onPrepareForSubmit()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.PREPARE_FOR_SUBMIT</td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><strong>prepare</strong></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Before the submitted form is processed, but after
<em>prepareForSubmit</em></p></td><td colspan="1" rowspan="1"
class="confluenceTd">onPrepare()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.PREPARE</td></tr><tr><td cols
pan="1" rowspan="1"
class="confluenceTd"><p><strong>validate</strong></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>After fields have been populated from submitted values
and validated (e.g. perform cross-field validation)</p></td><td colspan="1"
rowspan="1" class="confluenceTd">onValidate</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.VALIDATE</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>validateForm</strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>same as <em>validate (deprecated – do
not use)<br clear="none"></em></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><em>onValidateForm</em></td><td colspan="1" rowspan="1"
class="confluenceTd"> </td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>failure</strong></p></td><td colspan=
"1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>After one or more validation errors have
occurred</p></td><td colspan="1" rowspan="1"
class="confluenceTd">onFailure()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.FAILURE</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>success</strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>When validation has completed
<em>without</em> any errors (e.g. save changes to the database)</p></td><td
colspan="1" rowspan="1" class="confluenceTd">onSuccess()</td><td colspan="1"
rowspan="1" class="confluenceTd">EventConstants.SUCCESS</td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><strong>submit</strong></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Submit</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>After all validation (s
uccess or failure) has finished</p></td><td colspan="1" rowspan="1"
class="confluenceTd">onSubmit()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.SUBMIT</td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><strong>canceled</strong></td><td colspan="1"
rowspan="1" class="confluenceTd">Submit</td><td colspan="1" rowspan="1"
class="confluenceTd">Whenever a <em>Submit</em> or <em>LinkSubmit</em>
component containing <em>mode="cancel"</em> or <em>mode="unconditional"</em> is
clicked</td><td colspan="1" rowspan="1"
class="confluenceTd">onCanceled()</td><td colspan="1" rowspan="1"
class="confluenceTd">EventConstants.CANCELED</td></tr></tbody></table></div><p>Note
that the "prepare" event is emitted during both form rendering and form
submission.</p><h2 id="FormsandValidation-HandlingEvents">Handling
Events</h2><p>Main Article: <a href="component-events.html">Component
Events</a></p><p>You handle events by providing methods in your page or
component class, ei
ther following the
on<strong><em>Event</em></strong>From<strong><em>Component</em></strong>()
naming convention or using the OnEvent annotation. For example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Event Handler Using
Naming Convention</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> void onValidateFromPassword() { ...}</pre>
+</div></div><p>or the equivalent using @OnEvent:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Event Handler Using @OnEvent
Annotation</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> @OnEvent(value=EventConstants.VALIDATE,
component="password")
+ void verifyThePassword() { ...}</pre>
+</div></div><h2 id="FormsandValidation-TrackingValidationErrors">Tracking
Validation Errors</h2><p>Associated with the Form is a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValidationTracker.html";>ValidationTracker</a>
that tracks all the provided user input and validation errors for every field
in the form. The tracker can be provided to the Form via the Form's tracker
parameter, but this is rarely necessary.</p><p>The Form includes methods
<code>isValid()</code> and <code>getHasErrors()</code>, which are used to see
if the Form's validation tracker contains any errors.</p><p>In your own logic,
it is possible to record your own errors. Form includes two different versions
of method <code>recordError()</code>, one of which specifies a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Field.html";>Field</a>
(an interface implemented by all form element components), and one of which is
for
"global" errors, not associated with any particular field. If the error
concerns only a single field, you should use the first version so that the
field will be highlighted.</p><h2
id="FormsandValidation-StoringDataBetweenRequests">Storing Data Between
Requests</h2><p></p><div class="navmenu" style="float:right; width:40%;
background:white; margin:3px; padding:3px">
+<div class="confluence-information-macro
confluence-information-macro-information"><p class="title">New in Tapestry
5.4</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
+<p>Starting in Tapestry 5.4, the default behavior for server-side validation
failures is to re-render the page within the same request (rather than emitting
a redirect). This removes the need to use a session-persistent field to store
the validation tracker when validation failures occur.</p></div></div></div>As
with other action requests, the result of a form submission (except when using
<a 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 href="persistent-page-data.html">persisted</a>
(generally in the HttpSession) across these two requests in order to prevent
the loss of validation information. Fortunately, the default ValidationTracker
provided by the Form component is persistent, so you don't normally have to
worry about it.<p>However, for the same reason, the individual fields updated
by the components should also be persisted across requests, and this is som
ething you <strong>do</strong> need to do yourself – generally with the
@Persist annotation.</p><p>For example, a Login page class, which collects a
user name and a password, might look like:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Login.java Example</b></div><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package com.example.newapp.pages;
import com.example.newapp.services.UserAuthenticator;
@@ -120,11 +184,11 @@ public class Login {
}
-</plain-text-body><p><plain-text-body>{float:right|width=40%}
-{info}
-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.
-{info}
-{float}</plain-text-body>Because a form submission is really <em>two</em>
requests: the submission itself (which results in a redirect response), then a
second request for the page (which results in a re-rendering of the page), it
is necessary to persist the userName field between the two requests, by using
the @Persist annotation. This would be necessary for the password field as
well, except that the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/PasswordField.html";>PasswordField</a>
component never renders a value.</p><rich-text-body><p>To avoid data loss,
fields whose values are stored in the HttpSession (such as userName, above)
must be serializable, particularly if you want to be able to cluster your
application or preserve sessions across server
restarts.</p></rich-text-body><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 Login page template below contains a minimal
amount of Tapestry instrumentation and references some of the <a
class="external-link" href="http://getbootstrap.com";
rel="nofollow">Bootstrap</a> CSS classes (Bootstrap is automatically integrated
into each page by default, starting with Tapestry 5.4).</p><parameter
ac:name="language">xml</parameter><parameter ac:name="title">Login.tml Exampl
e</parameter><plain-text-body><html t:type="layout" title="newapp
com.example"
+</pre>
+</div></div><p></p><div class="navmenu" style="float:right; width:40%;
background:white; margin:3px; padding:3px">
+<div class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
+<p>Note that the onValidateFromLoginForm() and onSuccess() methods are not
public; event handler methods can have any visibility, even private. Package
private (that is, no modifier) is the typical use, as it allows the component
to be tested, from a test case class in the same
package.</p></div></div></div>Because a form submission is really <em>two</em>
requests: the submission itself (which results in a redirect response), then a
second request for the page (which results in a re-rendering of the page), it
is necessary to persist the userName field between the two requests, by using
the @Persist annotation. This would be necessary for the password field as
well, except that the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/PasswordField.html";>PasswordField</a>
component never renders a value.<div class="confluence-information-macro
confluence-information-macro-tip"><span class="aui-icon aui-icon-small
aui-iconfo
nt-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>To avoid data loss, fields whose
values are stored in the HttpSession (such as userName, above) must be
serializable, particularly if you want to be able to cluster your application
or preserve sessions across server restarts.</p></div></div><p>The Form only
emits a "success" event if the there are no prior validation errors. This means
it is not necessary to write <code>if (form.getHasErrors()) return;</code> as
the first line of the method.</p><p>Finally, notice how business logic fits
into validation. The UserAuthenticator service is responsible for ensuring that
the userName and (plaintext) password are valid. When it returns false, we ask
the Form component to record an error. We provide the PasswordField instance as
the first parameter; this ensures that the password field, and its label, are
decorated when the Form is re-rendered, to present the errors to the
user.</p><h2 id
="FormsandValidation-ConfiguringFieldsandLabels">Configuring Fields and
Labels</h2><p>The Login page template below contains a minimal amount of
Tapestry instrumentation and references some of the <a class="external-link"
href="http://getbootstrap.com"; rel="nofollow">Bootstrap</a> CSS classes
(Bootstrap is automatically integrated into each page by default, starting with
Tapestry 5.4).</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Login.tml Example</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><html t:type="layout" title="newapp com.example"
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<div class="row">
@@ -139,18 +203,26 @@ Note that the onValidateFromLoginForm()
</div>
</html>
-</plain-text-body><p>Rendering the page gives a reasonably pleasing first
pass:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-content-image-border image-center" width="500"
src="forms-and-validation.data/newapp_com_example.png"></span></p><p>The
Tapestry Form component is responsible for creating the necessary URL for the
form submission (this is Tapestry's responsibility, not yours).</p><p><span
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. </span></p><p>As a rule of
thumb, you should always give your fields a specific id (this id will be used
to generate the <code>name</code> a
nd <code>id</code> attributes of the rendered tag). Being allowed to omit the
value parameter helps to keep the template from getting too
cluttered.</p><p>The FormGroup mixin decorates the field with some additional
markup, including a <label> element; this leverages more of
Bootstrap.</p><parameter ac:name="language">xml</parameter><parameter
ac:name="title">userName component as
rendered</parameter><plain-text-body><div class="form-group">
+</pre>
+</div></div><p>Rendering the page gives a reasonably pleasing first
pass:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-content-image-border image-center" width="500"
src="forms-and-validation.data/newapp_com_example.png"></span></p><p>The
Tapestry Form component is responsible for creating the necessary URL for the
form submission (this is Tapestry's responsibility, not yours).</p><p><span
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. </span></p><p>As a rule of
thumb, you should always give your fields a specific id (this id will be used
to generate the <code>name</code> and <co
de>id</code> attributes of the rendered tag). Being allowed to omit the value
parameter helps to keep the template from getting too cluttered.</p><p>The
FormGroup mixin decorates the field with some additional markup, including a
<label> element; this leverages more of Bootstrap.</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>userName component as
rendered</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><div class="form-group">
<label for="userName" class="control-label">User Name</label>
<input id="userName" class="form-control" name="userName" type="text">
-</div></plain-text-body><p> </p><p><span style="color:
rgb(83,145,38);font-size: 24.0px;line-height: 1.25;">Form
Validation</span></p><p>The above example is a very basic form which allows the
fields to be empty. However, with a little more effort we can add client-side
validation to prevent the user from submitting the form with either field
empty.</p><p>Validation in Tapestry involves associating one or
more <em>validators</em> with a form element component, such as TextField
or PasswordField. This is done using the <strong>validate</strong>
parameter:</p><parameter
ac:name="language">xml</parameter><plain-text-body><t:textfield
t:id="userName" validate="required" t:mixins="formgroup"/>
-<t:passwordfield t:id="password" value="password" validate="required"
t:mixins="formgroup"/></plain-text-body><p> </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>–</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="emai
l" 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"
rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Makes sure that a string value has a minimum
length</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="somefield"
validate="minlength=1" /></code></p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>none</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>–</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Does nothing (used to override a @Validate
annotation)</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="somefield" validate="none"
/></code></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>rege
xp</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 class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/b
eaneditor/Validate.html">Validate</a> annotation can take the place of the
validate parameter of TextField, PasswordField, TextArea and other components.
When the validate parameter is not bound in the template file, the component
will check for the @Validate annotation and use its value as the validation
definition.</p><p>The annotation may be placed on the getter or setter method,
or on the field itself.</p><p>Let's update the two fields of the Login
page:</p><parameter ac:name="language">java</parameter><plain-text-body>
@Persist
+</div></pre>
+</div></div><p> </p><p><span style="color: rgb(83,145,38);font-size:
24.0px;line-height: 1.25;">Form Validation</span></p><p>The above example is a
very basic form which allows the fields to be empty. However, with a little
more effort we can add client-side validation to prevent the user from
submitting the form with either field empty.</p><p>Validation in Tapestry
involves associating one or more <em>validators</em> with a form element
component, such as TextField or PasswordField. This is done using the
<strong>validate</strong> parameter:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:textfield t:id="userName" validate="required"
t:mixins="formgroup"/>
+<t:passwordfield t:id="password" value="password" validate="required"
t:mixins="formgroup"/></pre>
+</div></div><p> </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>–</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>ma
x</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>long</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Enforces a maximum integer
value</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="age"
validate="max=120,min=0" /></code></p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>maxLength</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Makes sure that a string value has a maximum
length</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="zip"
validate="maxlength=7" /></code></p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>min</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>long</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Enforces a minimum integer value</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield value="
age" validate="max=120,min=0" /></code></p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>minLength</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Makes sure that a string value has a minimum
length</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="somefield"
validate="minlength=1" /></code></p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>none</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>–</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Does nothing (used to override a @Validate
annotation)</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="somefield" validate="none"
/></code></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>regexp</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>pattern</p></td><td colspan="1" rowspan="
1" class="confluenceTd"><p>Makes sure that a string value conforms to a given
pattern</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="letterfield"
validate="regexp=^</code><code>[A-Za-z]+$" /></code></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>required</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>–</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Makes sure that a string value is not null
and not the empty string</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="name" validate="required"
/></code></p></td></tr></tbody></table></div><h2
id="FormsandValidation-CentralizingValidationwith@Validate">Centralizing
Validation with @Validate</h2><p>The @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html";>Validate</a>
annotation can take the place of the validate parameter of TextFie
ld, PasswordField, TextArea and other components. When the validate parameter
is not bound in the template file, the component will check for the @Validate
annotation and use its value as the validation definition.</p><p>The annotation
may be placed on the getter or setter method, or on the field
itself.</p><p>Let's update the two fields of the Login page:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> @Persist
@Property
@Validate("required")
private String userName;
@Property
@Validate("required")
- private String password;</plain-text-body><p>Now, we'll rebuild the app,
refresh the browser, and just hit enter:</p><p><span
class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-content-image-border image-center" width="500"
src="forms-and-validation.data/newapp_com_example.png"></span></p><p>The form
has updated, in place, to present the errors. You will not be able to submit
the form until some value is provided for each field.</p><h2
id="FormsandValidation-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 @Validate
annotation) is performed again on the server.</p><p>It is also possible to
perfor
m extra validation there.</p><parameter
ac:name="language">java</parameter><plain-text-body> /**
+ private String password;</pre>
+</div></div><p>Now, we'll rebuild the app, refresh the browser, and just hit
enter:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-content-image-border image-center" width="500"
src="forms-and-validation.data/newapp_com_example.png"></span></p><p>The form
has updated, in place, to present the errors. You will not be able to submit
the form until some value is provided for each field.</p><h2
id="FormsandValidation-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 @Validate
annotation) is performed again on the server.</p><p>It is also possible to
perform extra validation there.</p><d
iv class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> /**
* Do the cross-field validation
*/
void onValidateFromLoginForm() {
@@ -160,22 +232,34 @@ Note that the onValidateFromLoginForm()
}
}
-</plain-text-body><p>This is the validate event handler from the loginForm
component. It is invoked once all the components have had a chance to read
values out of the request, do their own validations, and update the properties
they are bound to.</p><p>In this case, the authenticator is used to decide if
the userName and password is valid. In a real application, this would be where
a database or other external service was consulted.</p><p>If the combination is
not valid, then the password field is marked as in error. The form is used to
record an error, about a component (the passwordField) with an error
message.</p><p>Entering any two values into the form and submitting will cause
a round trip; the form will re-render to present the error to the
user:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-content-image-border image-center" width="500"
src="forms-and-validation.data/
newapp_com_example.png"></span></p><p>Notice that the cursor is placed
directly into the password field.</p><rich-text-body><p>In versions of Tapestry
prior to 5.4, a form with validation errors would result in a redirect response
to the client; often, temporary server-side data (such as the userName field)
would be lost. Starting in 5.4, submitting a form with validation errors
results in the new page being rendered in the same request as the form
submission.</p></rich-text-body><p> </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
href="localization.html">message catalog</a> (or the containing component's
message catalog). As with any localized property, this can
also go into the application's message catalog.</p><p>The first key checked
is
<em>formId</em>-<em>fieldId</em>-<em>validatorName</em>-message.</p><ul><li>formId:
the local component id of the Form component</li><li>fieldId: the local
component id of the field (TextField, etc.)</li><li>validatorName: the name of
the validator, i.e., "required" or "minlength"</li></ul><p>If there is no
message for that key, a second check is made, for
<em>fieldId</em>-<em>validatorName</em>-message. <span style="font-size:
14.0px;">If</span><span style="font-size: 14.0px;"> that does not match a
message, then the built-in default validation message is
used.</span></p><p><span style="font-size: 14.0px;">For example, if the form ID
is "loginForm", the field ID is "userName", and the validator is "required"
then Tapestry will first look for a "loginForm-userName-required-message" key
in the message catalog, and then for a "<span>userName-required-message"
key.</span></span></p><p>The validati
on message in the message catalog may contain <a class="external-link"
href="https://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html";
rel="nofollow">printf-style format strings</a> (such as %s) to indicate
where the validate parameter's value will be inserted. For example, if the
validate parameter in the template is minLength=3 and the validation message is
"User name must be at least %s characters" then the corresponding error message
would be <span>"User name must be at least 5 characters".</span></p><h3
id="FormsandValidation-CustomizingValidationMessagesforBeanEditForm">Customizing
Validation Messages for BeanEditForm</h3><p>The <a
href="beaneditform-guide.html">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-Configur
ingValidatorContraintsintheMessageCatalog">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><parameter
ac:name="language">xml</parameter><plain-text-body> <t:textfield t:id="ssn"
validate="required,regexp"/>
-</plain-text-body><p>And your message catalog can contain:</p><parameter
ac:name="language">java</parameter><plain-text-body>ssn-regexp=\d{3}-\d{2}-\d{4}
+</pre>
+</div></div><p>This is the validate event handler from the loginForm
component. It is invoked once all the components have had a chance to read
values out of the request, do their own validations, and update the properties
they are bound to.</p><p>In this case, the authenticator is used to decide if
the userName and password is valid. In a real application, this would be where
a database or other external service was consulted.</p><p>If the combination is
not valid, then the password field is marked as in error. The form is used to
record an error, about a component (the passwordField) with an error
message.</p><p>Entering any two values into the form and submitting will cause
a round trip; the form will re-render to present the error to the
user:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-content-image-border image-center" width="500"
src="forms-and-validation.data/newapp
_com_example.png"></span></p><p>Notice that the cursor is placed directly into
the password field.</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>In versions of Tapestry prior to
5.4, a form with validation errors would result in a redirect response to the
client; often, temporary server-side data (such as the userName field) would be
lost. Starting in 5.4, submitting a form with validation errors results in the
new page being rendered in the same request as the form
submission.</p></div></div><p> </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 m
essage can be customized by adding an entry to the page's <a
href="localization.html">message catalog</a> (or the containing component's
message catalog). As with any localized property, this can also go into the
application's message catalog.</p><p>The first key checked is
<em>formId</em>-<em>fieldId</em>-<em>validatorName</em>-message.</p><ul><li>formId:
the local component id of the Form component</li><li>fieldId: the local
component id of the field (TextField, etc.)</li><li>validatorName: the name of
the validator, i.e., "required" or "minlength"</li></ul><p>If there is no
message for that key, a second check is made, for
<em>fieldId</em>-<em>validatorName</em>-message. <span style="font-size:
14.0px;">If</span><span style="font-size: 14.0px;"> that does not match a
message, then the built-in default validation message is
used.</span></p><p><span style="font-size: 14.0px;">For example, if the form ID
is "loginForm", the field ID is "userName", and the validator is "re
quired" then Tapestry will first look for a
"loginForm-userName-required-message" key in the message catalog, and then for
a "<span>userName-required-message" key.</span></span></p><p>The validation
message in the message catalog may contain <a class="external-link"
href="https://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html";
rel="nofollow">printf-style format strings</a> (such as %s) to indicate
where the validate parameter's value will be inserted. For example, if the
validate parameter in the template is minLength=3 and the validation message is
"User name must be at least %s characters" then the corresponding error message
would be <span>"User name must be at least 5 characters".</span></p><h3
id="FormsandValidation-CustomizingValidationMessagesforBeanEditForm">Customizing
Validation Messages for BeanEditForm</h3><p>The <a
href="beaneditform-guide.html">BeanEditForm</a> component also supports
validation message customizing. The search for messages is si
milar; the <em>formId</em> is the component id of the BeanEditForm component
(not the Form component it contains). The <em>fieldId</em> is the property
name.</p><h2
id="FormsandValidation-ConfiguringValidatorContraintsintheMessageCatalog">Configuring
Validator Contraints in the Message Catalog</h2><p>It is possible to omit the
validation constraint from the validate parameter (or @Validator annotation),
in which case it is expected to be stored in the message catalog.</p><p>This is
useful when the validation constraint is awkward to enter inline, such as a
regular expression for use with the regexp validator.</p><p>The key here is
similar to customizing the validation message:
<em>formId</em>-<em>fieldId</em>-<em>validatorName</em> or just
<em>fieldId</em>-<em>validatorName</em>.</p><p>For example, your template may
have the following:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <t:textfield t:id="ssn"
validate="required,regexp"/>
+</pre>
+</div></div><p>And your message catalog can contain:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">ssn-regexp=\d{3}-\d{2}-\d{4}
ssn-regexp-message=Social security numbers are in the format 12-34-5678.
-</plain-text-body><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>
+</pre>
+</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="confluence-information-macro
confluence-information-macro-information"><p class="title">Added in
5.2</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
</div></div>
<div class="error"><span class="error">Unknown macro: {div}</span>
-<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><parameter
ac:name="language">java</parameter><plain-text-body>@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">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Contribute(ValidatorMacro.class)
public static void combinePasswordValidators(MappedConfiguration<String,
String> configuration) {
configuration.add("password","required,minlength=5,maxlength=15,");
}
-</plain-text-body><p>Then, you can use this new macro in component templates
and classes:</p><parameter
ac:name="language">xml</parameter><plain-text-body><input t:type="textField"
t:id="password" t:validate="password" />
-</plain-text-body><parameter
ac:name="language">java</parameter><plain-text-body>@Validate("password")
+</pre>
+</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">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><input t:type="textField" t:id="password"
t:validate="password" />
+</pre>
+</div></div><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Validate("password")
private String password;
-</plain-text-body><h2
id="FormsandValidation-OverridingtheTranslatorwithEvents">Overriding the
Translator with Events</h2><p>The TextField, PasswordField and TextArea
components all have a translate parameter, a <a 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 u
sed 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><parameter ac:name="language">java</parameter><plain-text-body>
<t:textfield t:id="quantity" size="10"/>
+</pre>
+</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 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">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <t:textfield t:id="quantity" size="10"/>
. . .
@@ -187,17 +271,22 @@ private String password;
return null;
}
-</plain-text-body><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><parameter ac:name="language">java</parameter><plain-text-body> Object
onParseClientFromQuantity(String input)
+</pre>
+</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">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> Object onParseClientFromQuantity(String input)
{
if ("".equals(input)) return 0;
return null;
}
-</plain-text-body><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
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><parameter ac:name="language">java</parameter><plain-text-body>
void onValidateFromCount(Integer value) throws ValidationException
+</pre>
+</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 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">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> void onValidateFromCount(Integer value) throws
ValidationException
{
if (value.equals(13)) throw new ValidationException("Thirteen is an
unlucky number.");
}
-</plain-text-body><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>
+</pre>
+</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/general-questions.html
==============================================================================
--- websites/production/tapestry/content/general-questions.html (original)
+++ websites/production/tapestry/content/general-questions.html Wed Sep 20
12:29:16 2017
@@ -27,6 +27,16 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,7 +77,16 @@
</div>
<div id="content">
- <div
id="ConfluenceContent"><plain-text-body>{scrollbar}</plain-text-body><h2
id="GeneralQuestions-GeneralQuestions">General Questions</h2><p></p><h3
id="GeneralQuestions-HowdoIgetstartedwithTapestry?">How do I get started with
Tapestry?</h3><p>The easiest way to get started is to use <a
class="external-link" href="http://maven.apache.org";>Apache Maven</a> to create
your initial project; Maven can use an <em>archetype</em> (a kind of project
template) to create a bare-bones Tapestry application for you. See the <a
href="getting-started.html">Getting Started</a> page for more
details.</p><p>Even without Maven, Tapestry is quite easy to set up. You just
need to <a href="download.html">download</a> the binaries and setup your build
to place them inside your WAR's WEB-INF/lib folder. The rest is just some
one-time <a href="configuration.html">configuration of the web.xml deployment
descriptor</a>.</p><h3
id="GeneralQuestions-WhydoesTapestryusePrototype?Whynotinsertfa
voriteJavaScriptlibraryhere?">Why does Tapestry use Prototype? Why not
<em>insert favorite JavaScript library here</em>?</h3><p>An important goal for
Tapestry is seamless DHTML and Ajax integration. To serve that goal, it was
important that the built in components be capable of Ajax operations, such as
dynamically re-rendering parts of the page. Because of that, it made sense to
bundle a well-known JavaScript library as part of Tapestry.</p><p>At the time
(this would be 2006-ish), Prototype and Scriptaculous were well known and well
documented, and jQuery was just getting started.</p><p>The intent has always
been to make this aspect of Tapestry pluggable. Tapestry 5.4 includes the
option of either Prototype or jQuery Tapestry 5.5 will remove Prototype as an
option..</p><h3
id="GeneralQuestions-WhydoesTapestryhaveitsownInversionofControlContainer?WhynotSpringorGuice?">Why
does Tapestry have its own Inversion of Control Container? Why not Spring or
Guice?</h3><p>An Inversion of Contro
l Container is <em>the</em> key piece of Tapestry's infrastructure. It is
absolutely necessary to create software as robust, performant ,and extensible
as Tapestry.</p><p>Tapestry IoC includes a number of features that distinguish
itself from other containers:</p><ul><li>Configured in code, not
XML</li><li>Built-in extension mechanism for services: configurations and
contributions</li><li>Built-in aspect oriented programming model (service
decorations and advice)</li><li>Easy modularization</li><li>Best-of-breed
exception reporting</li></ul><p>Because Tapestry is implemented on top of its
IoC container, and because the container makes it easy to extend or replace any
service inside the container, it is possible to make the small changes to
Tapestry needed to customize it to any project's needs.</p><h3
id="GeneralQuestions-HowdoIupgradefromTapestry4toTapestry5?">How do I upgrade
from Tapestry 4 to Tapestry 5?</h3><p>There is no existing tool that supports
upgrading from Tapestry 4 to
Tapestry 5; Tapestry 5 is a complete rewrite.</p><p>Many of the basic
concepts in Tapestry 4 are still present in Tapestry 5, but refactored,
improved, streamlined, and simplified. The basic concept of pages, templates
and components are largely the same. Other aspects, such as server-side event
handling, is markedly different.</p><h3
id="GeneralQuestions-HowdoIupgradefromoneversionofTapestry5toanother?">How do I
upgrade from one version of Tapestry 5 to another?</h3><p>A lot of effort goes
into making an upgrade from one Tapestry 5 release to another go smoothly. In
the general case, it is just a matter of updating the version number in your
Maven <code>build.xml</code> or Gradle <code>build.gradle</code> file and
executing the appropriate commands (e.g., <code>gradle idea</code> or <code>mvn
eclipse:eclipse</code>) to bring your local workspace up to date with the
latest binaries.</p><p>After changing dependencies, you should always perform a
clean recompile of your application.<
/p><p>We make every effort to ensure backwards-compatibility. Tapestry is
mostly coded in terms of interfaces; those interfaces are stable to a point:
interfaces your code is expected to implement are usually completely frozen;
interfaces your code is expected to invoke, such as the interfaces to IoC
services, are stable, but may have new methods added in a release; existing
methods are not changed.</p><p>In <em>rare</em> cases a choice is necessary
between fixing bugs (or adding essential functionality) and maintaining
complete backwards compatibility; in those cases, an incompatible change may be
introduced. These are always discussed in detail in the <a
href="release-notes.html">Release Notes</a> for the specific release. You
should always read the release notes before attempting an upgrade, and always
(really, <em>always</em>) be prepared to retest your application
afterwards.</p><p>Note that you should be careful any time you make use of
<strong>internal</strong> APIs (you can
tell an API is internal by the package name,
<code>org.apache.tapestry5.internal...</code>. Internal APIs may change <em>at
any time</em>; there's no guarantee of backwards compatibility. Please always
check on the documentation, or consult the user mailing list, to see if there's
a stable, public alternative. If you do make use of internal APIs, be sure to
get a discussion going so that your needs can be met in the future by a stable,
public API.</p><p><span style="color: rgb(83,145,38);font-size:
16.0px;line-height: 1.5625;">Why are there both Request and
HttpServletRequest?</span></p><p>Tapestry's Request interface is <em>very</em>
close to the standard HttpServletRequest interface. It differs in a few ways,
omitting some unneeded methods, and adding a couple of new methods (such as
<code>isXHR()</code>), as well as changing how some existing methods operate.
For example, <code>getParameterNames()</code> returns a sorted List of Strings;
HttpServletRequest returns an Enumeration
, which is a very dated approach.</p><p>However, the stronger reason for
Request (and the related interfaces Response and Session) is to enable the
support for Portlets at some point in the future. By writing code in terms of
Tapestry's Request, and not HttpServletRequest, you can be assured that the
same code will operate in both Servlet Tapestry and Portlet
Tapestry.</p><plain-text-body>{scrollbar}</plain-text-body></div>
+ <div id="ConfluenceContent"><h2
id="GeneralQuestions-GeneralQuestions">General Questions</h2><p><style
type="text/css">/*<![CDATA[*/
+div.rbtoc1499639545088 {padding: 0px;}
+div.rbtoc1499639545088 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1499639545088 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></p><div class="toc-macro rbtoc1499639545088">
+<ul class="toc-indentation"><li><a
href="#GeneralQuestions-GeneralQuestions">General Questions</a>
+<ul class="toc-indentation"><li><a
href="#GeneralQuestions-HowdoIgetstartedwithTapestry?">How do I get started
with Tapestry?</a></li><li><a
href="#GeneralQuestions-WhydoesTapestryusePrototype?WhynotinsertfavoriteJavaScriptlibraryhere?">Why
does Tapestry use Prototype? Why not insert favorite JavaScript library
here?</a></li><li><a
href="#GeneralQuestions-WhydoesTapestryhaveitsownInversionofControlContainer?WhynotSpringorGuice?">Why
does Tapestry have its own Inversion of Control Container? Why not Spring or
Guice?</a></li><li><a
href="#GeneralQuestions-HowdoIupgradefromTapestry4toTapestry5?">How do I
upgrade from Tapestry 4 to Tapestry 5?</a></li><li><a
href="#GeneralQuestions-HowdoIupgradefromoneversionofTapestry5toanother?">How
do I upgrade from one version of Tapestry 5 to another?</a></li></ul>
+</li></ul>
+</div><h3 id="GeneralQuestions-HowdoIgetstartedwithTapestry?">How do I get
started with Tapestry?</h3><p>The easiest way to get started is to use <a
class="external-link" href="http://maven.apache.org";>Apache Maven</a> to create
your initial project; Maven can use an <em>archetype</em> (a kind of project
template) to create a bare-bones Tapestry application for you. See the <a
href="getting-started.html">Getting Started</a> page for more
details.</p><p>Even without Maven, Tapestry is quite easy to set up. You just
need to <a href="download.html">download</a> the binaries and setup your build
to place them inside your WAR's WEB-INF/lib folder. The rest is just some
one-time <a href="configuration.html">configuration of the web.xml deployment
descriptor</a>.</p><h3
id="GeneralQuestions-WhydoesTapestryusePrototype?WhynotinsertfavoriteJavaScriptlibraryhere?">Why
does Tapestry use Prototype? Why not <em>insert favorite JavaScript library
here</em>?</h3><p>An important goal for Tapest
ry is seamless DHTML and Ajax integration. To serve that goal, it was
important that the built in components be capable of Ajax operations, such as
dynamically re-rendering parts of the page. Because of that, it made sense to
bundle a well-known JavaScript library as part of Tapestry.</p><p>At the time
(this would be 2006-ish), Prototype and Scriptaculous were well known and well
documented, and jQuery was just getting started.</p><p>The intent has always
been to make this aspect of Tapestry pluggable. Tapestry 5.4 includes the
option of either Prototype or jQuery Tapestry 5.5 will remove Prototype as an
option..</p><h3
id="GeneralQuestions-WhydoesTapestryhaveitsownInversionofControlContainer?WhynotSpringorGuice?">Why
does Tapestry have its own Inversion of Control Container? Why not Spring or
Guice?</h3><p>An Inversion of Control Container is <em>the</em> key piece of
Tapestry's infrastructure. It is absolutely necessary to create software as
robust, performant ,and extensible as T
apestry.</p><p>Tapestry IoC includes a number of features that distinguish
itself from other containers:</p><ul><li>Configured in code, not
XML</li><li>Built-in extension mechanism for services: configurations and
contributions</li><li>Built-in aspect oriented programming model (service
decorations and advice)</li><li>Easy modularization</li><li>Best-of-breed
exception reporting</li></ul><p>Because Tapestry is implemented on top of its
IoC container, and because the container makes it easy to extend or replace any
service inside the container, it is possible to make the small changes to
Tapestry needed to customize it to any project's needs.</p><h3
id="GeneralQuestions-HowdoIupgradefromTapestry4toTapestry5?">How do I upgrade
from Tapestry 4 to Tapestry 5?</h3><p>There is no existing tool that supports
upgrading from Tapestry 4 to Tapestry 5; Tapestry 5 is a complete
rewrite.</p><p>Many of the basic concepts in Tapestry 4 are still present in
Tapestry 5, but refactored, improved, str
eamlined, and simplified. The basic concept of pages, templates and components
are largely the same. Other aspects, such as server-side event handling, is
markedly different.</p><h3
id="GeneralQuestions-HowdoIupgradefromoneversionofTapestry5toanother?">How do I
upgrade from one version of Tapestry 5 to another?</h3><p>A lot of effort goes
into making an upgrade from one Tapestry 5 release to another go smoothly. In
the general case, it is just a matter of updating the version number in your
Maven <code>build.xml</code> or Gradle <code>build.gradle</code> file and
executing the appropriate commands (e.g., <code>gradle idea</code> or <code>mvn
eclipse:eclipse</code>) to bring your local workspace up to date with the
latest binaries.</p><p>After changing dependencies, you should always perform a
clean recompile of your application.</p><p>We make every effort to ensure
backwards-compatibility. Tapestry is mostly coded in terms of interfaces; those
interfaces are stable to a point: inter
faces your code is expected to implement are usually completely frozen;
interfaces your code is expected to invoke, such as the interfaces to IoC
services, are stable, but may have new methods added in a release; existing
methods are not changed.</p><p>In <em>rare</em> cases a choice is necessary
between fixing bugs (or adding essential functionality) and maintaining
complete backwards compatibility; in those cases, an incompatible change may be
introduced. These are always discussed in detail in the <a
href="release-notes.html">Release Notes</a> for the specific release. You
should always read the release notes before attempting an upgrade, and always
(really, <em>always</em>) be prepared to retest your application
afterwards.</p><p>Note that you should be careful any time you make use of
<strong>internal</strong> APIs (you can tell an API is internal by the package
name, <code>org.apache.tapestry5.internal...</code>. Internal APIs may change
<em>at any time</em>; there's no guara
ntee of backwards compatibility. Please always check on the documentation, or
consult the user mailing list, to see if there's a stable, public alternative.
If you do make use of internal APIs, be sure to get a discussion going so that
your needs can be met in the future by a stable, public API.</p><p><span
style="color: rgb(83,145,38);font-size: 16.0px;line-height: 1.5625;">Why are
there both Request and HttpServletRequest?</span></p><p>Tapestry's Request
interface is <em>very</em> close to the standard HttpServletRequest interface.
It differs in a few ways, omitting some unneeded methods, and adding a couple
of new methods (such as <code>isXHR()</code>), as well as changing how some
existing methods operate. For example, <code>getParameterNames()</code> returns
a sorted List of Strings; HttpServletRequest returns an Enumeration, which is a
very dated approach.</p><p>However, the stronger reason for Request (and the
related interfaces Response and Session) is to enable the support
for Portlets at some point in the future. By writing code in terms of
Tapestry's Request, and not HttpServletRequest, you can be assured that the
same code will operate in both Servlet Tapestry and Portlet Tapestry.</p></div>
</div>
<div class="clearer"></div>
