Tapestry 5 组件模板

Tapestry 5 组件模板

 

 

本文根据 http://tapestry.apache.org/tapestry5/tapestry-core/guide/templates.html 翻译整理过来，请高手指正，转载请注明出处！

 

 

Tapestry 中，组件模板是与页面或组件类相关的文件，包含组件以及其内嵌组件的标记（ markup ）。

 

从 Tapestry 4 中变化而来，在 Tapestry 5 中，组件模板是格式良好的 XML 文档。这意味着每一个起始标签必须有一个相匹配的结束标签，每一个属性都要被引用起来等等。

 

模板多半是标准的（ X ） HTML ； Tapestry 以提供 Tapestry 命名空间的形式扩展了普通的标记（ markup ）。

 

我们将简短介绍模板的具体内容，首先详细介绍组件与模板是如何联系的。

 

模板定位

 

组件模板与组件类文件存放在一起，文件后缀名为 ".html" ，与相应组件类存放在同一包下。

 

在典型的 Maven 目录结构中，组件的 Java 类可以是 src/main/java/org/example/myapp/components/MyComponent.java 。相应的模板将会是 src/main/resources/org/example/myapp/components/MyComponent.html 。

 

与此同时，页面的 Java 类可以是 src/main/java/org/example/myapp/pages/MyPage.java 。相应的模板将会是 src/main/resources/org/example/myapp/pages/MyPage.html 。

 

模板与被编译的类将会被一起打包到 WAR 应用包的 WEB-INF/classes 文件夹下。

 

对于页面（非组件），还有一个位置将会被查找： web 应用目录下（ web application context ），位置是基于页面的逻辑名，在先前的一个例子中，模板应该是在 web 应用根目录下的 MyPage.html 。

 

类路径下的模板要优先于 web 应用目录下的模板文件。

 

模板国际化

 

模板像单独的组件信息分类文件一样被国际化（ localized ）了：文件名后接有效的 local （如 en ， zh_CN ）。因此德国的用户将看到由 MyPage_de.html 生成的页面内容，法国的用户将看到由 MyPage_fr.html 生成的页面内容，当没有明确的国际化文件时，默认的国际化文件（ MyPage.html ）会被使用。

 

模板继承

 

如果一个组件没有模板，但是它继承的父组件类有模板，此时父类的模板将会被用作子模板。

 

这就允许组件继承基类的模板而不是重复基类的模板。

 

Tapestry 命名空间

 

组件模板应该包括 Tapestry 命名空间，其定义在模板的根元素中。

 

＜html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd"＞

    ＜head＞

        ＜title＞Hello World Page＜/title＞

    ＜/head＞

    ＜body＞

        ＜h1＞Hello World＜/h1＞

    ＜/body＞

＜/html＞

 

这里的命名空间定义使用了标准的前缀“ t: ”，这一页中的实例都采用这一标准前缀。

 

Tapestry 元素

 

Tapestry 元素都采用 Tapestry 命名空间前缀定义的元素。

 

其他元素应该在默认的命名空间中，没有前缀。

 

＜body ＞

 

在许多情况下，组件被设计成与其模板中内嵌的模板整合在一起。

 

＜ body ＞元素被用来标识组件模板中的内嵌模板的 body 被呈现（ rendered ）在哪里。

 

组件可以控制（经常）其 body 是否被呈现。

 

以下实例是一个 Layout 组件，页面具体内容里面添加了基本的 HTML 元素。

 

＜html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd"＞

    ＜head＞

        ＜title＞My Tapestry Application＜/title＞

    ＜/head＞

    ＜body＞

        ＜t:body/＞

    ＜/body＞

＜/html＞

 

以下是页面应该如何使用这一组件：

 

＜t:layout xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd"＞

 

 My Page Specific Content

 

＜/t:layout＞

 

当页面呈现时，页面模板和其外围的组件模板被合并到了一起：

 

＜html＞

  ＜head＞

    ＜title＞My Tapestry Application＜/title＞

  ＜/head＞

  ＜body＞

    My Page Specific Content

  ＜/body＞

＜/html＞

 

Tapestry 4 用户将意识到＜ body ＞元素就是 RenderBody 组件的替代。

 

＜block ＞

 

block 是组件部分模板的容器。 block 不会正常呈现（ render ），任何组件或内容放入一个 block 都不会被正常呈现。然而，通过注入 block ，你可以精确控制什么时候及是否呈现内容。

 

block 可以是匿名的，或者拥有一个 id （通过 id 属性来指定）。非匿名 block 可以注入（ injected ）到组件里。

 

＜parameter ＞

 

参数元素是一个特殊类型的 block ，它被放置在一个内嵌组件的 body 中。 block 通过＜ parameter ＞定义传入到组件。＜ parameter ＞包含一个必须的 name 属性用以识别绑定了组件的哪一个参数。

Example:

＜t:if test="loggedIn"＞

 Hello, ${userName}!

  ＜t:parameter name="else"＞

 Click ＜a t:type="actionlink" t:id="login"＞here＜/a＞ to log in.

  ＜/t:parameter＞

＜/t:if＞

 

扩展表达式（Expansions ）

 

