Tapestry 5
组件事件
本文根据
http://tapestry.apache.org/tapestry5/tapestry-core/guide/event.html
翻译整理过来,请高手指正,转载请注明出处!
本人随后时间将忙于单点登录研究,翻译
Tapestry 5
的时间不多,稍后章节翻译将会较慢,还望各位继续支持!
组件事件
组件事件是指组件所察觉到的用户的行为,如点击链接或提交表单。
组件主要用于两种用途:
- 它们呈现了用户在客户端浏览器中触发链接或表单发起的请求。这些在页面导航(page navigation)和请求处理(requst processing)中有更全面的描述。
- 它们描绘了一个请求中的控制流即允许一个组件通知它的容器一些情境(一个表单被提交),或者从容器中收集一些片断数据。
通常,一个导航请求(由用户发起)将产生许多控制流请求。如,表单组件被将一个动作请求触发,然后发送通知事件
声称
表单提交事件将被处理,随后不管成功与否。
Tapestry 4
中,你可以用一个方法名来配置组件的一个参数,当某一特定事件发生时(通常来自客户端的请求)该方法将被调用。如:
这有一些局限性,包括事实上仅有一个方法被调用。
- <form jwcid=”@Form” listener=”listener:someMethodName”>
Tapestry 5
引入了通过命名约定或者
OnEvent annotation
来标识的事件处理方法(
event handler methods
)。事件处理方法可以有任何的可见性,甚至私有的(通常它们是包可见性的,用以支持测试)。
同比于配置组件一个被调用的特定的方法,你可以标识一个或多个方法来监听组件事件。单独的一个事件处理方法可以接收许多不同组件的通知事件,如在事件处理方法上加上
@OnEvent(component={"component1", "component2"})
。
比如,这里是一个让用户选择
1
到
10
数字的页面片断(就叫
"chooser"
):
- <p> Choose a number from 1 to 10: </p>
- <p>
- <t:count end="10" value="index">
- <a t:id="select" t:type="actionlink" context="index">${index}</t:comp>
- </t:count>
- </p>
ActionLink
组件创建一个动作
URL
。
URL
标识了页面包含的组件(
"chooser"
),事件的类型(除非不是默认且很通常的
"action"
事件类型),页面里组件的
id
(
"select"
)还有附加的上下文(
context
)值。
一个
URL
示例:
http://localhost:8080/chooser.select/3
.
当存在附加的上下文值时,它们被追加到路径中。
这里示范了
Tapestry
与传统方式
URL
的关键区别,它是一个面向动作的框架。这里的
URL
并不是说链接被点击时发生了什么,而是标识哪个组件来响应。
没有从
URL
到一段代码的简单映射;这里通过调用事件处理方法的形式来替代组件发送通知事件。
当组件生成的链接被用户点击时,一个
Java
方法将会被调用。
- @OnEvent(component = "select")
- void valueChosen(int value)
- {
- _value = value;
- }
Tapestry
在此做了两件事:
- 确认valueChosen()方法作为调用的方法。
- 将上下文值从字符串转换为整数并传送给事件处理方法。
在上面的实例中,
valueChosen()
方法将在
choose
组件产生任何事件时被调用(至少有一个上下文值)。因为
ActionLink
组件仅产生单个事件类型,即
"action"
,这不会带来任何问题(
OnEvent
可以配置事件类型)。
某些组件能产生多种事件,些时你需要更多的细节参数:
- @OnEvent(value = "action", component = "select")
- void valueChosen(int value)
- {
- _value = value;
- }
OnEvent annotation
的
value
属性用来匹配事件名。
"action"
是默认的事件类型名,
ActionLink
和
Form
组件都使用这个事件类型。如果你省略了
OnEvent annotation
的
component
参数,它就是收到所有包含组件的通知事件,可能包括内嵌组件(因为事件冒泡机制
event bubbling
)。
你可以限定接收哪个或哪些组件的事件。
事件处理方法命名约定
作为使用
annotations
的一种替代,我们可以以指定的方式命名事件,
Tapestry
将会调用你的方法,就好像方法被声明了
annotation
一样。
这种事件处理方法的命名方式以前缀
"on"
开头,紧跟着动作的名字(首字母
大写
capitalized
),然后加上
"From"
和
一个首字母大写的
组件
id
。
先前的例子可以写成:
- void onActionFromSelect(int value)
- {
- _value = value;
- }
如果事件类型命名为
"onAny"
,它将接受所有事件类型,我们很少需要此种方式!
如果出于某些难解的原因我们需要以同一方法接收不同组件的相同事件,我们就需要
OnEvent annotation
。
来自
Howard
的提示:我发现我更喜欢命名约定方式,保留
annotation
只是为了其他不适合的情况。
事件上下文(
Event Context
)
上下文值(
ActionLink
组件的
context
参数)可以是任何对象,然而,仅发生一个简单的字符串转换。与
Tapestry 4
相比,他有一个精细的类型机制,怪名叫
"DataSqueezer"
。
此外,不管是什么值(
string, number, date
),它都会被转换为文本字符串。这将形成一个更可读的
URL
。
如果带有多个上下文值(通过将一个对象
list
或数组绑定到
ActionLink
的
context
参数),则每一个值都将有序地追加到
URL
中。
当一个事件处理方法被调用时,将发生一个强制(
coercion
)从字符串到实际类型的转换。事件处理方法仅当上下文值的数量至少与方法参数数量一致时被调用,带有过多参数的方法将被跳过。
另外,一个事件处理方法还可以带上一个
java.lang.Object[]
类型的参数。这个参数会接收整个上下文数组。这在上下文不同时间为不同长度时有用处。我们可以使用一个个显式的参数或者单个的
Object[]
类型的参数。
事件冒泡(
Event Bubbling
)
事件会冒泡向上传递到层级,直到它被终止。事件在事件处理方法返回一个非
null
值时终止。
对于页面导航事件,事件处理方法的返回决定了
Tapestry
将如何呈现响应。