[CONF] Apache Tapestry Component Parameters
Component Parameters
Page edited by Bob Harner
Comment:
inherited
Changes (1)
...
You may set a default value for optional parameters using thenbsp;{{value}}nbsp;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.
{anchor:Inherited_Parameter_Bindings}
h3. Parameter Binding Defaults
...
Full Content
Related Articles
Page:
Component Parameters
Page:
Component Templates
Page:
Page And Component Classes FAQ
Page:
Enum Parameter Recipe
Page:
Templating and Markup FAQ
Page:
Default Parameter
Page:
Supporting Informal Parameters
Page:
Component Classes
Page:
Component Cheat Sheet
Component Parameters
Component Parameters
Parameter Bindings
Binding Expressions
Render Variables: Bindings
Property: Bindings
Validate: Bindings
Translate: Bindings
Asset: Bindings
Context: Bindings
@Parameter annotation
Required Parameters
Optional Parameters
Parameter Binding Defaults
Parameter Caching
Don't use the ${...} syntax!
Informal Parameters
Parameters Are Bi-Directional
Inherited Parameter Bindings
Computed Parameter Binding Defaults
Unbound Parameters
Parameter Type Coercion
Parameter Names
Determining if Bound
Publishing Parameters
Component parameters are the primary means for a component instance and its container to communicate with each other. Parameters are used to configure component instances.
In the following example, page is a parameter of the pagelink component. The page parameter tells the pagelink component which page to go to when the user clicks on the rendered hyperlink:
html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd"
t:pagelink page="Index"Go Home/t:pagelink
/html
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 optional or required.
Within a component class, parameters are declared by using the @Parameter annotation on a private field.
In Tapestry, a parameter is not a slot into which data is pushed: it is a connection 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.
The connection between a component and a property (or resource) of its container is called a binding. 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.
This is important in a lot of cases; for example a TextField component can read and update the property bound to its value parameter. It reads the value when rendering, but updates the value when the form is submitted.
The component listed below is a looping component; it renders its body a number of times, defined by its start and end parameters (which set the boundaries of the loop). The component can update a result parameter bound to a property of its
[CONF] Apache Tapestry Component Parameters
Component Parameters
Page edited by Bob Harner
Comment:
Added note about what happens when an informal parameter is bound to null
Changes (4)
...
h1. Informal Parameters
Some components support _informal parameters_, 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.
Main Article: [Supporting Informal Parameters]
Many components support _informal parameters_, 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.
Only components whose class is annotated with @[SupportsInformalParameters|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SupportsInformalParameters.html] will support informal parameters. Tapestry silently drops informal parameters that are specified for components that do not have this annotation.
...
The default binding prefix for informal parameters depends on _where_ the parameter binding is specified. If the parameter is bound inside a Java class, within the @[Component|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html] 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.
Informal parameters (if supported) are always rendered into the output _unless_ they are bound to a property whose value is null. If the bound property is null then the parameter will _not_ be present at all in the rendered output.
If your component should render informal parameters, just inject the [ComponentResources|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html] for your component and invoke the {{renderInformalParameters()}} method. See [Supporting Informal Parameters] for an example of how to do this.
...
Full Content
Related Articles
Page:
Component Parameters
Page:
Component Templates
Page:
Page And Component Classes FAQ
Page:
Supporting Informal Parameters
Page:
Enum Parameter Recipe
Page:
Templating and Markup FAQ
Page:
Default Parameter
Page:
Component Classes
Page:
Component Cheat Sheet
Component Parameters
Component Parameters
Parameter Bindings
Binding Expressions
Render Variables: Bindings
Property: Bindings
Validate: Bindings
Translate: Bindings
Asset: Bindings
Context: Bindings
@Parameter annotation
Required Parameters
Optional Parameters
Parameter Binding Defaults
Parameter Caching
Don't use the ${...} syntax!
[CONF] Apache Tapestry Component Parameters
Component Parameters
Page edited by DEMEY Emmanuel
Changes (7)
...
h1. Component Parameters
{toc}
*Component parameters* are the primary means for a component instance and its container to communicate with each other. Parameters are used to _configure_ component instances.
...
A _special prefix_, inherit:, is used to support [Inherited Parameter Bindings|#Inherited_Parameter_Bindings].
h3. Render variables
h3. Render Variables: Bindings
Components can have any number ofnbsp;_render variables_. 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.
...
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 applications 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.
h1. @Parameter annotation h3. Required Parameters Parameters that are requirednbsp;*must*nbsp;be bound. A runtime exception occurs if a component has unbound required parameters. {code}public class Component{@Parameter(required = true) private String parameter; }{code} {tip} 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 components value parameter, which may have its underlying value set bynbsp;[contributing a ValueEncoderSource|Using Select With a List]. Be sure to read the components 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).{tip} h3. Optional Parameters Parameters are optional unless they are marked as required. You may set a default value for optional parameters using thenbsp;{{value}}nbsp;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. {anchor:Inherited_Parameter_Bindings} h3. Parameter Binding Defaults The @Parameter annotationsnbsp;{{value}}nbsp;element can be used to specify anbsp;_binding expression_nbsp;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. {code:java} @Parameter(value=defaultMessage) // or, equivalently, @Parameter(defaultMessage) private String message; @Parameter(required=true) private int maxLength; public String getDefaultMessage(){ return String.format(Maximum field length is %d., maxLength); } {code} As elsewhere, you may use a prefix on the value. A common prefix to use is the message: prefix, to access a localized message. h3. Parameter Caching 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. 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.
h1. Dont use the $\{...\} syntax\!
...
The relevant part is that components can read fixed values, or _live_ properties of their container, and can _change_ properties of their container as well.
h1. Required Parameters Parameters that are required *must* be bound. A runtime exception occurs if a component has unbound required parameters. {tip} 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 components value parameter, which may have its underlying value set by [contributing a ValueEncoderSource|Using Select With a List]. Be sure to read the components 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). {tip} h1. Optional Parameters Parameters are optional unless they are marked as required. You may set a default value for optional parameters using the {{value}} 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.
[CONF] Apache Tapestry Component Parameters
Component Parameters
Page edited by Bob Harner
Comment:
Changed example to use a property named "result" instead of "value", because "value" has so many other meanings on this page.
Changes (26)
...
This is important in a lot of cases; for example a TextField component can read _and update_ the property bound to its value parameter. It reads the value when rendering, but updates the value when the form is submitted.
The component listed below is a looping component; it renders its body a number of times, defined by its start and end parameters (which set the boundaries of the loop). The component can update a value result parameter bound to a property of its container,; it will automatically count up or down depending on whether start or end is larger.
{code:java}
...
public class Count {
@Parameter private int start = 1;
@Parameter (value=1) private int start;
@Parameter(required = true)
...
@Parameter
private int value; result;
private boolean increment; @SetupRender
void initializeValues()
{
value result = start;
increment = start end; }
...
if (increment) {
int newValue newResult = value + 1;
if (newValue (newResult = end)
{
value = newValue;
result = newResult;
return false; }
...
else {
int newValue = newResult= value - 1;
if (newValue = end)
if (newResult= end)
{
value = newValue;
result = newResult;
return false; } }
return true; }
...
{code}
The name of the parameter is derived from the field name (by stripping leading _ and $ characters). Here, the parameter names are start, end and value.
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.
{anchor:bindingparameters}
...
| literal: | A literal string. | | nullfieldstrategy: | Used to locate a pre-defined [NullFieldStrategy|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/NullFieldStrategy.html] |
| message: | Retrieves a value string from the components [message catalog|#localization.html] |
| prop: | A [property _expression_|Property Expressions] to read or update | | symbol: | Used to read one of your [symbols|TAPESTRY:Symbols] |
...
t:layout xmlns:t=http://tapestry.apache.org/schema/tapestry_5_1_0.xsd p Countdown:
t:count start=5 end=1 value=index result=index
${index} ... /t:count
...
{code}
Because the Count component updates its value result parameter (the \_value {{result}} field), the index property of the containing component is updated. Inside the Counts body, we output the current value of the index property, using the expansion {{$\{index\}}}. The resulting output will look something like:
{code:xml}
...
Parameters are optional unless they are marked as required.
You may set a default value for optional parameters as you would for any other field. In the Count component, the min parameter has a default value of 1. That value is used unless the min parameter is bound, in which case, the bound value supersedes the default.
You may set a default value for optional parameters using the {{value}} 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.
{anchor:Inherited_Parameter_Bindings}
...
h1. Parameter Binding Defaults
The @Parameter annotations value() attribute {{value}} element can be used to specify a _binding expression_ that will be the default binding for the parameter isf otherwise left unbound. Typically, this is the name of a property that that will compute the value on the fly.
Example: {code:java}
@Parameter(defaultMessage)
[CONF] Apache Tapestry Component Parameters
Component Parameters
Page edited by Bob Harner
Comment:
Added "Don't use the ${...} syntax" section, other tweaks
Changes (25)
...
{anchor:bindingparameters}
h1. Binding Parameters
h1. Parameter Bindings
The component above can be referenced in another component or page [template|Component Templates], and its parameters _bound_:
{code:xml}
...
Any number of parameters may be bound this way.
Component parameters may also be bound using the @[Component|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html] annotation inside the component class. (Where conflicts occur, the parameters bound using the Component annotation will take precedence over parameter bindings in the template.)
Where conflicts occur, the parameters bound using the Component annotation will take precedence over parameter bindings in the template.
{anchor:binding-expressions}
h1. Using Binding Expressions
The value inside the template, 3 in the previous example, is a _binding expression_.
...
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 containers 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.
Only prop: and var: binding prefixes are updateable.
Only prop: and var: binding prefixes are updateable (but you must _not_ use the $\{..\} syntax here; see the next section).
Parameters have a default prefix, usually prop:, that is used when the prefix is not provided.
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:.
A _special prefix_, inherit:, is used to support [Inherited Parameter Bindings|#Inherited_Parameter_Bindings].
h1. Render Variables
h1. Dont use the $\{...\} syntax!
Main Article: [Component Templates#Expansions] You generally should _not_ 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 {{prop:}} or {{var:}}, since such component parameters are _two-way_ bindings). {section} {column} {code:title=This is right} t:textfield t:id=color value=color/ {code} {column} {column} {code:title=This is wrong} t:textfield t:id=color value=${color}/ {code} {column} {section} 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. {section} {column} {code:title=This is right} img src="" {code} {column} {column} {code:title=This is wrong} img src="" {code} {column} {section} h1. Render variables
Components can have any number of _render variables_. 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.
For example:
For example, the following template code:
{code:xml}
...
{code}
And in the Java code:
and the following Java code:
{code:java}
...
{code}
In other words, you dont have to define a property in the Java code. The disadvantage is that render variables dont work with the property _expression_ syntax, so you can pass around a render variables _value_ but you cant reference any of the values properties.
Render variables are automatically cleared when a component finishes rendering.
...
The default binding prefix in most cases is prop:, which is why it is usually omitted.
h1. Validate: Bindings
Main Article: [Forms and Validation]
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.
The string is a comma-separated list of _validator
[CONF] Apache Tapestry Component Parameters
Component Parameters
Page edited by DEMEY Emmanuel
Changes (2)
...
In Tapestry 5.1 and later, you may use the publishParameters attribute of the @[Component|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html] annotation. List one or more parameters separated by commas: those parameters of the inner/embedded component become parameters of the outer component. You should *not* define a parameter field in the outer component.
| {code:lang=html|title=ContainerComponent.tml}t:container xmlns:t=http://tapestry.apache.org/schema/tapestry_5_1_0.xsd
t:pageLink t:id=linkPage Link/t:pageLink /t:container {code} | {code:title=ContainerComponent.java}public class ContainerComponent{ @Component(id=link, publishParameters=page) private PageLink link; } {code}\\ | | {code:lang=html|title=Index.tml}t:ContainerComponent t:id=Container t:page=About / {code}\\ | |
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.
Full Content
Related Articles
Page:
Component Parameters
Page:
Component Templates
Page:
Default Parameter
Page:
Supporting Informal Parameters
Page:
Page And Component Classes FAQ
Page:
Component Classes
Page:
Templating and Markup FAQ
Page:
Enum Parameter Recipe
Page:
Component Cheat Sheet
Component Parameters
Component parameters are a critical aspect of Tapestry. It is not enough that an instance of a component class exists, it must be configured to do the right thing. Configuration is in terms of the parameters of the component.
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 optional or required.
Parameters are defined by using the @Parameter annotation on a private field.
In Tapestry, a parameter is not a slot into which data is pushed: it is a connection 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 container is the page, but since components can have themselves have templates, sometime the container of a component is another component.
The connection is called a binding. 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.
This is important in a lot of cases; for example a TextField component can read and update the property bound to its value parameter. It reads the value when rendering, but updates the value when the form is submitted.
The component listed below is a looping component; it renders its body a number of times, defined by its start and end parameters (which set the boundaries of the loop). The component can update a value parameter bound to a property of its container, it will automatically count up or down depending on whether start or end is larger.
package org.example.app.components;
import org.apache.tapestry5.annotations.AfterRender;
[CONF] Apache Tapestry Component Parameters
Component Parameters
Page edited by DEMEY Emmanuel
Changes (4)
...
{code}
Because the Count component updates its value parameter (the \_value field), the index property of the containing component is updated. Inside the Counts body, we output the current value of the index property, using the expansion {{$\{index\}}}. The resulting output will look something like:
{code:xml}
...
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.
More examples on this coming soon.
{code:xml|title=Index.tml} html xmlns:t=http://tapestry.apache.org/schema/tapestry_5_1_0.xsd body div t:type=layout t:menuTitle=literal:The Title ... /div /body /html {code}
{code:xml|title=Layout.tml} t:container xmlns:t=http://tapestry.apache.org/schema/tapestry_5_1_0.xsd div t:type=title t:title=inherit:menuTitle/div t:body / /t:container {code} {code:java|title=Title.java} package org.example.app.components; import org.apache.tapestry5.annotations.Parameter; public class Title { @Parameter private String title; } {code}
h1. Parameter Binding Defaults
...
Full Content
Related Articles
Page:
Component Parameters
Page:
Component Templates
Page:
Page And Component Classes FAQ
Page:
Templating and Markup FAQ
Page:
Component Classes
Page:
Enum Parameter Recipe
Page:
Component Cheat Sheet
Page:
Supporting Informal Parameters
Page:
Default Parameter
Component Parameters
Component parameters are a critical aspect of Tapestry. It is not enough that an instance of a component class exists, it must be configured to do the right thing. Configuration is in terms of the parameters of the component.
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 optional or required.
Parameters are defined by using the @Parameter annotation on a private field.
In Tapestry, a parameter is not a slot into which data is pushed: it is a connection 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 container is the page, but since components can have themselves have templates, sometime the container of a component is another component.
The connection is called a binding. 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.
This is important in a lot of cases; for example a TextField component can read and update the property bound to its value parameter. It reads the value when rendering, but updates the value when the form is submitted.
The component listed below is a looping component; it renders its body a number of times, defined by its start and end parameters (which set the boundaries of the loop). The component can update a value parameter bound to a property of its container, it will automatically count up or down depending on whether start or end is larger.
package org.example.app.components;
import
[CONF] Apache Tapestry Component Parameters
Component Parameters
Page edited by Bob Harner
Comment:
Combined the mostly-redundant "Informal Parameters" and "Supporting Informal Parameters" sections.
Changes (4)
...
Some components support _informal parameters_, 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.
Only components whose class is annotated with [...@supportsinformalparameters|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SupportsInformalParameters.html] will support informal parameters. Tapestry silently drops informal parameters that are specified for components that do not have this annotation.
Informal parameters are often used to set the CSS class of an element, or to specify client-side event handlers.
The default binding prefix for informal parameters depends on _where_ the parameter binding is specified. If the parameter is bound inside a Java class, within the [...@component|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html] 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.
If your component should render informal parameters, just inject the [ComponentResources|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html] for your component and invoke the {{renderInformalParameters()}} method.
h1. Asset Bindings
...
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 applications 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.
h1. Supporting Informal Parameters *Only* components which area annotated with [...@supportsinformalparameters|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SupportsInformalParameters.html] may have informal parameters. Tapestry silently drops informal parameters that are specified for components that do not have this annotation. To render informal parameters, inject the [ComponentResources|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html] for your component and invoke the {{renderInformalParameters()}} method.
h1. Parameters Are Bi-Directional
...
In Tapestry 5.0, you would define a parameter of the outer component, and use the inherit: binding prefix to connect the inner components parameter to the outer components 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.
In Tapestry 5.1 and later, you may use the publishParameters attribute of the [...@component|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html] annotation. List one or more parameters separated by commas: those parameters of the inner/embedded component become parameters of the outer component. You should *not* define a parameter field in the outer component.
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.
Full Content
Related Articles
Component Parameters
Component Templates
Page And Component Classes
[CONF] Apache Tapestry Component Parameters
Component Parameters
Page edited by Ulrich Stärk
Changes (1)
...
| nullfieldstrategy | Used to locate a pre-defined [NullFieldStrategy|../apidocs/org/apache/tapestry5/NullFieldStrategy.html] | | message | Retrieves a value from the components [message catalog|#localization.html]. |
{deprecated:since=5.2}| {deprecated-part}| prop | A [property _expression_|#propexp.html] to read or update. |{deprecated-part}
| translate | The name of a configured translator. | | validate | A _validator specification_ used to create some number of field validators. |
...
Full Content
Component Parameters
Component parameters are a critical aspect of Tapestry. It is not enough that an instance of a component class exists, it must be configured to do the right thing. Configuration is in terms of the parameters of the component.
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 optional or required.
Parameters are defined by placing a Parameter|../apidocs/org/apache/tapestry5/annotations/Parameter.html annotation onto a private field.
In Tapestry, a parameter is not a slot into which data is pushed: it is a connection 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 container is the page, but since components can have themselves have templates, sometime the container of a component is another component.
The connection is called a binding. 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.
This is important in a lot of cases; for example a TextField component can read and update the property bound to its value parameter. It reads the value when rendering, but updates the value when the form is submitted.
The component listed below is a looping component; it renders its body a number of times, defined by its start and end parameters (which set the boundaries of the loop). The component can update a value parameter bound to a property of its container, it will automatically count up or down depending on whether start or end is larger.
package org.example.app.components;
import org.apache.tapestry5.annotations.AfterRender;
import org.apache.tapestry5.annotations.Parameter;
import org.apache.tapestry5.annotations.SetupRender;
public class Count
{
@Parameter
private int start = 1;
@Parameter(required = true)
private int end;
@Parameter
private int value;
private boolean increment;
@SetupRender
void initializeValue()
{
value = start;
increment = start end;
}
@AfterRender
boolean next()
{
if (increment)
{
int newValue = value + 1;
if (newValue = end)
{
value = newValue;
return false;
}
}
else
{
int newValue = value - 1;
if (newValue = end)
{
value = newValue;
return false;
}
}
return true;
}
}
The name of the parameter is derived from the field name (by stripping leading "_" and "$" characters). Here, the parameter names are "start", "end" and "value".
Binding Parameters
The component above can be referenced in another component or page template:
html t:type="layout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"
p Merry Christmas: t:count end="3" Ho! /t:count
/p
/html
The end attribute is used to bind the end parameter of the Count component. Here, it is being bound to the string value "3", which is automatically coerced by Tapestry into the int value, 3.
Any number of parameters may be bound this way.
Component parameters may also be bound using the Component annotation inside the component class.
Where conflicts occur, the parameters bound using the Component annotation will take precendence over parameter bindings in the template.
Binding Expressions
The value inside the template, "3" in the previous example, is a binding _expression_.
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):
Prefix
Description
asset
The relative path to an asset file (which must exist).
block
The id of a block within the template.
component
The id of another component within the same template.
context
Context asset: path from context root.
literal
A literal string.
nullfieldstrategy
Used to
