(A4)Tapestry Core :Component Parameters
本文翻译出处 http://tapestry.apache.org/tapestry5/tapestry-core/guide/parameters.html
本人翻译目的是用来学习Tapestry5的,共享出来希望大家批评指正。计划持续翻译。
chinajavawolf
组件参数
组件参数是
Tapestry的一个很重要方面。组件类实例的存在还不足够，它必须被配置去做正确的事。配置要根据组件的参数。
组件可以拥有多个参数。每一个参数都有一个明确的名字，一个明确的
Java类型（也可以是一个简单的值），并且是可选或必需的。
参数定义可以通过在私有属性上放置参数标注。
这个组件列出了一个循环组件；通过定义他的
start和end参数(用来设置循环边界)，他的body将多次呈现.组件可以更新绑定在组件容器内属性的value参数，他将根据是start还是end大而自动进行加减。
- package org.example.app.components;
- import org.apache.tapestry.annotations.AfterRender;
- import org.apache.tapestry.annotations.Parameter;
- import org.apache.tapestry.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;
- }
- }
参数名来源于属性名
(通过去除前面的“_”和“$”字符).这里，参数名是“start”，“end”和“value”。
绑定参数
上面的组件可以被其他组件或者页面模板所引用。
- <html t:type="layout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
- <p> Merry Christmas: <t:count end="3"> Ho! </t:count>
- p>
- html>
End属性被用来绑定
Count组建的end参数。这里，被绑定为string值“3”,Tapestry会自动强制将他转换为int值3.
许多参数都可以这样绑定。
组件参数也可以在组件类里通过组件标注绑定。
当两种绑定方式有冲突的时候，使用组件标注绑定的参数将接管在模板中绑定的参数。
绑定表达式
在前面的例子中模板值为
3就是一个绑定了的表达式。
通过在值前面放置不同的前缀，你可以改变Tapestry如何解释表达式的剩余部分（冒号后面的部分）：
|
前缀
|
描述
|
|
block
|
模板中的
block id.
|
|
component
|
同一个模板中的另一个组件的
id.
|
|
literal
|
一个字面字符串。
|
|
message
|
从组件的信息目录中找回一个值。
|
|
prop
|
容器组件的属性名用来读写。
|
|
translate
|
配置的转换者的名字。
|
|
validate
|
一个被用来创建一些属性验证的验证规范。
|
参数有一个默认的前缀，通常是“
prop:”,当没有提供验证的时候就用它。
属性绑定
前缀为“
prop”的绑定就是属性绑定。
属性绑定的表达式是一个点分隔的属性名序列。简单的属性表达式就是一个属性名，“prop:userName”。 复杂的属性表达式可以在获得属性前加上少量导航来进行读写，如："prop:userData.name"。
除了属性名之外，你也可以调用任意方法。这个方法必须是公有的，返回一个非void值，抛出的是不需检查且无参的异常。你只需要通过添加圆括号就可以区分方法名和属性名了。这样先前的例子可以被重写成“prop:getUserName()”和“prop:getUserData().getName()”. 注意当表达式最后一项是一个方法名，绑定将是只读的，而非可读写的。
这一特性对于访问标准集合类的一对属性来说非常有用，如Collection.size()或Map.keySet()。
当获得失败的时候，是否会因为在这个异常里存在空指针而被绊倒呢
?你可以使用“?.”来替换“.”作为分隔符。这会增加一个空值检测并且如果这项是空值将会忽略表达式。如果不是foo就是bar为null那么"foo?.bar?.baz"将会返回null，同样如果foo或bar为null，则"foo?.bar?.baz"将转变为一个空操作。
另外，还支持少数特殊的情况。在多数情况下，这些特殊的值可以省去你在值前面添加前缀"literal:"。这些少数情况对于属性表达式是可选的。
- "true" 和 "false" 将被转换成布尔值。
- "null" 将被转换成值null。
- "this" 将是组件自身。
- 简单的数字值也可以被接受，这些将会被解析成Long或Double对象。比如："prop:3.14"。
- 被分隔成两个周期的一个整数范围。如："1..10"。
- "单引号里的字面字符串，如："'Hello World'"。
在这些情况里，多余的空格是被忽略的。对于关键词
(“true”,“false”,“this”和“null”)是被忽略大小写的。
这些值都是只读和不变的。
验证绑定
"validate:"绑定前缀非常特别，它允许一个简短的字符串被用来创建和配置对象执行表单控制组件的输入验证，如TextField 和 Checkbox。
这个字符串是一个逗号分隔的验证类型列表.这些简短别名对对象执行验证。在很多情况下，验证是可以多方式进行配置的：例如，一个验证强制一个字符串的所需的最小长度，最小的字符串长度是多少，这个值被指定在一个等号后面。
例如：
validate:required, ,minLength=5 意思就是
强制该字段必须填写并且且不得少于5个字符。
转换绑定
"translate:"绑定前缀也可以用来进行输入验证。它是一个配置转换器
Translator的名字，主要负责服务端与客户端表现数据转换（例如，客户端字符串与服务端数字值的转换）。
有效的转换列表通过
TranslatorSource服务被配置。
非正式参数
一些组件支持非正式参数，额外的参数超过了正式定义的参数。非正式参数将在组件标签呈现时作为额外的属性被呈现。一般来说，组件与特别的HTML标签有1:1的对应关系（比如
TextField和＜input＞支持非正式参数）。
非正式参数通常被用来设置一个元素的
CSS样式，或者用来指定客户端的事件处理器。
非正式参数默认的绑定前缀依赖于指定的参数绑定在那里。如果参数绑定在Java类中的组件标记里，那么这个的默认绑定为"prop:"，如果参数绑定在组件模板中，默认的绑定前缀为"literal:"。这反映个事实，一个用标注在Java类里指定的参数，很可能就是一个计算的值，反之，一个在模板中的值将被简单的拷贝，按照原样放入到HTML结果流中。
参数是双向的
参数不是简单的变量；在组件和它的容器的属性之间，每一个参数代表一个连接或者绑定。当使用绑定前缀prop:时，组件能够通过赋值到他自己的实例变量里强制改变到该组件容器的属性中。
- <t:layout xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
- <p> Countdown:
- <t:count start="5" end="1" value="index">
- ${index} ...
- t:count>
- p>
- t:layout>
因为Count组件更新value参数（_value属性），容器组件的
index属性被更新。在Count的body内，我们通过扩展表达式${index}输出当前index属性的值。输出结果大至如下：
Countdown: 5 ... 4 ... 3 ... 2 ... 1 ...
（尽管空格完全不同）
相关的部分是组件可以读取固定的值或者他的容器中可变的属性值，并且能更改其容器中的属性值。
必选参数
必选参数必须要被绑定。如果一个组件没有绑定必选的参数将会发生运行时异常。
可选参数
参数不是必需的，是可选的。
你可以设置一个默认值给可选参数为其他属性使用。在Count组件中，参数 min有默认值为1，如果参数min绑定了一个值，则绑定的值将替代默认值。
参数的默认绑定
参数标注的value()属性可以被用来指定一个绑定的表达式，用来当参数未绑定的时候作为默认绑定。典型地，绑定的表达式是一个属性的名字，这个属性将会在运行时被计算值。
例如
:
- @Parameter("defaultMessage")
- private String _message;
- @Parameter(required=true)
- private int _maxLength;
- public String getDefaultMessage()
- {
- return String.format("Maximum field length is %d.", _maxLength);
- }
在别处，你可以在value上使用前缀。一个普通的前缀"message:"用来访问本地化信息。
计算参数默认绑定
在少数情况下，你可能需要用计算绑定的方式来作为参数的默认值。此时，你可以提供一个默认的无参的绑定方法。方法的返回值被用来绑定参数。返回值可以是一个绑定实例或者是一个简单的值（比较多的使用）。
方法名以"default"加上首字母大写的参数名。
使用这种方法，前面的例子可以写成这样：
- @Parameter
- private String _message;
- @Parameter(required=true)
- private int _maxLength;
- @Inject
- private ComponentResources _resources;
- @Inject("alias:BindingSource")
- private BindingSource _bindingSource;
- Binding defaultMessage()
- {
- return _bindingSource.newBinding("default value", _resources, "defaultMessage");
- }
- public String getDefaultMessage()
- {
- return String.format("Maximum field length is %d.", _maxLength);
- }
在这个例子中，属性表达式"defaultMessage"被用来动态访问信息。
再换一个，上面的例子可以被写得更简洁：
- @Parameter
- private String _message;
- @Parameter(required=true)
- private int _maxLength;
- @Inject
- private ComponentResources _resources;
- String defaultMessage()
- {
- return String.format("Maximum field length is %d.", _maxLength);
- }
这种形式更像使用"literal:"绑定前缀，只是字面值是通过defaultMessage()方法计算的。
很明显，这要比简单地用参数标注指定一个默认的参数值做更多的工作。这种方法在一些少量的实际情况中被使用，默认的绑定方法将经常会依据组件的id产生正确的绑定。例如，TextField组件将产生一个value参数绑定到它容器中具有相同名字的一个属性。
默认的绑定方法只有在参数标注没有提供默认值时才被调用。
没有绑定的参数
如果一个参数没有被绑定（可选参数），那么它的值可以在任何时候被读写。
更新对于未绑定的参数不起作用。在第一个例子中，Count组件的value参数没有绑定，这完全是有效的。
注意：更新对于这样的属性是临时性的；当组件完成呈现时，属性将被恢复为默认值。
参数缓存
读取一个参数值会耗费不少资源（因为类型的强制转换）。因此，缓存参数值是有意义的，至少当组件正在呈现自己时。
只有在极少情况下去掉缓存是有意义的。可以通过设置参数标注的cache()属性为false来实现。
参数类型强制转换
Tapestry包含一个自动强制类型转换机制。大多情况下，它被用来将字面字符串转换成相应的值，但在许多情况下，将发生更复杂的转换。
参数名
默认情况，Tapestry通过去掉首字母"$" 和 "_"的属性名转换为参数名。
也可以使用参数标注的name()属性。
决定是否绑定
极少数情况，你需要依据参数是否绑定来产生不同的行为。这可以通过查询组件资源来完成，组件资源可以通过
injected标注注入到组件中：
- public class MyComponent
- {
- @Parameter
- private int _myParam;
- @Inject
- private ComponentResources _resources;
- @BeginRender
- void setup()
- {
- if (_resources.isBound("myParam"))
- {
- . . .
- }
- }
- }
以上粗略举例这种方法。因为参数类型是简单类型int，很难区分没有绑定和明确地绑定0。
Inject标注向组件将注入组件的资源。这些资源是连接你提供的Java类与Tapestry底层构建你的类之间的桥梁。任何情况，资源一但被注入，就可以被访问。