Modified: websites/production/tapestry/content/component-parameters.html
==============================================================================
--- websites/production/tapestry/content/component-parameters.html (original)
+++ websites/production/tapestry/content/component-parameters.html Tue Sep 26
19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,118 +67,13 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Component
parameters</strong> are the primary means for a component instance and its
container to communicate with each other. Parameters are used to
<em>configure</em> component instances.</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="component-parameters.html">Component
Parameters</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="component-templates.html">Component
Templates</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="templating-and-markup-faq.html">Templating
and Markup 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="component-classes.html">Component Classes</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="page-and-component-classes-faq.html">Page
And Component Classes 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="enum-parameter-recipe.html">Enum Parameter
Recipe</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="supporting-informal-parameters.html">Supporting Informal Parameters</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="default-parameter.html">Default Parameter</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="component-cheat-sheet.html">Component Cheat
Sheet</a>
-
-
- </div>
- </li></ul>
-</div>
-
-
-<p>In the following example, <code>page</code> is a parameter of the
<code>pagelink</code> component. The page parameter tells the pagelink
component which page to go to when the user clicks on the rendered
hyperlink:</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;"><html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+ <div id="ConfluenceContent"><p><strong>Component
parameters</strong> are the primary means for a component instance and its
container to communicate with each other. Parameters are used to
<em>configure</em> component instances.</p><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label in
("expressions","component-classes","component-templates","parameters") and
space = currentSpace()</parameter></rich-text-body><p>In the following example,
<code>page</code> is a parameter of the <code>pagelink</code> component. The
page parameter tells the pagelink component which page to go to when the user
clicks on the rendered hyperlink:</p><parameter
ac:name="language">xml</parameter><p
lain-text-body><html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<t:pagelink page="Index">Go Home</t:pagelink>
-</html></pre>
-</div></div><p>A component may have any number of parameters. Each parameter
has a specific name, a specific Java type (which may be a primitive value), and
may be <em>optional</em> or <em>required</em>.</p><p>Within a component class,
parameters are declared by using the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Parameter.html";>Parameter</a>
annotation on a private field, as we'll see below.</p><p><span
class="confluence-anchor-link"
id="ComponentParameters-bindingparameters"></span></p><h1
id="ComponentParameters-ParameterBindings">Parameter Bindings</h1><p>In
Tapestry, a parameter is not a slot into which data is pushed: it is a
<em>connection</em> between a field of the component (marked with the
@Parameter annotation) and a property or resource of the component's container.
(Components can be nested, so the container can be either the page or another
component.)</p><div class="navmenu" style="float:right; backgr
ound:white; margin:3px; padding:3px">
-<div class="panel" style="border-width: 1px;"><div class="panelHeader"
style="border-bottom-width: 1px;"><b>Contents</b></div><div
class="panelContent">
-<style type="text/css">/*<![CDATA[*/
-div.rbtoc1499639539109 {padding: 0px;}
-div.rbtoc1499639539109 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1499639539109 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style><div class="toc-macro rbtoc1499639539109">
-<ul class="toc-indentation"><li><a
href="#ComponentParameters-ParameterBindings">Parameter Bindings</a></li><li><a
href="#ComponentParameters-BindingExpressions">Binding
Expressions</a></li><li><a
href="#ComponentParameters-@Parameterannotation">@Parameter
annotation</a></li><li><a
href="#ComponentParameters-Don'tusethe${...}syntax!">Don't use the ${...}
syntax!</a></li><li><a href="#ComponentParameters-InformalParameters">Informal
Parameters</a></li><li><a
href="#ComponentParameters-ParametersAreBi-Directional">Parameters Are
Bi-Directional</a></li><li><a
href="#ComponentParameters-InheritedParameterBindings">Inherited Parameter
Bindings</a></li><li><a
href="#ComponentParameters-ComputedParameterBindingDefaults">Computed Parameter
Binding Defaults</a></li><li><a
href="#ComponentParameters-UnboundParameters">Unbound Parameters</a></li><li><a
href="#ComponentParameters-ParameterTypeCoercion">Parameter Type
Coercion</a></li><li><a href="#ComponentParameters-ParameterNames">
Parameter Names</a></li><li><a
href="#ComponentParameters-DeterminingifBound">Determining if
Bound</a></li><li><a
href="#ComponentParameters-PublishingParameters">Publishing
Parameters</a></li></ul>
-</div>
-</div></div></div> <p>The connection between a component and a property
(or resource) of its container is called a <em>binding</em>. The binding is
two-way: the component can read the bound property by reading its parameter
field. Likewise, a component that updates its parameter field will update the
bound property.</p><p>This is important in a lot of cases; for example a
TextField component can read <em>and update</em> the property bound to its
value parameter. It reads the value when rendering, but updates the value when
the form is submitted.</p><p>The component listed below is a looping component;
it renders its body a number of times, defined by its <code>start</code> and
<code>end</code> parameters (which set the boundaries of the loop). The
component can update a <code>result</code> parameter bound to a property of its
container; it will automatically count up or down depending on whether
<code>start</code> or <code>end</code> is larger.</p><div class="code panel
pdl" st
yle="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package org.example.app.components;
+</html></plain-text-body><p>A component may have any number of
parameters. Each parameter has a specific name, a specific Java type (which may
be a primitive value), and may be <em>optional</em> or
<em>required</em>.</p><p>Within a component class, parameters are declared by
using the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Parameter.html";>Parameter</a>
annotation on a private field, as we'll see below.</p><p><parameter
ac:name="">bindingparameters</parameter></p><h1
id="ComponentParameters-ParameterBindings">Parameter Bindings</h1><p>In
Tapestry, a parameter is not a slot into which data is pushed: it is a
<em>connection</em> between a field of the component (marked with the
@Parameter annotation) and a property or resource of the component's container.
(Components can be nested, so the container can be either the page or another
component.)<plain-text-body>{float:right}
+{panel:title=Contents|background=#eee}
+{toc:minLevel=1|maxLevel=2}
+{panel}
+{float}</plain-text-body> </p><p>The connection between a component and a
property (or resource) of its container is called a <em>binding</em>. The
binding is two-way: the component can read the bound property by reading its
parameter field. Likewise, a component that updates its parameter field will
update the bound property.</p><p>This is important in a lot of cases; for
example a TextField component can read <em>and update</em> the property bound
to its value parameter. It reads the value when rendering, but updates the
value when the form is submitted.</p><p>The component listed below is a looping
component; it renders its body a number of times, defined by its
<code>start</code> and <code>end</code> parameters (which set the boundaries of
the loop). The component can update a <code>result</code> parameter bound to a
property of its container; it will automatically count up or down depending on
whether <code>start</code> or <code>end</code> is larger.</p><parameter ac:name=
"language">java</parameter><plain-text-body>package org.example.app.components;
import org.apache.tapestry5.annotations.AfterRender;
import org.apache.tapestry5.annotations.Parameter;
@@ -239,40 +124,26 @@ public class Count
return true;
}
}
-</pre>
-</div></div><p>The name of the parameter is the same as field name (except
with leading "_" and "$" characters, if any, removed). Here, the parameter
names are "start", "end" and "result".</p><p>The component above can be
referenced in another component or page <a
href="component-templates.html">template</a>, and its parameters
<em>bound</em>:</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;"><html t:type="layout"
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</plain-text-body><p>The name of the parameter is the same as field name
(except with leading "_" and "$" characters, if any, removed). Here, the
parameter names are "start", "end" and "result".</p><p>The component above can
be referenced in another component or page <a
href="component-templates.html">template</a>, and its parameters
<em>bound</em>:</p><parameter
ac:name="language">xml</parameter><plain-text-body><html t:type="layout"
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<p> Merry Christmas: <t:count end="3"> Ho! </t:count>
</p>
</html>
-</pre>
-</div></div><p>The end attribute is used to <em>bind</em> the end parameter of
the Count component. Here, it is being bound to the string value "3", which is
automatically <a href="parameter-type-coercion.html">coerced</a> by Tapestry
into the int value, 3.</p><p>Any number of parameters may be bound this
way.</p><p>Component parameters may also be bound using the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation inside the component class. (Where conflicts occur, the parameters
bound using the Component annotation will take precedence over parameter
bindings in the template.)</p><p><span class="confluence-anchor-link"
id="ComponentParameters-binding-expressions"></span></p><h1
id="ComponentParameters-BindingExpressions">Binding Expressions</h1><p>The
value inside the template, "3" in the previous example, is a <em>binding
expression</em>.</p><p>By placing a prefix in front of the va
lue, you can change how Tapestry interprets the remainder of the expression
(the part after the colon):</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p><strong>Prefix</strong></p></th><th colspan="1"
rowspan="1"
class="confluenceTh"><p><strong>Description</strong></p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asset:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The relative path to an asset file (which
must exist)</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>block:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The id of a block within the
template</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>component:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The id of another component within the same
template</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>context:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Context asset: path from context
root</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>literal:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A literal string</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>nullfieldstrategy:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Used to locate a pre-defined <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/NullFieldStrategy.html";>NullFieldStrategy</a></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>message:</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Retrieves a string from the
component's <a href="component-parameters.html">message
catalog</a></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>prop:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A <a href="property-expressions.html">property
expression</a> to read or updat
e</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>symbol:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Used to read one of your <a
href="symbols.html">symbols</a></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>translate:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The name of a configured
translator</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>validate:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A <em>validator specification</em> used to create some
number of field validators</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>var:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Allows a render variable of the component to be read or
updated</p></td></tr></tbody></table></div><p>Most of these binding prefixes
allow parameters to be bound to read-only values; for instance a parameter
bound to "message:some-key" will see the message for "some
-key" from its container's message catalog in the field. If the component
tries to update the parameter (by setting the value of the field), a runtime
exception will be thrown to indicate that the value is read-only.</p><p>Only
prop: and var: binding prefixes are updateable (but you must <em>not</em> use
the ${..} syntax here; see the <a href="component-parameters.html">warning
below</a>).</p><p>Each parameter has a default prefix, defined by the
component, that is used when the prefix is not provided. The most common are
"literal:" and "prop:".</p><p>A <em>special prefix</em>, "inherit:", is used to
support <a href="component-parameters.html">Inherited Parameter
Bindings</a>.</p><h3 id="ComponentParameters-RenderVariables:Bindings">Render
Variables: Bindings</h3><p>Components can have any number of <em>render
variables</em>. Render variables are named values with no specific type (they
are ultimately stored in a Map). Render variables are useful for holding simple
values, such as
loop indices, that need to be passed from one component to another.</p><p>For
example, the following template code:</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;"><ul>
+</plain-text-body><p>The end attribute is used to <em>bind</em> the end
parameter of the Count component. Here, it is being bound to the string value
"3", which is automatically <a href="parameter-type-coercion.html">coerced</a>
by Tapestry into the int value, 3.</p><p>Any number of parameters may be bound
this way.</p><p>Component parameters may also be bound using the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation inside the component class. (Where conflicts occur, the parameters
bound using the Component annotation will take precedence over parameter
bindings in the template.)</p><p><parameter
ac:name="">binding-expressions</parameter></p><h1
id="ComponentParameters-BindingExpressions">Binding Expressions</h1><p>The
value inside the template, "3" in the previous example, is a <em>binding
expression</em>.</p><p>By placing a prefix in front of the value, you can
change how Tapest
ry interprets the remainder of the expression (the part after the
colon):</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p><strong>Prefix</strong></p></th><th colspan="1"
rowspan="1"
class="confluenceTh"><p><strong>Description</strong></p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>asset:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The relative path to an asset file (which
must exist)</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>block:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The id of a block within the
template</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>component:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The id of another component within the same
template</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>context:</p></td><td colspan="1" rowspan="1"
class="confluenceT
d"><p>Context asset: path from context root</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>literal:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A literal string</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>nullfieldstrategy:</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Used to locate a pre-defined <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/NullFieldStrategy.html";>NullFieldStrategy</a></p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>message:</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Retrieves a string from the
component's <a href="component-parameters.html">message
catalog</a></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>prop:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A <a href="property-expressions.html">property
expression</a> to read or update</p></td></tr><tr><td colspan
="1" rowspan="1" class="confluenceTd"><p>symbol:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Used to read one of your <a
href="symbols.html">symbols</a></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>translate:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The name of a configured
translator</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>validate:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>A <em>validator specification</em> used to create some
number of field validators</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>var:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Allows a render variable of the component to be read or
updated</p></td></tr></tbody></table></div><p>Most of these binding prefixes
allow parameters to be bound to read-only values; for instance a parameter
bound to "message:some-key" will see the message for "some-key" from its
container's mes
sage catalog in the field. If the component tries to update the parameter (by
setting the value of the field), a runtime exception will be thrown to indicate
that the value is read-only.</p><p>Only prop: and var: binding prefixes are
updateable (but you must <em>not</em> use the ${..} syntax here; see the <a
href="component-parameters.html">warning below</a>).</p><p>Each parameter has a
default prefix, defined by the component, that is used when the prefix is not
provided. The most common are "literal:" and "prop:".</p><p>A <em>special
prefix</em>, "inherit:", is used to support <a
href="component-parameters.html">Inherited Parameter Bindings</a>.</p><h3
id="ComponentParameters-RenderVariables:Bindings">Render Variables:
Bindings</h3><p>Components can have any number of <em>render variables</em>.
Render variables are named values with no specific type (they are ultimately
stored in a Map). Render variables are useful for holding simple values, such
as loop indices, that need to be
passed from one component to another.</p><p>For example, the following
template code:</p><parameter
ac:name="language">xml</parameter><plain-text-body><ul>
<li t:type="loop" source="1..10" value="index">${index}</li>
</ul>
-</pre>
-</div></div><p>and the following Java code:</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;">@Property
+</plain-text-body><p>and the following Java code:</p><parameter
ac:name="language">java</parameter><plain-text-body>@Property
private int index;
-</pre>
-</div></div><p>... could be rewritten as just:</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;"><ul>
+</plain-text-body><p>... could be rewritten as just:</p><parameter
ac:name="language">xml</parameter><plain-text-body><ul>
<li t:type="loop" source="1..10"
value="var:index">${var:index}</li>
</ul>
-</pre>
-</div></div><p>In other words, you don't have to define a property in the Java
code. The disadvantage is that render variables don't work with the property
expression syntax, so you can pass around a render variable's <em>value</em>
but you can't reference any of the value's properties.</p><p>Render variables
are automatically cleared when a component finishes rendering.</p><p>Render
variable names are case insensitive.</p><h3
id="ComponentParameters-Property:Bindings">Property: Bindings</h3><p>The
"prop:" binding prefix indicates a property expression binding.</p><p>Property
expressions are used to link a parameter of a component to a property of its
container. Property expressions can navigate a series of properties and/or
invoke methods, as well as several other useful patterns. See <a
href="property-expressions.html">Property Expressions</a>.</p><p>The default
binding prefix in most cases is "prop:", which is why it is usually
omitted.</p><h3 id="ComponentParameters-Validate:Bi
ndings">Validate: Bindings</h3><p>Main Article: <a
href="forms-and-validation.html">Forms and Validation</a></p><p>The "validate:"
binding prefix is highly specialized. It allows a short string to be used to
create and configure the objects that perform input validation for form control
components, such as TextField and Checkbox.</p><p>The string is a
comma-separated list of <em>validator types</em>. These are short aliases for
objects that perform the validation. In many cases, the validation is
configurable in some way: for example, a validator that enforces a minimum
string length needs to know what that minimum string length is. Such values are
specified after an equals sign.</p><p>For example:
<code>validate:required,minLength=5</code> would presumably enforce that a
field requires a value, and with at least five characters.</p><h3
id="ComponentParameters-Translate:Bindings">Translate: Bindings</h3><p>The
"translate:" binding prefix is also related to input validation. It is t
he name of a configured <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Translator.html";>Translator</a>,
responsible for converting between server-side and client-side representations
of data (for instance, between client-side strings and server-side numeric
values).</p><p>The list of available translators is configured by the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/TranslatorSource.html";>TranslatorSource</a>
service.</p><h3 id="ComponentParameters-Asset:Bindings">Asset:
Bindings</h3><p>Assets bindings are used to specify <a
href="assets.html">Assets</a>, static content served by Tapestry. By default,
assets are located relative to the component class in your packaged application
or module. This can be overridden by prefixing the path with "context:", in
which case, the path is a context path from the root of the web application
context. Because accessing context assets
is relatively common, a separate "context:" binding prefix for that purpose
exists (described below).</p><h3
id="ComponentParameters-Context:Bindings">Context: Bindings</h3><p>Context
bindings are like asset bindings, but the path is <em>always</em> relative to
the root of the web application context. This is intended for use inside
templates, i.e.:</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;"> <img src="${context:images/icon.png}"/>
-</pre>
-</div></div><p>Tapestry will adjust the URL of the image so that it is
processed by Tapestry, not the servlet container. It will gain a URL that
includes the application's version number, it will have a far-future expires
header, and (if the client supports it) its content will be compressed before
being sent to the client.</p><h1
id="ComponentParameters-@Parameterannotation">@Parameter annotation</h1><h3
id="ComponentParameters-RequiredParameters">Required
Parameters</h3><p>Parameters that are required <strong>must</strong> be bound.
A runtime exception occurs if a component has unbound required
parameters.</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;">public class Component{
+</plain-text-body><p>In other words, you don't have to define a property in
the Java code. The disadvantage is that render variables don't work with the
property expression syntax, so you can pass around a render variable's
<em>value</em> but you can't reference any of the value's
properties.</p><p>Render variables are automatically cleared when a component
finishes rendering.</p><p>Render variable names are case insensitive.</p><h3
id="ComponentParameters-Property:Bindings">Property: Bindings</h3><p>The
"prop:" binding prefix indicates a property expression binding.</p><p>Property
expressions are used to link a parameter of a component to a property of its
container. Property expressions can navigate a series of properties and/or
invoke methods, as well as several other useful patterns. See <a
href="property-expressions.html">Property Expressions</a>.</p><p>The default
binding prefix in most cases is "prop:", which is why it is usually
omitted.</p><h3 id="ComponentParameters-Valid
ate:Bindings">Validate: Bindings</h3><p>Main Article: <a
href="forms-and-validation.html">Forms and Validation</a></p><p>The "validate:"
binding prefix is highly specialized. It allows a short string to be used to
create and configure the objects that perform input validation for form control
components, such as TextField and Checkbox.</p><p>The string is a
comma-separated list of <em>validator types</em>. These are short aliases for
objects that perform the validation. In many cases, the validation is
configurable in some way: for example, a validator that enforces a minimum
string length needs to know what that minimum string length is. Such values are
specified after an equals sign.</p><p>For example:
<code>validate:required,minLength=5</code> would presumably enforce that a
field requires a value, and with at least five characters.</p><h3
id="ComponentParameters-Translate:Bindings">Translate: Bindings</h3><p>The
"translate:" binding prefix is also related to input validation. I
t is the name of a configured <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Translator.html";>Translator</a>,
responsible for converting between server-side and client-side representations
of data (for instance, between client-side strings and server-side numeric
values).</p><p>The list of available translators is configured by the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/TranslatorSource.html";>TranslatorSource</a>
service.</p><h3 id="ComponentParameters-Asset:Bindings">Asset:
Bindings</h3><p>Assets bindings are used to specify <a
href="assets.html">Assets</a>, static content served by Tapestry. By default,
assets are located relative to the component class in your packaged application
or module. This can be overridden by prefixing the path with "context:", in
which case, the path is a context path from the root of the web application
context. Because accessing context a
ssets is relatively common, a separate "context:" binding prefix for that
purpose exists (described below).</p><h3
id="ComponentParameters-Context:Bindings">Context: Bindings</h3><p>Context
bindings are like asset bindings, but the path is <em>always</em> relative to
the root of the web application context. This is intended for use inside
templates, i.e.:</p><parameter
ac:name="language">xml</parameter><plain-text-body> <img
src="${context:images/icon.png}"/>
+</plain-text-body><p>Tapestry will adjust the URL of the image so that it is
processed by Tapestry, not the servlet container. It will gain a URL that
includes the application's version number, it will have a far-future expires
header, and (if the client supports it) its content will be compressed before
being sent to the client.</p><h1
id="ComponentParameters-@Parameterannotation">@Parameter annotation</h1><h3
id="ComponentParameters-RequiredParameters">Required
Parameters</h3><p>Parameters that are required <strong>must</strong> be bound.
A runtime exception occurs if a component has unbound required
parameters.</p><parameter
ac:name="language">java</parameter><plain-text-body>public class Component{
@Parameter(required = true)
private String parameter;
-}</pre>
-</div></div><div class="confluence-information-macro
confluence-information-macro-tip"><span class="aui-icon aui-icon-small
aui-iconfont-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Sometimes a parameter is marked as
required, but may still be omitted if the underlying value is provided by some
other means. This is the case, for example, with the Select component's value
parameter, which may have its underlying value set by <a
href="using-select-with-a-list.html">contributing a ValueEncoderSource</a>. Be
sure to read the component's parameter documentation carefully. Required simply
enables checks that the parameter is bound, it does not mean that you must
supply the binding in the template (or @Component
annotation).</p></div></div><h3
id="ComponentParameters-OptionalParameters">Optional
Parameters</h3><p>Parameters are optional unless they are marked as
required.</p><p>You may set a default value for optional parameters using
the <code>value</code> element of the @Parameter annotation. In the Count
component above, the start parameter has a default value of 1. That value is
used unless the start parameter is bound, in which case, the bound value
supersedes the default.</p><h3
id="ComponentParameters-ParameterBindingDefaults">Parameter Binding
Defaults</h3><p>The @Parameter annotation's <code>value</code> element can be
used to specify a <em>binding expression</em> that will be the default binding
for the parameter if otherwise left unbound. Typically, this is the name of a
property that that will compute the value on the fly.</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;">@Parameter(value="defaultMessage") // or, equivalently,
@Parameter("defaultMessage")
+}</plain-text-body><rich-text-body><p>Sometimes a parameter is marked as
required, but may still be omitted if the underlying value is provided by some
other means. This is the case, for example, with the Select component's value
parameter, which may have its underlying value set by <a
href="using-select-with-a-list.html">contributing a ValueEncoderSource</a>. Be
sure to read the component's parameter documentation carefully. Required simply
enables checks that the parameter is bound, it does not mean that you must
supply the binding in the template (or @Component
annotation).</p></rich-text-body><h3
id="ComponentParameters-OptionalParameters">Optional
Parameters</h3><p>Parameters are optional unless they are marked as
required.</p><p>You may set a default value for optional parameters using the
<code>value</code> element of the @Parameter annotation. In the Count component
above, the start parameter has a default value of 1. That value is used unless
the start parameter is bound,
in which case, the bound value supersedes the default.</p><h3
id="ComponentParameters-ParameterBindingDefaults">Parameter Binding
Defaults</h3><p>The @Parameter annotation's <code>value</code> element can be
used to specify a <em>binding expression</em> that will be the default binding
for the parameter if otherwise left unbound. Typically, this is the name of a
property that that will compute the value on the fly.</p><parameter
ac:name="language">java</parameter><plain-text-body>@Parameter(value="defaultMessage")
// or, equivalently, @Parameter("defaultMessage")
private String message;
@Parameter(required=true)
@@ -282,51 +153,33 @@ public String getDefaultMessage(){ 
return String.format("Maximum field length is %d.", maxLength);
}
-</pre>
-</div></div><p>As elsewhere, you may use a prefix on the value. A common
prefix to use is the "message:" prefix, to access a localized message.</p><h3
id="ComponentParameters-ParameterCaching">Parameter Caching</h3><p>Reading a
parameter value can be marginally expensive (because of type coercion).
Therefore, it makes sense to cache the parameter value, at least while the
component is actively rendering itself.</p><p>In rare cases, it is desirable to
defeat the caching; this can be done by setting the cache() attribute of the
@Parameter annotation to false.</p><p><span class="confluence-anchor-link"
id="ComponentParameters-dontUseSyntax"></span></p><h1
id="ComponentParameters-Don'tusethe${...}syntax!">Don't use the ${...}
syntax!</h1><p>Main Article: <a href="component-templates.html">Component
Templates#Expansions</a></p><p>You generally should <em>not</em> use the
Template Expansion syntax, ${...}, within component parameter bindings. Doing
so results in the property inside the b
races being converted to an (immutable) string, and will therefore result in a
runtime exception if your component needs to update the value (whenever the
default or explicit binding prefix is <code>prop:</code> or <code>var:</code>,
since such component parameters are <em>two-way</em> bindings).</p><div
class="sectionColumnWrapper"><div class="sectionMacro"><div
class="sectionMacroRow"><div class="columnMacro"><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>This is right</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:textfield t:id="color" value="color"/>
-</pre>
-</div></div></div><div class="columnMacro"><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>This is wrong</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:textfield t:id="color" value="${color}"/>
-</pre>
-</div></div></div></div></div></div><p>The general rule is, only use the
${...} syntax in non-Tapestry-controlled locations in your template, such as in
attributes of ordinary HTML elements and in plain-text areas of your
template.</p><div class="sectionColumnWrapper"><div class="sectionMacro"><div
class="sectionMacroRow"><div class="columnMacro"><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>This is right</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><img src="${context:images/banner.png}"/>
-</pre>
-</div></div></div><div class="columnMacro"><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>This is wrong</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><img src="context:images/banner.png"/>
-</pre>
-</div></div></div></div></div></div><h1
id="ComponentParameters-InformalParameters">Informal Parameters</h1><p>Main
Article: <a href="supporting-informal-parameters.html">Supporting Informal
Parameters</a></p><p>Many components support <em>informal parameters</em>,
additional parameters beyond the formally defined parameters. Informal
parameters will be rendered into the output as additional attributes on the tag
rendered by the component. Generally speaking, components that have a 1:1
relationship with a particular HTML tag (such as <TextField> and
<input> will support informal parameters.</p><p>Only components whose
class is annotated with @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SupportsInformalParameters.html";>SupportsInformalParameters</a>
will support informal parameters. Tapestry silently drops informal parameters
that are specified for components that do not have this
annotation.</p><p>Informal
parameters are often used to set the CSS class of an element, or to specify
client-side event handlers.</p><p>The default binding prefix for informal
parameters depends on <em>where</em> the parameter binding is specified. If the
parameter is bound inside a Java class, within the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation, then the default binding prefix is "prop:". If the parameter is
bound inside the component template, then the default binding prefix is
"literal:". This reflects the fact that a parameter specified in the Java
class, using the annotation, is most likely a computed value, whereas a value
in the template should simply be copied, as is, into the result HTML
stream.</p><p>Informal parameters (if supported) are always rendered into the
output <em>unless</em> they are bound to a property whose value is null. If the
bound property is null then the parameter will <em
>not</em> be present at all in the rendered output.</p><p>If your component
>should render informal parameters, just inject the <a class="external-link"
>href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>ComponentResources</a>
> for your component and invoke the <code>renderInformalParameters()</code>
>method. See <a href="supporting-informal-parameters.html">Supporting
>Informal Parameters</a> for an example of how to do this.</p><h1
>id="ComponentParameters-ParametersAreBi-Directional">Parameters Are
>Bi-Directional</h1><p>Parameters are not simply variables; each parameter
>represents a connection, or <em>binding</em>, between a component and a
>property of its container. When using the prop: binding prefix, the component
>can force changes <em>into</em> a property of its container, just by
>assigning a value to its own instance variable.</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:layout
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</plain-text-body><p>As elsewhere, you may use a prefix on the value. A common
prefix to use is the "message:" prefix, to access a localized message.</p><h3
id="ComponentParameters-ParameterCaching">Parameter Caching</h3><p>Reading a
parameter value can be marginally expensive (because of type coercion).
Therefore, it makes sense to cache the parameter value, at least while the
component is actively rendering itself.</p><p>In rare cases, it is desirable to
defeat the caching; this can be done by setting the cache() attribute of the
@Parameter annotation to false.</p><p><parameter
ac:name="">dontUseSyntax</parameter></p><h1
id="ComponentParameters-Don'tusethe${...}syntax!">Don't use the ${...}
syntax!</h1><p>Main Article: <a href="component-templates.html">Component
Templates#Expansions</a></p><p>You generally should <em>not</em> use the
Template Expansion syntax, ${...}, within component parameter bindings. Doing
so results in the property inside the braces being converted to an (i
mmutable) string, and will therefore result in a runtime exception if your
component needs to update the value (whenever the default or explicit binding
prefix is <code>prop:</code> or <code>var:</code>, since such component
parameters are <em>two-way</em>
bindings).</p><rich-text-body><rich-text-body><parameter
ac:name="language">xml</parameter><parameter ac:name="title">This is
right</parameter><plain-text-body><t:textfield t:id="color"
value="color"/>
+</plain-text-body></rich-text-body><rich-text-body><parameter
ac:name="language">xml</parameter><parameter ac:name="title">This is
wrong</parameter><plain-text-body><t:textfield t:id="color"
value="${color}"/>
+</plain-text-body></rich-text-body></rich-text-body><p>The general rule is,
only use the ${...} syntax in non-Tapestry-controlled locations in your
template, such as in attributes of ordinary HTML elements and in plain-text
areas of your template.</p><rich-text-body><rich-text-body><parameter
ac:name="language">xml</parameter><parameter ac:name="title">This is
right</parameter><plain-text-body><img
src="${context:images/banner.png}"/>
+</plain-text-body></rich-text-body><rich-text-body><parameter
ac:name="language">xml</parameter><parameter ac:name="title">This is
wrong</parameter><plain-text-body><img src="context:images/banner.png"/>
+</plain-text-body></rich-text-body></rich-text-body><h1
id="ComponentParameters-InformalParameters">Informal Parameters</h1><p>Main
Article: <a href="supporting-informal-parameters.html">Supporting Informal
Parameters</a></p><p>Many components support <em>informal parameters</em>,
additional parameters beyond the formally defined parameters. Informal
parameters will be rendered into the output as additional attributes on the tag
rendered by the component. Generally speaking, components that have a 1:1
relationship with a particular HTML tag (such as <TextField> and
<input> will support informal parameters.</p><p>Only components whose
class is annotated with @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SupportsInformalParameters.html";>SupportsInformalParameters</a>
will support informal parameters. Tapestry silently drops informal parameters
that are specified for components that do not have this annotation.
</p><p>Informal parameters are often used to set the CSS class of an element,
or to specify client-side event handlers.</p><p>The default binding prefix for
informal parameters depends on <em>where</em> the parameter binding is
specified. If the parameter is bound inside a Java class, within the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation, then the default binding prefix is "prop:". If the parameter is
bound inside the component template, then the default binding prefix is
"literal:". This reflects the fact that a parameter specified in the Java
class, using the annotation, is most likely a computed value, whereas a value
in the template should simply be copied, as is, into the result HTML
stream.</p><p>Informal parameters (if supported) are always rendered into the
output <em>unless</em> they are bound to a property whose value is null. If the
bound property is null then the pa
rameter will <em>not</em> be present at all in the rendered output.</p><p>If
your component should render informal parameters, just inject the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>ComponentResources</a>
for your component and invoke the <code>renderInformalParameters()</code>
method. See <a href="supporting-informal-parameters.html">Supporting Informal
Parameters</a> for an example of how to do this.</p><h1
id="ComponentParameters-ParametersAreBi-Directional">Parameters Are
Bi-Directional</h1><p>Parameters are not simply variables; each parameter
represents a connection, or <em>binding</em>, between a component and a
property of its container. When using the prop: binding prefix, the component
can force changes <em>into</em> a property of its container, just by assigning
a value to its own instance variable.</p><parameter
ac:name="language">xml</parameter><plain-text-body><t:layout xmlns:t="http:
//tapestry.apache.org/schema/tapestry_5_3.xsd">
<p> Countdown:
<t:count start="5" end="1" result="index">
${index} ...
</t:count>
</p>
</t:layout>
-</pre>
-</div></div><p>Because the Count component updates its result parameter (the
<code>result</code> field), the index property of the containing component is
updated. Inside the Count's body, we output the current value of the index
property, using the expansion <code>${index</code>}. The resulting output will
look something like:</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;"> <p> Countdown: 5 ... 4 ... 3 ... 2 ... 1 ...
</p>
-</pre>
-</div></div><p>(Though the whitespace will be quite different.)</p><p>The
relevant part is that components can read fixed values, or <em>live</em>
properties of their container, and can <em>change</em> properties of their
container as well.</p><h1
id="ComponentParameters-InheritedParameterBindings">Inherited Parameter
Bindings</h1><p>A special prefix, "inherit:" is used to identify the name of a
parameter of the containing component. If the parameter is bound in the
containing component, then it will be bound to the same value in the embedded
component.</p><p>If the parameter is not bound in the containing component,
then it will not be bound in the embedded component (and so, the embedded
component may use a default binding).</p><p>Inherited bindings are useful for
complex components; they are often used when an inner component has a default
value for a parameter, and the outer component wants to make it possible to
override that default.</p><div class="code panel pdl" style="borde
r-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Index.tml</b></div><div class="codeContent
panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</plain-text-body><p>Because the Count component updates its result parameter
(the <code>result</code> field), the index property of the containing component
is updated. Inside the Count's body, we output the current value of the index
property, using the expansion <code>${index</code>}. The resulting output will
look something like:</p><parameter
ac:name="language">xml</parameter><plain-text-body> <p> Countdown: 5 ...
4 ... 3 ... 2 ... 1 ... </p>
+</plain-text-body><p>(Though the whitespace will be quite
different.)</p><p>The relevant part is that components can read fixed values,
or <em>live</em> properties of their container, and can <em>change</em>
properties of their container as well.</p><h1
id="ComponentParameters-InheritedParameterBindings">Inherited Parameter
Bindings</h1><p>A special prefix, "inherit:" is used to identify the name of a
parameter of the containing component. If the parameter is bound in the
containing component, then it will be bound to the same value in the embedded
component.</p><p>If the parameter is not bound in the containing component,
then it will not be bound in the embedded component (and so, the embedded
component may use a default binding).</p><p>Inherited bindings are useful for
complex components; they are often used when an inner component has a default
value for a parameter, and the outer component wants to make it possible to
override that default.</p><parameter ac:name="language">xml<
/parameter><parameter
ac:name="title">Index.tml</parameter><plain-text-body><html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<body>
<div t:type="layout" t:menuTitle="literal:The Title">
...
</div>
</body>
</html>
-</pre>
-</div></div><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Layout.tml</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:container
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</plain-text-body><parameter ac:name="language">xml</parameter><parameter
ac:name="title">Layout.tml</parameter><plain-text-body><t:container
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<div t:type="title" t:title="inherit:menuTitle"></div>
<t:body />
</t:container>
-</pre>
-</div></div><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Title.java</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package org.example.app.components;
+</plain-text-body><parameter ac:name="language">java</parameter><parameter
ac:name="title">Title.java</parameter><plain-text-body>package
org.example.app.components;
import org.apache.tapestry5.annotations.Parameter;
@@ -336,9 +189,7 @@ public class Title {
private String title;
}
-</pre>
-</div></div><h1
id="ComponentParameters-ComputedParameterBindingDefaults">Computed Parameter
Binding Defaults</h1><p>In <em>rare</em> cases, you may want to compute the
binding to be used as a parameter default. In this case, you will provide a
<em>default binding method</em>, a method that takes no parameters. The
returned value is used to bind the parameter. The return value may be a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Binding.html";>Binding</a>
instance, or it may be a simple value (which is more often the
case).</p><p>The method name is "default" plus the capitalized name of the
parameter.</p><p>Using this approach, the previous example may be rewritten
as:</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;"> @Parameter
+</plain-text-body><h1
id="ComponentParameters-ComputedParameterBindingDefaults">Computed Parameter
Binding Defaults</h1><p>In <em>rare</em> cases, you may want to compute the
binding to be used as a parameter default. In this case, you will provide a
<em>default binding method</em>, a method that takes no parameters. The
returned value is used to bind the parameter. The return value may be a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Binding.html";>Binding</a>
instance, or it may be a simple value (which is more often the
case).</p><p>The method name is "default" plus the capitalized name of the
parameter.</p><p>Using this approach, the previous example may be rewritten
as:</p><parameter ac:name="language">java</parameter><plain-text-body>
@Parameter
private String message;
@Parameter(required=true)
@@ -359,9 +210,7 @@ public class Title {
{
return String.format("Maximum field length is %d.", maxLength);
}
-</pre>
-</div></div><p>In this example, a property expression, "basicMessage", is used
to access the message dynamically.</p><p>Alternately, the previous example may
be written even more succinctly as:</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;"> @Parameter
+</plain-text-body><p>In this example, a property expression, "basicMessage",
is used to access the message dynamically.</p><p>Alternately, the previous
example may be written even more succinctly as:</p><parameter
ac:name="language">java</parameter><plain-text-body> @Parameter
private String message;
@Parameter(required=true)
@@ -374,9 +223,7 @@ public class Title {
{
return String.format("Maximum field length is %d.", maxLength);
}
-</pre>
-</div></div><p>This form is more like using the "literal:" binding prefix,
except that the literal value is computed by the defaultMessage()
method.</p><p>Obviously, this is a lot more work than simply specifying a
default value as part of the @Parameter annotation. In the few real cases where
this is approach is used, the default binding method will usually deduce a
proper binding, typically in terms of the component's id. For example, the
TextField component will deduce a value parameter that binds to a property of
its container with the same name.</p><p>A default binding method will
<em>only</em> be invoked if the @Parameter annotation does not provide a
default value.</p><h1 id="ComponentParameters-UnboundParameters">Unbound
Parameters</h1><p>If a parameter is not bound (and is optional), then the value
may be read or <em>updated</em> at any time.</p><p>Updates to unbound
parameters cause no side effects. In the first example, the value parameter of
the Count component is not bo
und, and this is perfectly valid.</p><p>Note: updates to such fields are
temporary; when the component <em>finishes rendering</em>, the field will
revert to its default value.</p><h1
id="ComponentParameters-ParameterTypeCoercion">Parameter Type
Coercion</h1><p>Main Article: <a href="parameter-type-coercion.html">Parameter
Type Coercion</a></p><p>Tapestry includes a mechanism for <span
class="confluence-link">coercing types automatically</span>. Most often, this
is used to convert literal strings into appropriate values, but in many cases,
more complex conversions will occur. This mechanism is used for component
parameters, such as when an outer component passes a literal string to an inner
component that is expecting an integer.</p><p>You can easily <a
href="type-coercion.html">contribute new coercions</a> for your own
purposes.</p><h1 id="ComponentParameters-ParameterNames">Parameter
Names</h1><p>By default, Tapestry converts from the field name to the parameter
name, by strippin
g off leading "$" and "_" characters.</p><p>This can be overridden using the
name() attribute of the @Parameter annotation.</p><h1
id="ComponentParameters-DeterminingifBound">Determining if Bound</h1><p>In rare
cases, you may want to take different behaviors based on whether a parameter is
bound or not. This can be accomplished by querying the component's resources,
which can be <a href="injection.html">injected</a> into the component using
the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation:</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;">public class MyComponent
+</plain-text-body><p>This form is more like using the "literal:" binding
prefix, except that the literal value is computed by the defaultMessage()
method.</p><p>Obviously, this is a lot more work than simply specifying a
default value as part of the @Parameter annotation. In the few real cases where
this is approach is used, the default binding method will usually deduce a
proper binding, typically in terms of the component's id. For example, the
TextField component will deduce a value parameter that binds to a property of
its container with the same name.</p><p>A default binding method will
<em>only</em> be invoked if the @Parameter annotation does not provide a
default value.</p><h1 id="ComponentParameters-UnboundParameters">Unbound
Parameters</h1><p>If a parameter is not bound (and is optional), then the value
may be read or <em>updated</em> at any time.</p><p>Updates to unbound
parameters cause no side effects. In the first example, the value parameter of
the Count component is
not bound, and this is perfectly valid.</p><p>Note: updates to such fields are
temporary; when the component <em>finishes rendering</em>, the field will
revert to its default value.</p><h1
id="ComponentParameters-ParameterTypeCoercion">Parameter Type
Coercion</h1><p>Main Article: <a href="parameter-type-coercion.html">Parameter
Type Coercion</a></p><p>Tapestry includes a mechanism for <span
class="confluence-link">coercing types automatically</span>. Most often, this
is used to convert literal strings into appropriate values, but in many cases,
more complex conversions will occur. This mechanism is used for component
parameters, such as when an outer component passes a literal string to an inner
component that is expecting an integer.</p><p>You can easily <a
href="type-coercion.html">contribute new coercions</a> for your own
purposes.</p><h1 id="ComponentParameters-ParameterNames">Parameter
Names</h1><p>By default, Tapestry converts from the field name to the parameter
name, by st
ripping off leading "$" and "_" characters.</p><p>This can be overridden using
the name() attribute of the @Parameter annotation.</p><h1
id="ComponentParameters-DeterminingifBound">Determining if Bound</h1><p>In rare
cases, you may want to take different behaviors based on whether a parameter is
bound or not. This can be accomplished by querying the component's resources,
which can be <a href="injection.html">injected</a> into the component using
the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation:</p><parameter
ac:name="language">java</parameter><plain-text-body>public class MyComponent
{
@Parameter
private int myParam;
@@ -393,22 +240,15 @@ public class Title {
}
}
}
-</pre>
-</div></div><p>The above sketch illustrates the approach. Because the
parameter type is a primitive type, int, it is hard to distinguish between no
binding, and binding explicitly to the value 0.</p><p>The @Inject annotation
will inject the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>ComponentResources</a>
for the component. These resources are the linkage between the Java class you
provide, and the infrastructure Tapestry builds around your class. In any case,
once the resources are injected, they can be queried.</p><h1
id="ComponentParameters-PublishingParameters">Publishing
Parameters</h1><p>Often when creating new components from existing components,
you want to expose some of the functionality of the embedded component, in the
form of exposing parameters of the embedded components as parameters of the
outer component.</p><p>In Tapestry 5.0, you would define a parameter of the
outer component, and use t
he "inherit:" binding prefix to connect the inner component's parameter to the
outer component's parameter. This is somewhat clumsy, as it involves creating
an otherwise unused field just for the parameter; in practice it also leads to
duplication of the documentation of the parameter.</p><p>In Tapestry 5.1 and
later, you may use the publishParameters attribute of the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation. List one or more parameters separated by commas: those parameters
of the inner/embedded component become parameters of the outer component. You
should <strong>not</strong> define a parameter field in the outer
component.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>ContainerComponent.tml</b></div><div class="codeContent panelContent
pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:container
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</plain-text-body><p>The above sketch illustrates the approach. Because the
parameter type is a primitive type, int, it is hard to distinguish between no
binding, and binding explicitly to the value 0.</p><p>The @Inject annotation
will inject the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>ComponentResources</a>
for the component. These resources are the linkage between the Java class you
provide, and the infrastructure Tapestry builds around your class. In any case,
once the resources are injected, they can be queried.</p><h1
id="ComponentParameters-PublishingParameters">Publishing
Parameters</h1><p>Often when creating new components from existing components,
you want to expose some of the functionality of the embedded component, in the
form of exposing parameters of the embedded components as parameters of the
outer component.</p><p>In Tapestry 5.0, you would define a parameter of the
outer component, and
use the "inherit:" binding prefix to connect the inner component's parameter
to the outer component's parameter. This is somewhat clumsy, as it involves
creating an otherwise unused field just for the parameter; in practice it also
leads to duplication of the documentation of the parameter.</p><p>In Tapestry
5.1 and later, you may use the publishParameters attribute of the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html";>Component</a>
annotation. List one or more parameters separated by commas: those parameters
of the inner/embedded component become parameters of the outer component. You
should <strong>not</strong> define a parameter field in the outer
component.</p><parameter ac:name="language">xml</parameter><parameter
ac:name="title">ContainerComponent.tml</parameter><plain-text-body><t:container
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<t:pageLink t:id="link">Page Link</t:pageLink>
</t:container>
-</pre>
-</div></div><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>ContainerComponent.java</b></div><div class="codeContent panelContent
pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class ContainerComponent{
+</plain-text-body><parameter ac:name="language">java</parameter><parameter
ac:name="title">ContainerComponent.java</parameter><plain-text-body>public
class ContainerComponent{
@Component(id="link", publishParameters="page")
private PageLink link;
}
-</pre>
-</div></div><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Index.tml</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><t:ContainerComponent t:id="Container"
t:page="About" />
-</pre>
-</div></div><p>There are still cases where you want to use the "inherit:"
binding prefix. For example, if you have several components that need to share
a parameter, then you must do it the Tapestry 5.0 way: a true parameter on the
outer component, and "inherit:" bindings on the embedded components. You can
follow a similar pattern to rename a parameter in the outer component.</p></div>
+</plain-text-body><parameter ac:name="language">xml</parameter><parameter
ac:name="title">Index.tml</parameter><plain-text-body><t:ContainerComponent
t:id="Container" t:page="About" />
+</plain-text-body><p>There are still cases where you want to use the
"inherit:" binding prefix. For example, if you have several components that
need to share a parameter, then you must do it the Tapestry 5.0 way: a true
parameter on the outer component, and "inherit:" bindings on the embedded
components. You can follow a similar pattern to rename a parameter in the outer
component.</p></div>
</div>
<div class="clearer"></div>
