(A20)Tapestry Core:Document Object Model

本文翻译出处 http://tapestry.apache.org/tapestry5/tapestry-core/guide/dom.html

本人翻译目的是用来学习Tapestry5的,共享出来希望大家批评指正。计划持续翻译。

chinajavawolf  

文档对象模型

Tapestry5 与 Tapestry4 或其他框架比采取了一个非常不同的方法来标记生成。

l  Tapestry4 方法

在 Tapestry4 里，标记生成是基于产生一个字符流。在最低级别里，事实上输出在标记格式里，比如 HTML,XHTML 或 WML 是未知的。较高级别，像 IMarkupWriter 接口（及其实现）提供标记生成概念：元素，属性，开始标签和结束标签。

通常，组件将一起工作产生标记。一个通用的例子是一个 Form 组件和很多它包含的表单控制组件（像 TextField,Checkbox 等）。这个 Form 组件不能完全呈现直到所有附加的组件首先呈现。

ImarkupWriter 支持嵌套 writers 。嵌套的 writers 是一种缓冲输出方法直到需要。一个 Form 组件将使用一个嵌套 writer 呈现他的 body ，然后写出他的 < form > 和 < input type=”hidden” > 元素，同样嵌套，缓存 body

当两个元素同等（不是父 / 子关系）时这种方法将崩溃。例如，呈现一个 FieldLabel 组件将被他的同伴组件 TextField 影响。在 Tapestry4 种处理这些情况需要许多补充和特殊方案。

l Tapestry5 方法

Tapestry5 组件呈现出一个 DOM, 一个文档对象模型 (Document Object Model) 。这个文档内的树型节点表示为元素，属性和文本。

DOM 可以完全运行在一个随机访问方式上。这要优于 Tapestry4 种连续的（或缓存）方法。

一个新的 MarkupWriter 接口 允许大多数代码把生成的输出作为一个流。 事实上 , MarkupWriter 更象一个 DOM 树中的指针。

一旦所有的呈现完成， DOM 树被作为流交给客户端。计划增加控制输出个是，包括 pretty-printing 和 / 或 输出压缩（去处所有多余的空格）。

DOM 类

尽管事实上一些第三方的替代选择存在,但实现DOM是 Tapestry 的一部份。 这是一个希望限制依赖关系的框架 , 而且 Tapestry DOM 为初始化建立和少量并发的问题进行了改进。大多数 DOM 实现都较为成熟 , 对查询 ( 通常是使用 xpath) 和操纵具有更大的支持 .

一旦文档对象被创建，你不能直接创建新的文档对象；反之，每个文档对象包括方法创建新的子对象。这主要应用于 Element 类，它可以是一个文本，注释和其他元素的容器。

l 文档（Document ）

文档对象表现为一个完整的文档，也就是说，一个完整响应被发送给客户端。

文档将有一个唯一的 root 元素。 newRootElement() 方法被用来为文档创建 root 元素。

l 元素(Element)

少许文档元素可以有属性，并且他们可以包含其它的元素，像 text 和 comments 。

addAttribute() 方法添加一对新的属性 / 值元素。 如果现有的属性指定的名称已经存在 , 那么新值会被忽略。 这意味着当不同代码块尝试加入一个属性元素 ... 首先放入的属性将 " 赢 "

DOM 被建造之后的一些基本操作尚未实现。计划增加一些方法重新培育 DOM 节点到新的元素内。另外，一些查询方法可以被加入。

MarkupWriter

MarkupWriter 接口允许文档结构在维持一个流的时候被建造。

l  element() and end()

调用 element() 创建一个新的元素在树内。并且提供属性给新的元素。调用 write(), writeln() 和 writef() 在当前元素内书写文本节点。每个对于 element() 的调用都匹配一个 end() 调用，这被用来移动当前节点到上一层。

1. writer.element("img", "src", "icon.png", "width", 20, "height", 20, alt, "*");   
2. writer.end();   

注意 end() 必需被在这调用，即使 < img > 元素是空的（没有 body ）。如果忽略调用 end() ，那么稍后被调用的 element() 创建的元素将被潜逃在 < img > 元素内，这不是我们期望的。

此外，每个 element() 调用都必须匹配一个 end() 调用。

1. writer.element("select", "name", "choice");   
2.     
3.  for (String name : optionsNames)   
4.  {   
5.     writer.element("option");   
6.     writer.write(name);   
7.     writer.end();   
8.  }   
9.     
10.  writer.end();   

 

l  attributes()

添加额外的名 / 值对在当前元素。

当值是空的时，没有属性被添加。

当一个新的名称和现有的名称冲突时，新的值被忽略。 这使前面的值指定一个属性优于任何后继值 .

l  write()

Write() 方法书写文本在当前元素内。它自动提供文本为 XML 控制字符 ('<', '>', 和 '&') 并且转换它们为它们在 XML 实体内的同等物（ '<', '>', 和 '&' ）。结果是正确，安全的 HTML/XML 输出，即使内容（ 它可能是来自一个样板 , 或从外部源如数据库 ）包括这些有问题字符。

l writef()

writef() 方法格式化大量的 argument 。 . 它利用 java.util. Formatter . 这是一个方便的格式化 , 最终调用 write().

l  writeRaw()

writeRaw() 方法书写未过滤的文本到 DOM 内。当 DOM 被呈现给标记时，将提供的字符串不作任何改变写入到输出流。 应小心 , 因为这很容易造成无效标记 , 甚至标记不能很好的被格式化。

l  comment()

添加一个 XML 注释。 Tapestry 支持这个注释分隔符。

 

1. writer.comment("Start of JS Menu code");