另外一种呈现输出就是使用扩展表达式。扩展表达式是可以内嵌在模板体内的特殊字符串，借用了 Ant 构建工具的一些语法。

 

Welcome, ${userId}!

 

在此， ${userId} 是一个扩展表达式。此例中，组件的属性 userId 被提取出来转换成一个字符串流向输出。

 

扩展表达式只能用在普通的模板文本中；不允许用在属性中或者 CDATA 段中。

 

从其特性来讲，扩展表达式和参数绑定（ parameter bindings ）一样，它的默认绑定前缀为 "prop:" （表示一个属性名），还有其他的绑定前缀也很有用，特别是 "message:" （用来访问组件分类信息中的国际化信息）。

 

Tapestry 4 用户会注意到扩展表达式很简洁，它轻松替代了 Insert 组件或者＜ span key="..." ＞标识。

 

组件元素

 

一个内嵌的组件在模板中被识别为 t: 命名空间下的元素。如：

 

 You have ${cartItems.size()} items in your cart.

  ＜t:actionlink t:id="clear"＞Remove All＜/t:actionlink＞.

 

元素名 "actionlink" 用于标识组件的类型—— "ActionLink" （ Tapesty 在识别组件类型时不区分大小写）。

 

内嵌组件可以有两个 Tapestry 相关的参数：

§                 id ：组件的唯一 id （在其容器中）。

§     mixins ：用于组件的一个可选的用逗号分隔的混入组件（ mixins ）的列表。

 

这些属性指定在 t: 命名空间里（如， t:id="clear" ）。

 

如果 id 属性被忽略， Tapestry 会给这个元素赋一个唯一 id 。

 

其他属性用于绑定组件的参数 （ bind parameters of the component ），这些 可能是正式参数或非正式参数。正式参数会有一个默认的绑定前缀（通常 是 "prop:" ），非正式参数假定为字面的（如， "literal:" 绑定前缀）。

 

对于其他所有属性， t: 前缀是可选的。一些用户实现一个用于 Tapestry 模板文件校验的构建程序 … 此时，任何 Tapestry 相关的属性，非底层 DTD 或 scheme 定义的属性，应该在 Tapestry 的命名空间里，避免产生校验错误。

 

Tapestry 组件元素的开始和结束标签定义了组件的 body ，这常见于一些组件封入到另外的组件 body 里。

 

＜t:form＞

  ＜t:errors/＞

  ＜t:label for="userId"/＞

  ＜t:textfield t:id="userId"/＞

  ＜br/＞

  ＜t:table for="password"/＞

  ＜t:passwordfield t:id="password"/＞

  ＜br/＞

  ＜input type="submit" value="Login"/＞

＜/t:form＞

 

在一些情况下，组件需要某种闭合标签；比如，以上所有字段域组件如果没有被 Form 组件所封闭将会抛出一个运行时异常。

 

我们有可能将 Tapestry 组件放置在子包（ subclasses ？）里。比如，应用中有一个包 org.example.myapp.components.ajax.Dialog 。这个组件正常的类型名是 "ajax/dialog" （因为它在 ajax 子文件夹下），这个名字是有问题的，因为它不能通过元素名＜ t:ajax/dialog ＞有效地定义 XML 元素。此时，我们使用句点替换斜线——＜ t:ajax.dialog ＞。

 

隐式标识（invisible Instrumentation ）

 

Tapestry 中一个突出的特性是隐式标识（ invisible instrumentation ），用来标记普通的 HTML 元素为组件。隐式标识可以让模板更加简洁及更好的可读性。

 

Tapestry 5 中，我们使用命名空间 id 或类型属性来标记一个任意的元素为组件，如下：

＜p＞

    Merry Christmas:

    ＜span t:type="Count" end="3"＞

        Ho!

    ＜/span＞

＜/p＞

 

id 、 type 和 mixins 属性必须放在 Tapestry 的命名空间里。任何其他的属性可以在 Tapestry 命名空间里或默认的命名空间里。

Placing an attribute in the Tapestry namespace is useful when the attribute is not defined for the element being instrumented.

当被标识的元素属性未被定义时，将这个属性放入 Tapestry 的命名空间里是有用的。

 

只指定 t:id 属性而不在模板或类中提供明确的类型也是有效的。些种情况， Tapestry 会使用 Any 组件，它有点像是任何其他组件的一种替代。

 

在大多数情况下，在普通内嵌组件和隐式标识组件之间选择是一个美学问题。少数情况下，如 Loop 组件，其行为决定于你的选择。当 Loop 组件使用隐式标识的方式时，将会在其 body 外围呈现标签及任何非正式参数。因此，比如：

 

  ＜table＞

    ＜tr t:type="loop" source="items" value="item" class="prop:rowClass"＞

      ＜td＞${item.id}＜/td＞

      ＜td＞${item.name}＜/td＞

      ＜td＞${item.quantity}＜/td＞

    ＜/tr＞

  ＜/tabel＞

 

这里， loop 组件并入＜ tr ＞元素里，它将对每一个列表项呈现一个＜ tr ＞，以及在＜ tr ＞中输出一个动态的 class 属性。