Author: buildbot
Date: Tue Feb 17 17:19:28 2015
New Revision: 940492
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/persistent-page-data.html
websites/production/tapestry/content/uploading-files.html
websites/production/tapestry/content/using-select-with-a-list.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/persistent-page-data.html
==============================================================================
--- websites/production/tapestry/content/persistent-page-data.html (original)
+++ websites/production/tapestry/content/persistent-page-data.html Tue Feb 17
17:19:28 2015
@@ -67,14 +67,20 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><div class="navmenu" style="float:right;
background:#eee; margin:3px; padding:3px">
+<div id="ConfluenceContent"><p> </p><h1
id="PersistentPageData-PersistentPageData">Persistent Page Data</h1> <div
class="aui-message hint shadowed information-macro">
+ <span class="aui-icon icon-hint">Icon</span>
+ <div class="message-content">
+ <p>The use of the term "persistence" here refers
to <em>page-level</em> persistence, NOT database persistence.</p>
+ </div>
+ </div>
+<p>Most instance variables in Tapestry are automatically cleared at the end of
each request. This is important, as it pertains to how Tapestry pages are
shared, over time, by many users.</p><div class="navmenu" style="float:right;
background:#eee; margin:3px; padding:3px">
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
<span class="icon icon-page" title="Page">Page:</span>
</div>
<div class="details">
- <a shape="rect"
href="persistent-page-data.html">Persistent Page Data</a>
+ <a shape="rect"
href="performance-and-clustering.html">Performance and Clustering</a>
</div>
@@ -83,7 +89,7 @@
<span class="icon icon-page" title="Page">Page:</span>
</div>
<div class="details">
- <a shape="rect"
href="performance-and-clustering.html">Performance and Clustering</a>
+ <a shape="rect"
href="session-storage.html">Session Storage</a>
</div>
@@ -92,22 +98,19 @@
<span class="icon icon-page" title="Page">Page:</span>
</div>
<div class="details">
- <a shape="rect"
href="session-storage.html">Session Storage</a>
+ <a shape="rect"
href="persistent-page-data.html">Persistent Page Data</a>
</div>
</li></ul>
-</div><h1 id="PersistentPageData-PersistentPageData">Persistent Page Data</h1>
<div class="aui-message hint shadowed information-macro">
- <span class="aui-icon icon-hint">Icon</span>
- <div class="message-content">
- <p>The use of the term "persistence" here refers
to <em>page-level</em> persistence, NOT database persistence.</p>
- </div>
- </div>
-<p>Most instance variables in Tapestry are automatically cleared at the end of
each request. This is important, as it pertains to how Tapestry pages are
shared, over time, by many users.</p><p>However, you often want to store some
data on a <em>single</em> page, and have access to it in later requests to that
same page, without having to store it in a database between requests. (To store
values across multiple pages, see <a shape="rect"
href="session-storage.html">Session Storage</a>.)</p><p>Making page data
persist across requests to a single page is accomplished with the @<a
shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Persist.html";>Persist</a>
annotation. This annotation is applied to private instance fields of
components:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div><p>However, you often want to store some data on a <em>single</em> page,
and have access to it in later requests to that same page, without having to
store it in a database between requests. (To store values across multiple
pages, see <a shape="rect" href="session-storage.html">Session
Storage</a>.)</p><p>Making page data persist across requests to a single page
is accomplished with the @<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Persist.html";>Persist</a>
annotation. This annotation is applied to private instance fields of
components:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ @Persist
private int value;
]]></script>
-</div></div><p>Such annotated fields will retain their state between requests.
Generally, speaking, this means that the value is stored into the session (but
other approaches are possible).</p><p>Whenever you make a change to a
persistent field, its value is saved. On later requests to the same page, the
value for the field is restored.</p><h2
id="PersistentPageData-PersistenceStrategies">Persistence Strategies</h2><p>The
value for each field is the <em>strategy</em> used to store the field between
requests.</p><h3 id="PersistentPageData-SessionStrategy">Session
Strategy</h3><p>The session strategy stores field changes into the session; the
session is created as necessary.</p><p>A suitably long session attribute name
is used; it incorporates the name of the page, the nested component id, and the
name of the field.</p><p>Session strategy is the default strategy used unless
otherwise overridden.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHead
er pdl" style="border-bottom-width: 1px;"><b>Example: Session
Strategy</b></div><div class="codeContent panelContent pdl">
+</div></div><p>Such annotated fields will retain their state between requests.
Generally, speaking, this means that the value is stored into the session (but
other approaches are possible).</p><p>Whenever you make a change to a
persistent field, its value is saved. On later requests to the same page, the
value for the field is restored.</p><h2
id="PersistentPageData-PersistenceStrategies">Persistence Strategies</h2><p>The
value for each field is the <em>strategy</em> used to store the field between
requests.</p><h3 id="PersistentPageData-SessionStrategy">Session
Strategy</h3><div class="navmenu" style="float:right; background:#eee;
margin:3px; padding:0 1em">
+<p> <strong>JumpStart Demo:</strong><br clear="none">
+ <a shape="rect" class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/state/storingdatainapage";
>Storing Data in a Page</a><br clear="none">
+ <a shape="rect" class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/state/passingdatabetweenpages";
>Passing Data Between Pages</a></p></div><p>The session strategy stores field
changes into the session; the session is created as necessary. Session strategy
is the default strategy used unless otherwise overridden.</p><p>A suitably long
session attribute name is used; it incorporates the name of the page, the
nested component id, and the name of the field.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Example: Session Strategy</b></div><div
class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ @Persist
private int value;
]]></script>
Modified: websites/production/tapestry/content/uploading-files.html
==============================================================================
--- websites/production/tapestry/content/uploading-files.html (original)
+++ websites/production/tapestry/content/uploading-files.html Tue Feb 17
17:19:28 2015
@@ -32,6 +32,7 @@
<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 type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -73,7 +74,9 @@
<version>${tapestry-release-version}</version>
</dependency>
]]></script>
-</div></div><p>If you aren't using Maven, you'll have to download the jar and
its dependencies yourself.</p><h1 id="UploadingFiles-Usage">Usage</h1><p>The
upload component supports default value binding (based on id) and
validation.</p><h2 id="UploadingFiles-ComponentTemplate">Component
Template</h2><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div></div><p>If you aren't using Maven, you'll have to download the jar and
its dependencies yourself.</p><h1 id="UploadingFiles-Usage">Usage</h1><p>The
upload component supports default value binding (based on id) and
validation.</p><div class="navmenu" style="float:right; background:#eee;
margin:3px; padding:0 1em">
+<p> <strong>JumpStart Demo:</strong><br clear="none">
+ <a shape="rect" class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/javascript/fileupload";
>File Upload</a></p></div><h2 id="UploadingFiles-ComponentTemplate">Component
Template</h2><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ <t:form>
<t:errors/>
<input t:type="upload" t:id="file"
t:value="file" validate="required"/>
Modified: websites/production/tapestry/content/using-select-with-a-list.html
==============================================================================
--- websites/production/tapestry/content/using-select-with-a-list.html
(original)
+++ websites/production/tapestry/content/using-select-with-a-list.html Tue Feb
17 17:19:28 2015
@@ -75,36 +75,15 @@ table.ScrollbarTable td.ScrollbarParent
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width:
16px;border: none;}
-/*]]>*/</style><div class="Scrollbar"><table class="ScrollbarTable"><tr><td
colspan="1" rowspan="1" class="ScrollbarPrevIcon"><a shape="rect"
href="meta-programming-page-content.html"><img align="middle" border="0"
src="https://cwiki.apache.org/confluence/images/icons/back_16.gif"; width="16"
height="16"></a></td><td colspan="1" rowspan="1" class="ScrollbarPrevName"
width="33%"><a shape="rect"
href="meta-programming-page-content.html">Meta-Programming Page
Content</a> </td><td colspan="1" rowspan="1" class="ScrollbarParent"
width="33%"><sup><a shape="rect" href="cookbook.html"><img align="middle"
border="0" src="https://cwiki.apache.org/confluence/images/icons/up_16.gif";
width="8" height="8"></a></sup><a shape="rect"
href="cookbook.html">Cookbook</a></td><td colspan="1" rowspan="1"
class="ScrollbarNextName" width="33%"> <a shape="rect"
href="ioc-cookbook.html">IoC cookbook</a></td><td colspan="1" rowspan="1"
class="ScrollbarNextIcon"><a shape="rect" href="ioc-cookbook.html"
><img align="middle" border="0"
>src="https://cwiki.apache.org/confluence/images/icons/forwd_16.gif";
>width="16" height="16"></a></td></tr></table></div>
-<p></p>
-
-<h1 id="UsingSelectWithaList-UsingSelectWithaList">Using Select With a
List</h1>
-
-<p>The documentation for the <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Select.html";>Select
Component</a> and the <a shape="rect" href="tutorial.html">Tapestry
Tutorial</a> provide simplistic examples of populating a drop-down menu (as the
(X)HTML <em>Select</em> element) using comma-delimited strings and enums.
However, most real-world Tapestry applications need to populate such menus
using values from a database, commonly in the form of java.util.List objects.
Doing so generally requires a <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/SelectModel.html";>SelectModel</a>
and a <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValueEncoder.html";>ValueEncoder</a>
bound to the Select component with its "model" and "encoder" parameters:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-<t:select t:id="colorMenu" value="selectedColor"
model="ColorSelectModel" encoder="colorEncoder" />
+/*]]>*/</style><div class="Scrollbar"><table class="ScrollbarTable"><tr><td
colspan="1" rowspan="1" class="ScrollbarPrevIcon"><a shape="rect"
href="meta-programming-page-content.html"><img align="middle" border="0"
src="https://cwiki.apache.org/confluence/images/icons/back_16.gif"; width="16"
height="16"></a></td><td colspan="1" rowspan="1" class="ScrollbarPrevName"
width="33%"><a shape="rect"
href="meta-programming-page-content.html">Meta-Programming Page
Content</a> </td><td colspan="1" rowspan="1" class="ScrollbarParent"
width="33%"><sup><a shape="rect" href="cookbook.html"><img align="middle"
border="0" src="https://cwiki.apache.org/confluence/images/icons/up_16.gif";
width="8" height="8"></a></sup><a shape="rect"
href="cookbook.html">Cookbook</a></td><td colspan="1" rowspan="1"
class="ScrollbarNextName" width="33%"> <a shape="rect"
href="ioc-cookbook.html">IoC cookbook</a></td><td colspan="1" rowspan="1"
class="ScrollbarNextIcon"><a shape="rect" href="ioc-cookbook.html"
><img align="middle" border="0"
>src="https://cwiki.apache.org/confluence/images/icons/forwd_16.gif";
>width="16" height="16"></a></td></tr></table></div><h1
>id="UsingSelectWithaList-UsingSelectWithaList">Using Select With a
>List</h1><p>The documentation for the <a shape="rect" class="external-link"
>href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Select.html";>Select
> Component</a> and the <a shape="rect" href="tutorial.html">Tapestry
>Tutorial</a> provide simplistic examples of populating a drop-down menu (as
>the (X)HTML <em>Select</em> element) using comma-delimited strings and enums.
>However, most real-world Tapestry applications need to populate such menus
>using values from a database, commonly in the form of java.util.List objects.
>Doing so generally requires a <a shape="rect" class="external-link"
>href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/SelectModel.html";>SelectModel</a>
> and a <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValueEncoder.html";>ValueEncoder</a>
bound to the Select component with its "model" and "encoder"
parameters:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[<t:select t:id="colorMenu"
value="selectedColor" model="ColorSelectModel"
encoder="colorEncoder" />
]]></script>
-</div></div>
-
-<p>In the above example, ColorSelectModel must be of type SelectModel, or
anything that Tapestry knows how to <a shape="rect"
href="parameter-type-coercion.html">coerce</a> into a SelectModel, such as a
List or a Map or a "value=label,value=label,..." delimited string, or anything
Tapestry knows how to coerce into a List or Map, such as an Array or a
comma-delimited String.</p>
-
-<h2 id="UsingSelectWithaList-SelectModel">SelectModel</h2>
-
-<p>A SelectModel is a collection of options (specifically <a shape="rect"
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/OptionModel.html";>OptionModel</a>
objects) for a drop-down menu. Basically, each option is a value (an object)
and a label (presented to the user).</p>
-
-<p>If you provide a property of type List for the "model" parameter, Tapestry
automatically builds a SelectModel that uses each object's toString() for both
the select option value and the select option label. For database-derrived
lists this is rarely useful, however, since after form submission you would
then have to look up the selected object using that label.</p>
-
-<p>If you provide a Map, Tapestry builds a SelectModel that uses each item's
key as the encoded value and its value as the user-visible label. This is more
useful, but if you are going to build a copy of the list as a map just for this
purpose, you may as well let Tapestry do it for you, using
SelectModelFactory.</p>
-
-<h2 id="UsingSelectWithaList-SelectModelFactory">SelectModelFactory</h2>
-
-<p>To have Tapestry create a SelectModel for you, use the <a shape="rect"
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/SelectModelFactory.html";>SelectModelFactory</a>
service. SelectModelFactory creates a SelectModel from a List of objects (of
whatever type) and a label property name that you choose:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>SelectWithListDemo.java
(a page class)</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-@Property
+</div></div><p>In the above example, ColorSelectModel must be of type
SelectModel, or anything that Tapestry knows how to <a shape="rect"
href="parameter-type-coercion.html">coerce</a> into a SelectModel, such as a
List or a Map or a "value=label,value=label,..." delimited string, or anything
Tapestry knows how to coerce into a List or Map, such as an Array or a
comma-delimited String.</p><h2
id="UsingSelectWithaList-SelectModel">SelectModel</h2><div class="navmenu"
style="float:right; background:#eee; margin:3px; padding:0 1em">
+<p> <strong>JumpStart Demos:</strong><br clear="none">
+ <a shape="rect" class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/select/totalcontrolobject";
>Total Control Object Select</a><br clear="none">
+ <a shape="rect" class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/select/id"; >ID
Select</a><br clear="none">
+ <a shape="rect" class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/select/easyid";
>Easy ID Select</a></p></div><p>A SelectModel is a collection of options
(specifically <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/OptionModel.html";>OptionModel</a>
objects) for a drop-down menu. Basically, each option is a value (an object)
and a label (presented to the user).</p><p>If you provide a property of type
List for the "model" parameter, Tapestry automatically builds a SelectModel
that uses each object's toString() for both the select option value and the
select option label. For database-derrived lists this is rarely useful,
however, since after form submission you would then have to look up the
selected object using that label.</p><p>If you provide a Map, Tapestry builds a
SelectModel that uses each item's key as the encoded value and its value as the
user-visible label. This is more usef
ul, but if you are going to build a copy of the list as a map just for this
purpose, you may as well let Tapestry do it for you, using
SelectModelFactory.</p><h2
id="UsingSelectWithaList-SelectModelFactory">SelectModelFactory</h2><p>To have
Tapestry create a SelectModel for you, use the <a shape="rect"
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/SelectModelFactory.html";>SelectModelFactory</a>
service. SelectModelFactory creates a SelectModel from a List of objects (of
whatever type) and a label property name that you choose:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>SelectWithListDemo.java (a page
class)</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[@Property
private SelectModel colorSelectModel;
@Inject
SelectModelFactory selectModelFactory;
@@ -117,39 +96,17 @@ void setupRender() {
colorSelectModel = selectModelFactory.create(colors, "name");
}
]]></script>
-</div></div>
-
-<p>The resulting SelectModel has a selectable option (specifically, an
OptionModel) for every object in the original List. The label property name
(the "name" property, in this example) determines the user-visible text of each
menu option, and your ValueEncoder's toClient() method provides the encoded
value (most commonly a simple number). If you don't provide a ValueEncoder, the
result of the objects' toString() method (Color#toString() in this example) is
used. Although not a recommended practice, you <em>could</em> set your
toString() to return the object's ID for this purpose:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Color.java
(partial)</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-...
+</div></div><p>The resulting SelectModel has a selectable option
(specifically, an OptionModel) for every object in the original List. The label
property name (the "name" property, in this example) determines the
user-visible text of each menu option, and your ValueEncoder's toClient()
method provides the encoded value (most commonly a simple number). If you don't
provide a ValueEncoder, the result of the objects' toString() method
(Color#toString() in this example) is used. Although not a recommended
practice, you <em>could</em> set your toString() to return the object's ID for
this purpose:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Color.java (partial)</b></div><div class="codeContent panelContent
pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[...
@Override
public String toString() {
return String.valueOf(this.getId());
}
]]></script>
-</div></div>
-
-<p>But that is contorting the purpose of the toString() method, and if you go
to that much trouble you're already half way to the recommended practice:
creating a ValueEncoder.</p>
-
-<h2 id="UsingSelectWithaList-ValueEncoder">ValueEncoder</h2>
-
-<p>In addition to a SelectModel, your Select menu is likely to need a
ValueEncoder. While a SelectModel is concerned only with how to construct a
Select menu, a ValueEncoder is used when constructing the Select menu
<em>and</em> when interpreting the encoded value that is submitted back to the
server. A ValueEncoder is a converter between the type of objects you want to
represent as options in the menu and the client-side encoded values that
uniquely identify them, and vice-versa.</p>
-
-<div class="navmenu" style="float:right; background:#eee; margin:3px;
padding:0 1em">
+</div></div><p>But that is contorting the purpose of the toString() method,
and if you go to that much trouble you're already half way to the recommended
practice: creating a ValueEncoder.</p><h2
id="UsingSelectWithaList-ValueEncoder">ValueEncoder</h2><p>In addition to a
SelectModel, your Select menu is likely to need a ValueEncoder. While a
SelectModel is concerned only with how to construct a Select menu, a
ValueEncoder is used when constructing the Select menu <em>and</em> when
interpreting the encoded value that is submitted back to the server. A
ValueEncoder is a converter between the type of objects you want to represent
as options in the menu and the client-side encoded values that uniquely
identify them, and vice-versa.</p><div class="navmenu" style="float:right;
background:#eee; margin:3px; padding:0 1em">
<p> <strong>JumpStart Demo:</strong><br clear="none">
- <a shape="rect" class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/select/easyobject";
>Easy Object Select</a></p></div>
-
-<p>Most commonly, your ValueEncoder's toClient() method will return a unique
ID (e.g. a database primary key, or perhaps a UUID) of the given object, and
its toValue() method will return the <em>object</em> matching the given ID by
doing a database lookup (ideally using a service or DAO method).</p>
-
-<p>If you're using one of the ORM integration modules (<a shape="rect"
href="hibernate.html">Tapestry-Hibernate</a>, <a shape="rect"
href="integrating-with-jpa.html">Tapestry-JPA</a>, or <a shape="rect"
class="external-link"
href="http://code.google.com/p/tapestry5-cayenne/wiki/ValueEncoder";
>Tapestry-Cayenne</a>), the ValueEncoder is automatically provided for each of
your mapped entity classes. The Hibernate module's implementation is typical:
the primary key field of the object (converted to a String) is used as the
client-side value, and that same primary key is used to look up the selected
object. </p>
-
-<p>That's exactly what you should do in your own ValueEncoders too:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>ColorEncoder.java
(perhaps in your com.example.myappname.encoders package)</b></div><div
class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-public class ColorEncoder implements ValueEncoder<Color>,
ValueEncoderFactory<Color> {
+ <a shape="rect" class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/select/easyobject";
>Easy Object Select</a></p></div><p>Most commonly, your ValueEncoder's
toClient() method will return a unique ID (e.g. a database primary key, or
perhaps a UUID) of the given object, and its toValue() method will return the
<em>object</em> matching the given ID by doing a database lookup (ideally using
a service or DAO method).</p><p>If you're using one of the ORM integration
modules (<a shape="rect" href="hibernate.html">Tapestry-Hibernate</a>, <a
shape="rect" href="integrating-with-jpa.html">Tapestry-JPA</a>, or <a
shape="rect" class="external-link"
href="http://code.google.com/p/tapestry5-cayenne/wiki/ValueEncoder";
>Tapestry-Cayenne</a>), the ValueEncoder is automatically provided for each of
your mapped entity classes. The Hibernate module's implementation is typical:
the primary key field of the object (converted to a String) is used as the
client-side va
lue, and that same primary key is used to look up the selected
object.</p><p>That's exactly what you should do in your own ValueEncoders
too:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>ColorEncoder.java (perhaps in your com.example.myappname.encoders
package)</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[public class ColorEncoder implements
ValueEncoder<Color>, ValueEncoderFactory<Color> {
@Inject
private ColorService colorService;
@@ -173,13 +130,8 @@ public class ColorEncoder implements Val
}
}
]]></script>
-</div></div>
-
-<p>Alternatively, if you don't expect to need a particular ValueEncoder more
than once in your app, you might want to just create it on demand, using an
anonymous inner class, from the getter method in the component class where it
is needed. For example:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>SelectWithListDemo.java
(a page class, partial)</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
- . . .
+</div></div><p>Alternatively, if you don't expect to need a particular
ValueEncoder more than once in your app, you might want to just create it on
demand, using an anonymous inner class, from the getter method in the component
class where it is needed. For example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>SelectWithListDemo.java (a page class,
partial)</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ . . .
public ValueEncoder<Color> getColorEncoder() {
@@ -199,29 +151,15 @@ public class ColorEncoder implements Val
};
}
]]></script>
-</div></div>
-
-<p>Notice that the body of this anonymous inner class is the same as the body
of the ColorEncoder top level class, except that we don't need a
<code>create</code> method.</p>
-
-<h2 id="UsingSelectWithaList-ApplyingyourValueEncoderAutomatically">Applying
your ValueEncoder Automatically</h2>
-
-<p>If your ValueEncoder <em>implements ValueEncoderFactory</em> (as the
ColorEncoder top level class does, above), you can associate your custom
ValueEncoder with your entity class so that Tapestry will automatically use it
every time a ValueEncoder is needed for items of that type (such as with the
Select, RadioGroup, Grid, Hidden and AjaxFormLoop components). Just add lines
like the following to your module class (usually AppModule.java):</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>AppModule.java
(partial)</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-...
+</div></div><p>Notice that the body of this anonymous inner class is the same
as the body of the ColorEncoder top level class, except that we don't need a
<code>create</code> method.</p><h2
id="UsingSelectWithaList-ApplyingyourValueEncoderAutomatically">Applying your
ValueEncoder Automatically</h2><p>If your ValueEncoder <em>implements
ValueEncoderFactory</em> (as the ColorEncoder top level class does, above), you
can associate your custom ValueEncoder with your entity class so that Tapestry
will automatically use it every time a ValueEncoder is needed for items of that
type (such as with the Select, RadioGroup, Grid, Hidden and AjaxFormLoop
components). Just add lines like the following to your module class (usually
AppModule.java):</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>AppModule.java (partial)</b></div><div class="codeContent panelContent
pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[...
public static void
contributeValueEncoderSource(MappedConfiguration<Class<Color>,
ValueEncoderFactory<Color>> configuration) {
configuration.addInstance(Color.class, ColorEncoder.class);
}
]]></script>
-</div></div>
-
-<p>If you are contributing more than one ValueEncoder, you'll have to use raw
types, like this:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>AppModule.java
(partial)</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-...
+</div></div><p>If you are contributing more than one ValueEncoder, you'll have
to use raw types, like this:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>AppModule.java (partial)</b></div><div
class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[...
public static void
contributeValueEncoderSource(MappedConfiguration<Class,
ValueEncoderFactory> configuration)
{
@@ -229,34 +167,18 @@ public class ColorEncoder implements Val
configuration.addInstance(SomeOtherType.class,
SomeOtherTypeEncoder.class);
}
]]></script>
-</div></div>
-
-
-<h2 id="UsingSelectWithaList-WhatifIomittheValueEncoder?">What if I omit the
ValueEncoder?</h2>
-
-<p>The Select component's "encoder" parameter is optional, but if the "value"
parameter is bound to a complex object (not a simple String, Integer, etc.) and
you don't provide a ValueEncoder with the "encoder" parameter (and one isn't
provided automatically by, for example, the Tapestry Hibernate integration),
you'll receive a "Could not find a coercion" exception (when you submit the
form) as Tapestry tries to convert the selected option's encoded value back to
the <em>object</em> in your Select's "value" parameter. To fix this, you'll
either have to 1) provide a ValueEncoder, 2) provide a <a shape="rect"
href="type-coercion.html">Coercion</a>, or 3) use a simple value (String,
Integer, etc.) for your Select's "value" parameter, and then you'll have to add
logic in the corresponding onSuccess event listener method:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>SelectWithListDemo.tml
(partial)</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-<t:select t:id="colorMenu" value="selectedColorId"
model="ColorSelectModel" />
+</div></div><h2 id="UsingSelectWithaList-WhatifIomittheValueEncoder?">What if
I omit the ValueEncoder?</h2><p>The Select component's "encoder" parameter is
optional, but if the "value" parameter is bound to a complex object (not a
simple String, Integer, etc.) and you don't provide a ValueEncoder with the
"encoder" parameter (and one isn't provided automatically by, for example, the
Tapestry Hibernate integration), you'll receive a "Could not find a coercion"
exception (when you submit the form) as Tapestry tries to convert the selected
option's encoded value back to the <em>object</em> in your Select's "value"
parameter. To fix this, you'll either have to 1) provide a ValueEncoder, 2)
provide a <a shape="rect" href="type-coercion.html">Coercion</a>, or 3) use a
simple value (String, Integer, etc.) for your Select's "value" parameter, and
then you'll have to add logic in the corresponding onSuccess event listener
method:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>SelectWithListDemo.tml (partial)</b></div><div class="codeContent
panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[<t:select t:id="colorMenu"
value="selectedColorId" model="ColorSelectModel" />
]]></script>
-</div></div>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>SelectWithListDemo.java
(partial)</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-...
+</div></div><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>SelectWithListDemo.java (partial)</b></div><div class="codeContent
panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[...
public void onSuccessFromMyForm() {
// look up the color object from the ID selected
selectedColor = colorService.findById(selectedColorId);
...
}
]]></script>
-</div></div>
-
-<p>But then again, you may as well create a ValueEncoder instead.</p>
-
-<h2 id="UsingSelectWithaList-Whyisthissohard?">Why is this so hard?</h2>
-
-<p>Actually, it's really pretty easy if you follow the examples above. But why
is Tapestry designed to use SelectModels and ValueEncoders anyway? Well, in
short, this design allows you to avoid storing (via @Persist, @SessionAttribute
or @SessionState) the entire (potentially large) list of objects in the session
or rebuilding the whole list of objects again (though only one is needed) when
the form is submitted. The chief benefits are reduced memory use and <a
shape="rect" href="performance-and-clustering.html">more scalable
clustering</a> due to having far less HTTP session data to replicate across the
nodes of a cluster.</p></div>
+</div></div><p>But then again, you may as well create a ValueEncoder
instead.</p><h2 id="UsingSelectWithaList-Whyisthissohard?">Why is this so
hard?</h2><p>Actually, it's really pretty easy if you follow the examples
above. But why is Tapestry designed to use SelectModels and ValueEncoders
anyway? Well, in short, this design allows you to avoid storing (via @Persist,
@SessionAttribute or @SessionState) the entire (potentially large) list of
objects in the session or rebuilding the whole list of objects again (though
only one is needed) when the form is submitted. The chief benefits are reduced
memory use and <a shape="rect" href="performance-and-clustering.html">more
scalable clustering</a> due to having far less HTTP session data to replicate
across the nodes of a cluster.</p></div>
</div>
<div class="clearer"></div>
![https://cwiki.apache.org/confluence/images/icons/back_16.gif"](https://cwiki.apache.org/confluence/images/icons/back_16.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/up_16.gif"](https://cwiki.apache.org/confluence/images/icons/up_16.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/forwd_16.gif"](https://cwiki.apache.org/confluence/images/icons/forwd_16.gif"){kind=link}