Modified: websites/production/tapestry/content/forms-and-validation.html
==============================================================================
--- websites/production/tapestry/content/forms-and-validation.html (original)
+++ websites/production/tapestry/content/forms-and-validation.html Sat Feb 3
16:21:22 2018
@@ -77,7 +77,7 @@
</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><div class="aui-label"
style="float:right" title="Related Articles">
+ <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="forms-and-validation.html">Zones</a>.</p><div class="aui-label"
style="float:right" title="Related Articles">
@@ -120,24 +120,24 @@
<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;}
+div.rbtoc1517674838864 {padding: 0px;}
+div.rbtoc1517674838864 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1517674838864 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1499639542745">
+/*]]>*/</style></p><div class="toc-macro rbtoc1517674838864">
<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">
+</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="forms-and-validation.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="forms-and-validation.html">Forms and
Validation</a></p><p>You handle events by providing methods in your page or
component c
lass, either following the
on<strong><em>Event</em></strong>From<strong><em>Component</em></strong>()
naming convention or using the OnEvent annotation. For example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Event Handler Using
Naming Convention</b></div><div class="codeContent panelContent pdl">
<pre class="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">
+<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="forms-and-validation.html">Zones</a>) is to send a redirect to the
client, which results in a second request (to re-render the page). The
ValidationTracker must be <a href="forms-and-validation.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 something you <strong>do</strong> need to do yourself – generally
with the @Persist annotation.</p><p>For example, a Login page class, which
collects a user name and a password, might look like:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Login.java Example</b></div><div
class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package com.example.newapp.pages;
@@ -204,15 +204,15 @@ public class Login {
</html>
</pre>
-</div></div><p>Rendering the page gives a reasonably pleasing first
pass:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-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">
+</div></div><p>Rendering the page gives a reasonably pleasing first
pass:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-external-resource confluence-content-image-border image-center"
width="500"
src="https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2";
data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2";></span></p><p>The
Tapestry Form component is responsible for creating the necessary URL for the
form submission (this is Tapestry's responsibility, not yours).</p><p><span>For
the TextField, we provide a component id, userName. We could specify the
</span><code>value</code><span> parameter, but the default is to match the
TextField's id against a property of the cont
ainer, the Login page, if such a property exists. </span></p><p>As a rule
of thumb, you should always give your fields a specific id (this id will be
used to generate the <code>name</code> and <code>id</code> attributes of the
rendered tag). Being allowed to omit the value parameter helps to keep the
template from getting too cluttered.</p><p>The FormGroup mixin decorates the
field with some additional markup, including a <label> element; this
leverages more of Bootstrap.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>userName component as
rendered</b></div><div class="codeContent panelContent pdl">
<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></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">
+</div></div><p> </p><p><span style="color: rgb(83,145,38);">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">
+</div></div><p> </p><p><span style="color: rgb(83,145,38);">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>max</p></td><td colspan="1" rowspan="
1" class="confluenceTd"><p>long</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Enforces a maximum integer value</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield
value="age" validate="max=120,min=0" /></code></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>maxLength</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Makes sure that a string value has a
maximum length</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="zip"
validate="maxlength=7" /></code></p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>min</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>long</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Enforces a minimum integer value</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code><t:textfield
value="age" validate="max=120,min=0" />
</code></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>minLength</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>int</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Makes sure that a string value has a minimum
length</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="somefield"
validate="minlength=1" /></code></p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>none</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>–</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Does nothing (used to override a @Validate
annotation)</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code><t:textfield value="somefield" validate="none"
/></code></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>regexp</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>pattern</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Makes su
re 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 TextField,
PasswordField, TextArea and oth
er 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")
@@ -221,7 +221,7 @@ public class Login {
@Property
@Validate("required")
private String password;</pre>
-</div></div><p>Now, we'll rebuild the app, refresh the browser, and just hit
enter:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-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">
+</div></div><p>Now, we'll rebuild the app, refresh the browser, and just hit
enter:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-external-resource confluence-content-image-border image-center"
width="500"
src="https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2";
data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2";></span></p><p>The
form has updated, in place, to present the errors. You will not be able to
submit the form until some value is provided for each field.</p><h2
id="FormsandValidation-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 downlo
ading 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><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;"> /**
* Do the cross-field validation
*/
@@ -233,7 +233,7 @@ public class Login {
}
</pre>
-</div></div><p>This is the validate event handler from the loginForm
component. It is invoked once all the components have had a chance to read
values out of the request, do their own validations, and update the properties
they are bound to.</p><p>In this case, the authenticator is used to decide if
the userName and password is valid. In a real application, this would be where
a database or other external service was consulted.</p><p>If the combination is
not valid, then the password field is marked as in error. The form is used to
record an error, about a component (the passwordField) with an error
message.</p><p>Entering any two values into the form and submitting will cause
a round trip; the form will re-render to present the error to the
user:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-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">
+</div></div><p>This is the validate event handler from the loginForm
component. It is invoked once all the components have had a chance to read
values out of the request, do their own validations, and update the properties
they are bound to.</p><p>In this case, the authenticator is used to decide if
the userName and password is valid. In a real application, this would be where
a database or other external service was consulted.</p><p>If the combination is
not valid, then the password field is marked as in error. The form is used to
record an error, about a component (the passwordField) with an error
message.</p><p>Entering any two values into the form and submitting will cause
a round trip; the form will re-render to present the error to the
user:</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
confluence-external-resource confluence-content-image-border image-center"
width="500" src="htt
ps://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2"
data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2";></span></p><p>Notice
that the cursor is placed directly into the password field.</p><div
class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>In versions of Tapestry prior to
5.4, a form with validation errors would result in a redirect response to the
client; often, temporary server-side data (such as the userName field) would be
lost. Starting in 5.4, submitting a form with validation errors results in the
new page being rendered in the same request as the form
submission.</p></div></div><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="forms-and-validation.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. <sp
an>If</span><span> that does not match a message, then the built-in
default validation message is used.</span></p><p><span>For example, if the form
ID is "loginForm", the field ID is "userName", and the validator is "required"
then Tapestry will first look for a "loginForm-userName-required-message" key
in the message catalog, and then for a "<span>userName-required-message"
key.</span></span></p><p>The validation message in the message catalog may
contain <a class="external-link"
href="https://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html";
rel="nofollow">printf-style format strings</a> (such as %s) to indicate
where the validate parameter's value will be inserted. For example, if the
validate parameter in the template is minLength=3 and the validation message is
"User name must be at least %s characters" then the corresponding error message
would be <span>"User name must be at least 5 characters".</span></p><h3
id="FormsandValidation-CustomizingValidati
onMessagesforBeanEditForm">Customizing Validation Messages for
BeanEditForm</h3><p>The <a href="forms-and-validation.html">BeanEditForm</a>
component also supports validation message customizing. The search for messages
is similar; the <em>formId</em> is the component id of the BeanEditForm
component (not the Form component it contains). The <em>fieldId</em> is the
property name.</p><h2
id="FormsandValidation-ConfiguringValidatorContraintsintheMessageCatalog">Configuring
Validator Contraints in the Message Catalog</h2><p>It is possible to omit the
validation constraint from the validate parameter (or @Validator annotation),
in which case it is expected to be stored in the message catalog.</p><p>This is
useful when the validation constraint is awkward to enter inline, such as a
regular expression for use with the regexp validator.</p><p>The key here is
similar to customizing the validation message:
<em>formId</em>-<em>fieldId</em>-<em>validatorName</em> or just
<em>fieldId</em>-<em>
validatorName</em>.</p><p>For example, your template may have the
following:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<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">
Modified: websites/production/tapestry/content/https.html
==============================================================================
--- websites/production/tapestry/content/https.html (original)
+++ websites/production/tapestry/content/https.html Sat Feb 3 16:21:22 2018
@@ -44,13 +44,26 @@
<div class="wrapper bs">
- <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div>
+ <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div>
+
+</div>
<div id="top">
- <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form
enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
- <input type="text" name="q">
- <input type="submit" value="Search">
-</form></div><div class="emblem" style="float:left"><p><a
href="index.html"><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div
class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">HTTPS</h1></div></div>
+ <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span>
+<form enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form>
+
+</div>
+
+
+<div class="emblem" style="float:left"><p><a href="index.html"><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div>
+
+
+<div class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">HTTPS</h1></div>
+
+</div>
<div class="clearer"></div>
</div>
@@ -62,25 +75,49 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h1
id="HTTPS-SecuringyourapplicationwithHTTPS">Securing your application with
HTTPS</h1><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="security-faq.html">Security 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="https.html">HTTPS</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="security.html">Security</a>
- </div> </li></ul></div><p>Tapestry assumes your application will be
primarily deployed as a standard web application, using HTTP (not HTTPS)
as the transport mechanism.</p><p>However, many applications will need to have
some of their pages secured: only accessible via HTTPS. This could be a login
page, or a product ordering wizard, or administrative pages.</p><p>All that is
necessary to mark a page as secure is to add the @Secure annotation to the page
class:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+ <div id="ConfluenceContent"><h1
id="HTTPS-SecuringyourapplicationwithHTTPS">Securing your application with
HTTPS</h1><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="security-faq.html">Security 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="https.html">HTTPS</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="security.html">Security</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p>Tapestry assumes your application will be primarily deployed as a standard
web application, using HTTP (not HTTPS) as the transport
mechanism.</p><p>However, many applications will need to have some of their
pages secured: only accessible via HTTPS. This could be a login page, or a
product ordering wizard, or administrative pages.</p><p>All that is necessary
to mark a page as secure is to add the @Secure annotation to the page
class:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Secure
public class ProcessOrder
{
@@ -117,7 +154,7 @@ public class ProcessOrder
configuration.add(BaseURLSource.class, source);
}
</pre>
-</div></div><p>This override is hardcoded to generate URLs for localhost; as
such you might use it for development but certainly not in production.</p><h2
id="HTTPS-DevelopmentMode">Development Mode</h2><p>When working in development
mode, the Secure annotation is ignored. This is controlled by the
tapestry.secure-enabled <a href="configuration.html">configuration
symbol</a>.</p><h2 id="HTTPS-ApplicationServerConfiguration">Application Server
Configuration</h2><p>Setting up HTTPS support varies from application server to
application server.</p><ul><li>Jetty:<ul><li><a class="external-link"
href="https://wiki.eclipse.org/Jetty/Howto/Configure_SSL";
rel="nofollow">Versions 7, 8 or 9</a></li></ul></li><li>Tomcat:<ul><li><a
class="external-link"
href="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html";>Version
6.0</a></li><li><a class="external-link"
href="http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html";>Version
5.5</a></li></ul></li></ul></div>
+</div></div><p>This override is hardcoded to generate URLs for localhost; as
such you might use it for development but certainly not in production.</p><h2
id="HTTPS-DevelopmentMode">Development Mode</h2><p>When working in development
mode, the Secure annotation is ignored. This is controlled by the
tapestry.secure-enabled <a href="https.html">configuration symbol</a>.</p><h2
id="HTTPS-ApplicationServerConfiguration">Application Server
Configuration</h2><p>Setting up HTTPS support varies from application server to
application server.</p><ul><li>Jetty:<ul><li><a class="external-link"
href="https://wiki.eclipse.org/Jetty/Howto/Configure_SSL";
rel="nofollow">Versions 7, 8 or 9</a></li></ul></li><li>Tomcat:<ul><li><a
class="external-link"
href="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html";>Version
6.0</a></li><li><a class="external-link"
href="http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html";>Version
5.5</a></li></ul></li></ul></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/injection.html
==============================================================================
--- websites/production/tapestry/content/injection.html (original)
+++ websites/production/tapestry/content/injection.html Sat Feb 3 16:21:22 2018
@@ -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,42 +77,84 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Injection</strong> is
Tapestry's way of making a dependency – such as a resource, asset,
component, block or service – available in a page, component, mixin or
service class.</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 = "injection" and space =
currentSpace()</parameter></rich-text-body><p>Injection is a key concept in
Tapestry, and it is used in several different but related ways.</p><h2
id="Injection-InjectioninTapestryIOCServices">Injection in Tapestry IOC
Services</h2><p>Main Article: <a href="tapestry-ioc-overview.html">Tapestry
IoC Overview</a></p><p>The Tapestry IoC container makes use of injection prima
rily through constructors and via parameters to service builder
methods.</p><h2 id="Injection-InjectioninComponentClasses">Injection in
Component Classes</h2><p>For components, however, Tapestry takes a completely
different tack: injection directly into component fields.</p><p>The @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation is used to identify fields that will contain injected services and
other resources.</p><p>Tapestry allows for two kinds of
injection:</p><ul><li><strong>Default injection</strong>, where Tapestry
determines the object to inject into the field based on its
type.</li><li><strong>Explicit injection</strong>, where the particular service
to be injected is specified.</li></ul><p>In both cases, the field is
transformed into a read only value. As elsewhere in Tapestry, this
transformation occurs at runtime (which is very important in terms of being
able to test your c
omponents). Attempting to update an injected field will result in a runtime
exception.</p><p>In addition, there are a few special cases that are triggered
by specific field types, or additional annotations, in addition, to @Inject, on
a field.</p><h3 id="Injection-BlockInjection">Block Injection</h3><p>For field
type <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html";>Block</a>,
the value of the Inject annotation is the id of the <a
href="component-templates.html"><t:block></a> element within the
component's template. Normally, the id of the block is determined from the
field name (after stripping out any leading "_" and "$"
characters):</p><parameter ac:name="">java</parameter><plain-text-body>@Inject
+ <div id="ConfluenceContent"><p><strong>Injection</strong> is
Tapestry's way of making a dependency – such as a resource, asset,
component, block or service – available in a page, component, mixin or
service class.</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="injection-in-detail.html">Injection in
Detail</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="injection-faq.html">Injection 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="injection.html">Injection</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p>Injection is a key concept in Tapestry, and it is used in several different
but related ways, listed below.</p><h2
id="Injection-InjectioninTapestryIOCServices">Injection in Tapestry IOC
Services</h2><p>Main Article: <a href="injection.html">Injection</a></p><p>The
Tapestry IoC container makes use of injection primarily through constructors
and via parameters to service builder methods.</p><h2
id="Injection-InjectioninComponentClasses">Injection in Component
Classes</h2><p>For components, however, Tapestry takes a completely different
tack: injection directly into component fields.</p><p>The @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation is used to identify fields that will contain injected services and
other resources.</p><p>Tapestry allows for two kinds of
injection:</p><ul><li><strong>Default injection</strong>, where Tapestry
determines the object to inject into the field bas
ed on its type.</li><li><strong>Explicit injection</strong>, where the
particular service to be injected is specified.</li></ul><p>In both cases, the
field is transformed into a read only value. As elsewhere in Tapestry, this
transformation occurs at runtime (which is very important in terms of being
able to test your components). Attempting to update an injected field will
result in a runtime exception.</p><p>In addition, there are a few special cases
that are triggered by specific field types, or additional annotations, in
addition, to @Inject, on a field.</p><h3 id="Injection-BlockInjection">Block
Injection</h3><p>For field type <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html";>Block</a>,
the value of the Inject annotation is the id of the <a
href="injection.html"><t:block></a> element within the component's
template. Normally, the id of the block is determined from the field name
(after stripping out any leading "_
" and "$" characters):</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;">@Inject
private Block foo;
-</plain-text-body><p>Where that is not appropriate, an @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html";>Id</a>
annotation can be supplied:</p><plain-text-body>@Inject
+</pre>
+</div></div><p>Where that is not appropriate, an @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html";>Id</a>
annotation can be supplied:</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;">@Inject
@Id("bar")
private Block barBlock;
-</plain-text-body><p>The first injection will inject the Block with id "foo"
(as always, case is ignored). The second injection will inject the Block with
id "bar".</p><h3 id="Injection-ResourceInjection">Resource Injection</h3><p>For
a particular set of field types, Tapestry will inject a <em>resource</em>
related to the component, such as its Locale.</p><p>A very common example
occurs when a component needs access to its <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>resources</a>.
The component can define a field of the appropriate type and use the
<code>@Inject</code> annotation without a value:</p><parameter
ac:name="">java</parameter><plain-text-body>@Inject
+</pre>
+</div></div><p>The first injection will inject the Block with id "foo" (as
always, case is ignored). The second injection will inject the Block with id
"bar".</p><h3 id="Injection-ResourceInjection">Resource Injection</h3><p>For a
particular set of field types, Tapestry will inject a <em>resource</em> related
to the component, such as its Locale.</p><p>A very common example occurs when a
component needs access to its <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>resources</a>.
The component can define a field of the appropriate type and use the
<code>@Inject</code> annotation without a value:</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;">@Inject
private ComponentResources resources;
-</plain-text-body><p>Tapestry uses the type of the field, ComponentResources,
to determine what to inject into this field.</p><p>The following types are
supported for resources injection:</p><ul><li><strong>java.lang.String</strong>
– The complete id of the component, which incorporates the complete class
name of the containing page and the nested id of the component within the
page.</li></ul><ul><li><strong>java.util.Locale</strong> – The locale for
the component (all components within a page use the same
locale).</li></ul><ul><li><strong>org.slf4j.Logger</strong> – A Logger
instance configured for the component, based on the component's class name. <a
class="external-link" href="http://www.slf4j.org/"; rel="nofollow">SLF4J</a> is
a wrapper around Log4J or other logging
toolkits.</li></ul><ul><li><strong>org.apache.tapestry5.ComponentResources</strong>
– The resources for the component, often used to generate links related
to the component.</li></ul><ul><li>
<strong>org.apache.tapestry5.ioc.Messages</strong> – The component
message catalog for the component, from which <a
href="injection.html">localized</a> messages can be generated.</li></ul><h3
id="Injection-AssetInjection">Asset Injection</h3><p>Main Article: <a
href="assets.html">Assets</a></p><p>When the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html";>Path</a>
annotation is also present, then the injected value (relative to the
component) will be a localized asset.</p><parameter
ac:name="">java</parameter><plain-text-body>@Inject
+</pre>
+</div></div><p>Tapestry uses the type of the field, ComponentResources, to
determine what to inject into this field.</p><p>The following types are
supported for resources injection:</p><ul><li><strong>java.lang.String</strong>
– The complete id of the component, which incorporates the complete class
name of the containing page and the nested id of the component within the
page.</li></ul><ul><li><strong>java.util.Locale</strong> – The locale for
the component (all components within a page use the same
locale).</li></ul><ul><li><strong>org.slf4j.Logger</strong> – A Logger
instance configured for the component, based on the component's class name. <a
class="external-link" href="http://www.slf4j.org/"; rel="nofollow">SLF4J</a> is
a wrapper around Log4J or other logging
toolkits.</li></ul><ul><li><strong>org.apache.tapestry5.ComponentResources</strong>
– The resources for the component, often used to generate links related
to the component.</li></ul><ul><li><stron
g>org.apache.tapestry5.ioc.Messages</strong> – The component message
catalog for the component, from which <a href="injection.html">localized</a>
messages can be generated.</li></ul><h3 id="Injection-AssetInjection">Asset
Injection</h3><p>Main Article: <a
href="injection.html">Injection</a></p><p>When the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html";>Path</a>
annotation is also present, then the injected value (relative to the
component) will be a localized asset.</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;">@Inject
@Path("context:images/top_banner.png")
private Asset banner;
-</plain-text-body><p>Symbols in the annotation value are expanded.</p><h3
id="Injection-ServiceInjection">Service Injection</h3><p>Here, a custom
EmployeeService service is injected, but any custom or built-in service may be
injected in the same way.</p><parameter
ac:name="">java</parameter><plain-text-body>@Inject
+</pre>
+</div></div><p>Symbols in the annotation value are expanded.</p><h3
id="Injection-ServiceInjection">Service Injection</h3><p>Here, a custom
EmployeeService service is injected, but any custom or built-in service may be
injected in the same way.</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;">@Inject
private EmployeeService employeeService;
-</plain-text-body><p>A large number of services are provided by Tapestry. See
the following packages:<plain-text-body>{float:left|width=15em}
-* [Core
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/package-summary.html]
-* [AJAX
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ajax/package-summary.html]
-* [Assets
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/assets/package-summary.html]
-* [Dynamic Component
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/dynamic/package-summary.html]
-{float}</plain-text-body><plain-text-body>{float:left|width=15em}
-* [JavaScript
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/package-summary.html]
-* [Link Transformation
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/linktransform/package-summary.html]
-* [Message
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/messages/package-summary.html]
-* [Component Metadata
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/package-summary.html]
-{float}</plain-text-body><plain-text-body>{float:left|width=15em}
-* [Page Loading
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/pageload/package-summary.html]
-* [Security
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/security/package-summary.html]
-* [Template
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/templates/package-summary.html]
-* [Class Transformation
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/transform/package-summary.html]
-{float}</plain-text-body><plain-text-body>{float:left|width=15em}
-* [Tapestry IOC
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/package-summary.html]
-* [Tapestry IOC Cron
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/cron/package-summary.html]
-* [Kaptcha
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/kaptcha/services/package-summary.html]
-* [File Upload
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/upload/services/package-summary.html]
-{float}</plain-text-body><parameter
ac:name="atlassian-macro-output-type">INLINE</parameter><plain-text-body><div
style="clear:both"></div></plain-text-body> </p><h3
id="Injection-ExplicitServiceInjection">Explicit Service Injection</h3><p>Here,
a specific object is requested. A @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html";>Service</a>
annotation is used to identify the service name.</p><parameter
ac:name="">java</parameter><plain-text-body>@Inject
+</pre>
+</div></div><p>A large number of services are provided by Tapestry. See the
following packages:</p><div class="navmenu" style="float:left; width:15em;
background:white; margin:3px; padding:3px">
+<ul><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/package-summary.html";>Core
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ajax/package-summary.html";>AJAX
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/assets/package-summary.html";>Assets
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/dynamic/package-summary.html";>Dynamic
Component Services</a></li></ul>
+</div><div class="navmenu" style="float:left; width:15em; background:white;
margin:3px; padding:3px">
+<ul><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/package-summary.html";>JavaScript
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/linktransform/package-summary.html";>Link
Transformation Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/messages/package-summary.html";>Message
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/package-summary.html";>Component
Metadata Services</a></li></ul>
+</div><div class="navmenu" style="float:left; width:15em; background:white;
margin:3px; padding:3px">
+<ul><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/pageload/package-summary.html";>Page
Loading Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/security/package-summary.html";>Security
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/templates/package-summary.html";>Template
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/transform/package-summary.html";>Class
Transformation Services</a></li></ul>
+</div><div class="navmenu" style="float:left; width:15em; background:white;
margin:3px; padding:3px">
+<ul><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/package-summary.html";>Tapestry
IOC Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/cron/package-summary.html";>Tapestry
IOC Cron Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/kaptcha/services/package-summary.html";>Kaptcha
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/upload/services/package-summary.html";>File
Upload Services</a></li></ul>
+</div><div style="clear:both"></div> <h3
id="Injection-ExplicitServiceInjection">Explicit Service Injection</h3><p>Here,
a specific object is requested. A @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html";>Service</a>
annotation is used to identify the service name.</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;">@Inject
@Service("Request")
private Request request;
-</plain-text-body><p>This is generally not necessary; you should always be
able to identify the service to be injected just by type, not by explicit id.
Explicit ids have the disadvantage of not being refactoring-safe: this won't
happen with the Request service, but perhaps in your own code ... if you rename
the service interface and rename the service id to match, your existing
injections using the explicit service id will break.</p><h2
id="Injection-DefaultInjection">Default Injection</h2><p>When the type and/or
other annotations are not sufficient to identify the object or service to
inject, Tapestry falls back on two remaining steps. It assumes that the field
type will be used to identify a service, by the service interface.</p><p>First,
the object provider created by the Alias service is consulted. This object
provider is used to disambiguate injections when there is more than one service
that implements the same service interface.</p><p>Second, a search for a unique
service th
at implements the interface occurs. This will fail if either there are no
services that implement the interface, or there is more than one. In the latter
case, you must disambiguate, either with a contribution to the Alias service,
or by explicitly identifying the service with the @Service annotation.</p><h2
id="Injection-DefiningNewInjectionLogic">Defining New Injection
Logic</h2><p>Anonymous injection is controlled by the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html";>InjectionProvider</a>
service. The configuration for this service is a <a
href="chainbuilder-service.html">chain of command</a> for handling component
injections.</p></div>
+</pre>
+</div></div><p>This is generally not necessary; you should always be able to
identify the service to be injected just by type, not by explicit id. Explicit
ids have the disadvantage of not being refactoring-safe: this won't happen with
the Request service, but perhaps in your own code ... if you rename the service
interface and rename the service id to match, your existing injections using
the explicit service id will break.</p><h2
id="Injection-DefaultInjection">Default Injection</h2><p>When the type and/or
other annotations are not sufficient to identify the object or service to
inject, Tapestry falls back on two remaining steps. It assumes that the field
type will be used to identify a service, by the service interface.</p><p>First,
the object provider created by the Alias service is consulted. This object
provider is used to disambiguate injections when there is more than one service
that implements the same service interface.</p><p>Second, a search for a unique
service that imp
lements the interface occurs. This will fail if either there are no services
that implement the interface, or there is more than one. In the latter case,
you must disambiguate, either with a contribution to the Alias service, or by
explicitly identifying the service with the @Service annotation.</p><h2
id="Injection-DefiningNewInjectionLogic">Defining New Injection
Logic</h2><p>Anonymous injection is controlled by the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html";>InjectionProvider</a>
service. The configuration for this service is a <a
href="injection.html">chain of command</a> for handling component
injections.</p></div>
</div>
<div class="clearer"></div>
![https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2"](https://cwiki-test.apache.org/confluence/download/attachments/22872109/newapp_com_example.png?version=3&modificationDate=1428088849000&api=v2"){kind=link}
![http://tapestry.apache.org/images/tapestry_small.png"](http://tapestry.apache.org/images/tapestry_small.png"){kind=link}