You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bu...@apache.org on 2014/01/18 18:20:53 UTC
svn commit: r894641 [1/4] - in /websites/production/tapestry/content:
cache/main.pageCache component-parameters.html configuration.html
download.html exploring-the-project.html type-coercion.html
using-tapestry-with-hibernate.html
Author: buildbot
Date: Sat Jan 18 17:20:52 2014
New Revision: 894641
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/component-parameters.html
websites/production/tapestry/content/configuration.html
websites/production/tapestry/content/download.html
websites/production/tapestry/content/exploring-the-project.html
websites/production/tapestry/content/type-coercion.html
websites/production/tapestry/content/using-tapestry-with-hibernate.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/component-parameters.html
==============================================================================
--- websites/production/tapestry/content/component-parameters.html (original)
+++ websites/production/tapestry/content/component-parameters.html Sat Jan 18 17:20:52 2014
@@ -29,6 +29,7 @@
<link href='http://cxf.apache.org/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
<script src='http://cxf.apache.org/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
<script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
<script type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -112,7 +113,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="component-classes.html">Component Classes</a>
+ <a shape="rect" href="default-parameter.html">Default Parameter</a>
</div>
@@ -121,7 +122,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="default-parameter.html">Default Parameter</a>
+ <a shape="rect" href="supporting-informal-parameters.html">Supporting Informal Parameters</a>
</div>
@@ -130,7 +131,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="supporting-informal-parameters.html">Supporting Informal Parameters</a>
+ <a shape="rect" href="enum-parameter-recipe.html">Enum Parameter Recipe</a>
</div>
@@ -139,7 +140,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="enum-parameter-recipe.html">Enum Parameter Recipe</a>
+ <a shape="rect" href="templating-and-markup-faq.html">Templating and Markup FAQ</a>
</div>
@@ -148,55 +149,30 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="templating-and-markup-faq.html">Templating and Markup FAQ</a>
+ <a shape="rect" href="component-classes.html">Component Classes</a>
</div>
</li></ul>
-</div>
+</div><h1 id="ComponentParameters-ComponentParameters">Component Parameters</h1><p><style type="text/css">/*<![CDATA[*/
+div.rbtoc1390065642668 {padding: 0px;}
+div.rbtoc1390065642668 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1390065642668 li {margin-left: 0px;padding-left: 0px;}
-<h1 id="ComponentParameters-ComponentParameters">Component Parameters</h1>
-<style type="text/css">/*<![CDATA[*/
-div.rbtoc1387423369011 {padding: 0px;}
-div.rbtoc1387423369011 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1387423369011 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style><div class="toc-macro rbtoc1387423369011">
+/*]]>*/</style></p><div class="toc-macro rbtoc1390065642668">
<ul class="toc-indentation"><li>Related Articles</li></ul>
<ul><li><a shape="rect" href="#ComponentParameters-ComponentParameters">Component Parameters</a></li><li><a shape="rect" href="#ComponentParameters-ParameterBindings">Parameter Bindings</a></li><li><a shape="rect" href="#ComponentParameters-BindingExpressions">Binding Expressions</a>
<ul class="toc-indentation"><li><a shape="rect" href="#ComponentParameters-RenderVariables:Bindings">Render Variables: Bindings</a></li><li><a shape="rect" href="#ComponentParameters-Property:Bindings">Property: Bindings</a></li><li><a shape="rect" href="#ComponentParameters-Validate:Bindings">Validate: Bindings</a></li><li><a shape="rect" href="#ComponentParameters-Translate:Bindings">Translate: Bindings</a></li><li><a shape="rect" href="#ComponentParameters-Asset:Bindings">Asset: Bindings</a></li><li><a shape="rect" href="#ComponentParameters-Context:Bindings">Context: Bindings</a></li></ul>
</li><li><a shape="rect" href="#ComponentParameters-@Parameterannotation">@Parameter annotation</a>
<ul class="toc-indentation"><li><a shape="rect" href="#ComponentParameters-RequiredParameters">Required Parameters</a></li><li><a shape="rect" href="#ComponentParameters-OptionalParameters">Optional Parameters</a></li><li><a shape="rect" href="#ComponentParameters-ParameterBindingDefaults">Parameter Binding Defaults</a></li><li><a shape="rect" href="#ComponentParameters-ParameterCaching">Parameter Caching</a></li></ul>
</li><li><a shape="rect" href="#ComponentParameters-Don'tusethe${...}syntax!">Don't use the ${...} syntax!</a></li><li><a shape="rect" href="#ComponentParameters-InformalParameters">Informal Parameters</a></li><li><a shape="rect" href="#ComponentParameters-ParametersAreBi-Directional">Parameters Are Bi-Directional</a></li><li><a shape="rect" href="#ComponentParameters-InheritedParameterBindings">Inherited Parameter Bindings</a></li><li><a shape="rect" href="#ComponentParameters-ComputedParameterBindingDefaults">Computed Parameter Binding Defaults</a></li><li><a shape="rect" href="#ComponentParameters-UnboundParameters">Unbound Parameters</a></li><li><a shape="rect" href="#ComponentParameters-ParameterTypeCoercion">Parameter Type Coercion</a></li><li><a shape="rect" href="#ComponentParameters-ParameterNames">Parameter Names</a></li><li><a shape="rect" href="#ComponentParameters-DeterminingifBound">Determining if Bound</a></li><li><a shape="rect" href="#ComponentParameters-PublishingP
arameters">Publishing Parameters</a></li></ul>
-</div>
-
-<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>
-
-<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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</div><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><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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<t:pagelink page="Index">Go Home</t:pagelink>
</html>
]]></script>
-</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 shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Parameter.html">Parameter</a> annotation on a private field.</p>
-
-<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. In most simple examples, the component's container is the page, but since components can be nested, often the container of a component is another component.</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>
-
-<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[
-package org.example.app.components;
+</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 shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Parameter.html">Parameter</a> annotation on a private field.</p><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. In most simple examples, the component's container is the page, but since components can be nested, often the container of a component is another component.</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><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[package org.example.app.components;
import org.apache.tapestry5.annotations.AfterRender;
import org.apache.tapestry5.annotations.Parameter;
@@ -248,158 +224,45 @@ public class Count
}
}
]]></script>
-</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><span class="confluence-anchor-link" id="ComponentParameters-bindingparameters"></span></p>
-
-<h1 id="ComponentParameters-ParameterBindings">Parameter Bindings</h1>
-
-<p>The component above can be referenced in another component or page <a shape="rect" 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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<html t:type="layout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</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><span class="confluence-anchor-link" id="ComponentParameters-bindingparameters"></span></p><h1 id="ComponentParameters-ParameterBindings">Parameter Bindings</h1><p>The component above can be referenced in another component or page <a shape="rect" 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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<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>
]]></script>
-</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 shape="rect" href="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 shape="rect" 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 value, 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 shape="rect" 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 shape="rect" href="#ComponentParameters-localization.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 shape="rect" 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 shape="rect" 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 shape="rect" href="#ComponentParameters-dontUseSyntax">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 shape="rect" href="#ComponentParameters-InheritedParameterBindings">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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<ul>
+</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 shape="rect" href="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 shape="rect" 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 f
ront of the value, 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><t
d 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 shape="rect" 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 shape="rect" href="#ComponentParameters-localization.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 shape="rect" href="prop
erty-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 shape="rect" 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 inst
ance 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 shape="rect" href="#ComponentParameters-dontUseSyntax">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 shape="rect" href="#ComponentParameters-InheritedParameterBindings">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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<ul>
<li t:type="loop" source="1..10" value="index">${index}</li>
</ul>
]]></script>
-</div></div>
-<p>and the following Java code:</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[
-@Property
+</div></div><p>and the following Java code:</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[@Property
private int index;
]]></script>
-</div></div>
-<p>... could be rewritten as just:</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<ul>
+</div></div><p>... could be rewritten as just:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<ul>
<li t:type="loop" source="1..10" value="var:index">${var:index}</li>
</ul>
]]></script>
-</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 shape="rect" 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:Bindings">Validate: Bindings</h3>
-
-<p>Main Article: <a shape="rect" 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 the name of a configured <a shape="rect" 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 shape="rect" 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 shape="rect" 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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
- <img src="${context:images/icon.png}"/>
+</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 shape="rect" 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:Bindings">Validate: Bindings</h3><p>Main Article: <a shape="rect" 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 i
nput validation. It is the name of a configured <a shape="rect" 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 shape="rect" 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 shape="rect" 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 th
e 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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <img src="${context:images/icon.png}"/>
]]></script>
-</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">
+</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">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class Component{
@Parameter(required = true)
private String parameter;
}]]></script>
-</div></div>
-
- <div class="aui-message success shadowed information-macro">
+</div></div> <div class="aui-message success shadowed information-macro">
<span class="aui-icon icon-success">Icon</span>
<div class="message-content">
-
-<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 shape="rect" 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>
+ <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 shape="rect" 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">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-@Parameter(value="defaultMessage") // or, equivalently, @Parameter("defaultMessage")
+<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">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[@Parameter(value="defaultMessage") // or, equivalently, @Parameter("defaultMessage")
private String message;
@Parameter(required=true)
@@ -410,76 +273,20 @@ public String getDefaultMessage(){Â
}
]]></script>
-</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 shape="rect" href="component-templates.html#ComponentTemplates-Expansions">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 (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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<t:textfield t:id="color" value="color"/>
+</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 shape="rect" href="component-templates.html#ComponentTemplates-Expansions">Component Templates#Expansions</a></p><p>You generally should <em>not</em> use the Template Expansion syntax, ${...}, within component parameter bindings. Doi
ng so results in the property inside the braces 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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<t:textfield t:id="color" value="color"/>
]]></script>
-</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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<t:textfield t:id="color" value="${color}"/>
+</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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<t:textfield t:id="color" value="${color}"/>
]]></script>
-</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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<img src="${context:images/banner.png}"/>
+</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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<img src="${context:images/banner.png}"/>
]]></script>
-</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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<img src="context:images/banner.png"/>
+</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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<img src="context:images/banner.png"/>
]]></script>
-</div></div></div></div></div></div>
-
-<h1 id="ComponentParameters-InformalParameters">Informal Parameters</h1>
-
-<p>Main Article: <a shape="rect" 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 shape="rect" 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 shape="rect" 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 shape="rect" 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 shape="rect" 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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<t:layout xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</div></div></div></div></div></div><h1 id="ComponentParameters-InformalParameters">Informal Parameters</h1><p>Main Article: <a shape="rect" 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 shape="rect" 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 ann
otation.</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 shape="rect" 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 shape="rect" 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 shape="rect" 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-wid
th: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<t:layout xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<p> Countdown:
<t:count start="5" end="1" result="index">
${index} ...
@@ -487,31 +294,11 @@ public String getDefaultMessage(){Â
</p>
</t:layout>
]]></script>
-</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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
- <p> Countdown: 5 ... 4 ... 3 ... 2 ... 1 ... </p>
+</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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <p> Countdown: 5 ... 4 ... 3 ... 2 ... 1 ... </p>
]]></script>
-</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="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Index.tml</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<body>
<div t:type="layout" t:menuTitle="literal:The Title">
...
@@ -519,12 +306,8 @@ public String getDefaultMessage(){Â
</body>
</html>
]]></script>
-</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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<t:container xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<t:container xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<div t:type="title" t:title="inherit:menuTitle"></div>
@@ -532,12 +315,8 @@ public String getDefaultMessage(){Â
</t:container>
]]></script>
-</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">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-package org.example.app.components;
+</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">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[package org.example.app.components;
import org.apache.tapestry5.annotations.Parameter;
@@ -548,19 +327,8 @@ public class Title {
}
]]></script>
-</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 shape="rect" 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">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @Parameter
+</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 shape="rect" 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">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Parameter
private String message;
@Parameter(required=true)
@@ -582,15 +350,8 @@ public class Title {
return String.format("Maximum field length is %d.", maxLength);
}
]]></script>
-</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">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @Parameter
+</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">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Parameter
private String message;
@Parameter(required=true)
@@ -604,41 +365,8 @@ public class Title {
return String.format("Maximum field length is %d.", maxLength);
}
]]></script>
-</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 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>
-
-<p><strong>TODO: This seems contradictory. What does it mean to update an unbound component parameter when the component is not rendering?</strong></p>
-
-<h1 id="ComponentParameters-ParameterTypeCoercion">Parameter Type Coercion</h1>
-
-<p>Tapestry includes a mechanism for <a shape="rect" href="type-coercion.html">coercing types automatically</a>. Most often, this is used to convert literal strings into appropriate values, but in many cases, more complex conversions will occur.</p>
-
-<h1 id="ComponentParameters-ParameterNames">Parameter Names</h1>
-
-<p>By default, Tapestry converts from the field name to the parameter name, by stripping 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 shape="rect" href="injection.html">injected</a> into the component using the @<a shape="rect" 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">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class MyComponent
+</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><p><strong>TODO: This seems contradictory. What does it mean to update an unbound component parameter when the component is not rendering?</strong></p><h1 id="ComponentParameters-ParameterTypeCoercion">Parameter Type Coercion</h1><p>Tapestry includes a mechanism for <a shape="rect" href="type-coercion.html">coercing types automatically</a>. Most often, this is used to convert literal strings into appropriate values, but in many cases, more complex conversions will occur.</p><h1 id="ComponentParameters-ParameterNames">Parameter Names</h1><p>By default, Tapestry converts from the field name to the parameter name, by stripping off leading "$" and "_" characters.</p><p>This can be overridden using the name() attribute of the @Parameter annotation.</p><h1 id="ComponentParameters-DeterminingifBound">Determining i
f 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 shape="rect" href="injection.html">injected</a> into the component using the @<a shape="rect" 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">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class MyComponent
{
@Parameter
private int myParam;
@@ -656,43 +384,21 @@ public class MyComponent
}
}
]]></script>
-</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 shape="rect" 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 shape="rect" 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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<t:container xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+</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 shape="rect" 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 componen
t, 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 shape="rect" 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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<t:container xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<t:pageLink t:id="link">Page Link</t:pageLink>
</t:container>
]]></script>
-</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">
+</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">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class ContainerComponent{
-@Component(id="link", publishParameters="page")
-private PageLink link;
+ @Component(id="link", publishParameters="page")
+ private PageLink link;
}
]]></script>
-</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">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<t:ContainerComponent t:id="Container" t:page="About" />
+</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">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<t:ContainerComponent t:id="Container" t:page="About" />
]]></script>
-</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>
+</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>
</div>
<div class="clearer"></div>