THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
| Anchor | ||||
|---|---|---|---|---|
|
...
Binding Expressions
The value inside the template, "3" in the previous example, is a binding expression.
...
A special prefix, "inherit:", is used to support Inherited Parameter Bindings.
Don't 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).
...
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, the following template code:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<ul>
<li t:type="loop" source="1..10" value="index">${index}</li>
</ul>
|
and the following Java code:
| Code Block | ||||
|---|---|---|---|---|
| ||||
@Property
private int index;
|
... could be rewritten as just:
...
<t:textfield t:id="color" value="color"/>
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
| title | This is wrong |
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.
...
var:index">${var:index}</li>
</ul>
|
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 value but you can't reference any of the value's properties.
Render variables are automatically cleared when a component finishes rendering.
Render variable names are case insensitive.
Property: Bindings
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. SeeProperty Expressions.
The default binding prefix in most cases is "prop:", which is why it is usually omitted.
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 types. 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.
For example: validate:required,minLength=5 would presumably enforce that a field requires a value, with at least five characters.
Translate: Bindings
The "translate:" binding prefix is also related to input validator. It is the name of a configured Translator, responsible for converting between server-side and client-side representations of data (for instance, between client-side strings and server-side numeric values).
The list of available translators is configured by the TranslatorSource service.
Asset: Bindings
Assets bindings are normally relative to the component class. 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 binding prefix for that purpose exists (described below).
Context: Bindings
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.:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<img src="${context:images/icon.png}"/>
|
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.
Don't 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 | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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 | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
Only components whose class is annotated with @SupportsInformalParameters 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 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 for your component and invoke the renderInformalParameters() method. See Supporting Informal Parameters for an example of how to do this
...
<img src="${context:images/banner.png}"/>
...
<img src="context:images/banner.png"/>
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, the following template code:
...
<ul>
<li t:type="loop" source="1..10" value="index">${index}</li>
</ul>
and the following Java code:
...
@Property
private int index;
... could be rewritten as just:
...
<ul>
<li t:type="loop" source="1..10" value="var:index">${var:index}</li>
</ul>
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 value but you can't reference any of the value's properties.
Render variables are automatically cleared when a component finishes rendering.
Render variable names are case insensitive.
Property Expression Bindings
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.
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 types. 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.
For example: validate:required,minLength=5 would presumably enforce that a field requires a value, with at least five characters.
translate: Bindings
The "translate:" binding prefix is also related to input validator. It is the name of a configured Translator, responsible for converting between server-side and client-side representations of data (for instance, between client-side strings and server-side numeric values).
The list of available translators is configured by the TranslatorSource service.
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.
Only components whose class is annotated with @SupportsInformalParameters 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 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 for your component and invoke the renderInformalParameters() method. See Supporting Informal Parameters for an example of how to do this.
asset: Bindings
Assets bindings are normally relative to the component class. 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 binding prefix for that purpose exists (described below).
context: Bindings
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.:
...
<img src="${context:images/icon.png}"/>
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.
Parameters Are Bi-Directional
...