THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
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.
| Div | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
| Wiki Markup |
|---|
{float:right}
{panel:background=#eee}
{contentbylabel:title=Related Articles|showLabels=false|showSpace=false|space=@self|labels=expressions,component-classes,component-templates,parameters}
{panel}
*Contents*
{toc}
{float} |
...
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:
| Code Block | ||
|---|---|---|
| ||
<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_34.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, as we'll see below.
| Anchor | ||||
|---|---|---|---|---|
|
...
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.(Components can be nested, so the container can be either the page or another component.)
| Wiki Markup |
|---|
{float:right}
{panel:title=Contents|background=#eee}
{toc:minLevel=1|maxLevel=2}
{panel}
{float} |
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.
...
| Code Block | ||
|---|---|---|
| ||
<html t:type="layout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_34.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.
...
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 locate a pre-defined NullFieldStrategy |
message: | Retrieves a string from the component's message catalog |
prop: | A property expression to read or update |
symbol: | Used to read one of your symbols |
translate: | The name of a configured translator |
validate: | A validator specification used to create some number of field validators |
var: | Allows a render variable of the component to be read or updated |
...
Render variable names are case insensitive.
Property: Bindings
Main Article: Property Expressions
The "prop:" binding prefix indicates a property expression binding.
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 Property Expressions.
The default binding prefix in most cases is "prop:", which is why it is usually omitted.
...
The list of available translators is configured by the TranslatorSource service.
Asset: Bindings
Main Article: Assets
Assets bindings are used to specify Assets Component Parameters, 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).
Context: Bindings
Main Article: Assets
Context bindings are like asset bindings, but the path is always relative to the root of the web application context. This is intended for use inside templates, i.e.:
...
Don't use the ${...} syntax!
Main Article: Component Templates#Expansions 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).
...
If your component should render informal parameters, just inject the ComponentResources for your component and invoke the renderInformalParameters() method. See See Supporting Informal Parameters for an example of how to do this.
...
| Code Block | ||
|---|---|---|
| ||
<t:layout xmlns:t="http://tapestry.apache.org/schema/tapestry_5_34.xsd"> <p> Countdown: <t:count start="5" end="1" result="index"> ${index} ... </t:count> </p> </t:layout> |
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_34.xsd"> <body> <div t:type="layout" t:menuTitle="literal:The Title"> ... </div> </body> </html> |
| Code Block | ||||
|---|---|---|---|---|
| ||||
<t:container xmlns:t="http://tapestry.apache.org/schema/tapestry_5_34.xsd"> <div t:type="title" t:title="inherit:menuTitle"></div> <t:body /> </t:container> |
...
Parameter Type Coercion
Main Article: Parameter Type Coercion
Tapestry includes a mechanism for coercing types automatically. Most often, this is used to convert literal strings into appropriate values, but in many cases, more complex conversions will occur. This mechanism is used for component parameters, such as when an outer component passes a literal string to an inner component that is expecting an integer.
...
| Code Block | ||
|---|---|---|
| ||
public class MyComponent
{
@Parameter
private int myParam;
@Inject
private ComponentResources resourcescomponentResources;
@BeginRender
void setup()
{
if (resourcescomponentResources.isBound("myParam"))
{
. . .
}
}
}
|
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<t:container xmlns:t="http://tapestry.apache.org/schema/tapestry_5_34.xsd"> <t:pageLink t:id="link">Page Link</t:pageLink> </t:container> |
...
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.
| Scrollbar |
|---|