Document Actions

DTML参考

by 潘俊勇 — last modified 2005-12-14 14:25

_转自:杜文山《快乐程序》第一辑_ DTML参考

call:调用一个方法
comment: 注释DTML
- 2.1. 句法
- 2.2. 例子
Functions：DTML函数
if：测试条件
in：对序列进行循环
let：定义DTML变量
mime:用MIME格式数据
raise：引发一个例外
return: 返回数据
- 9.1. 句法
- 9.2. 例子
sendmail: 通过SMTP发送邮件
sqlgroup：处理复杂的SQL表达式格式
sqltest: 处理SQL条件测试格式
sqlvar：插入SQL变量
tree：插入一个树部件
try：处理例外
unless：测试一个条件
var：插入一个变量
with：控制查找DTML变量

文档模板标记语言（DTML）是一种便捷的内置于Zope中的表现和模板语言。

1. call:调用一个方法

call标记符使你能够调用一个方法而不把结果插入到DTML。

1.1. 句法

call标记符句法：

  <dtml-call Variable|expr="Expression">

如果call标记符使用变量，DTML自动传递方法的参数，就像var标记符那样。如果在一个表达式里指定方法，那么你必须亲自传递参数。

1.2. 例子

用变量名称调用：

  <dtml-call UpdateInfo>

它调用UpdateInfo 对象，自动传递参数。

用表达式调用：

  <dtml-call expr="RESPONSE.setHeader(content-type, text/plain)">

1.3. 参见

var tag

2. comment: 注释DTML

comment 标记符使你能够用注释为DTML做注解。你还可以用它把DTML注释掉，让DTML标记符暂时失效。

2.1. 句法

comment 标记符句法：

  <dtml-comment>
  </dtml-comment>

comment 标记符是一种块标记符。块的内容被执行，并且不插入到DTML输出中。

2.2. 例子

注解DTML：

  <dtml-comment>
    This content is not executed and does not appear in the
    output.
  </dtml-comment>

注释掉DTML：

  <dtml-comment>
    This DTML is disabled and will not be executed.
    <dtml-call someMethod>
  </dtml-comment>

3. Functions：DTML函数

DTML效用函数提供一些Python内建函数和一些DTML特效函数。

3.1. 函数

abs(number): 返回数字number的绝对值。参数可以为一个普通整数或长整数或一个浮点数。如果参数是一个复数，则返回它的量值。
chr(integer): 返回一个字符，这个字符的ASCII 代码是参数integer。例如，chr(97)返回字符a。相反的函数为ord()。参数必需在0 至 255范围内，如果integer 超出了那个范围就引发一个ValueError 错误。
DateTime?(): 返回一个已知构造参数的Zope DateTime?对象。有关构造参数的更多信息请参见“API参考”中的“DateTime类”部分。
divmod(number, number): 采用两个数字作为参数并在使用长除法时返回一对由它们的商和余数组成的数字。对于混合操作数类型，应用二进制算法操作符规则。对于普通和长整数，结果等同于(a / b, a % b)。对于浮点数，结果是 (q, a % b)，其中q是math.floor(a / b)，然而，它可能会是1，小于那个数。在任何情况中，q * b + a % b 非常接近a。如果a % b是非0，它有和b相同的符号并且0 <= abs(a % b) < abs(b)。
float(number): 把一个字符串或一个数字转换成浮点数。如果参数是一个字符串，它必需包含一个可能带有符号的小数或者浮点数，可嵌入空格；它的作用等同于string.atof(number)。另外，参数可以是一个普通整数或长整数或者一个浮点数，如果是浮点数，返回相同的值（在Python的浮点精度以内）。
getattr(object, string): 返回对象的指定的属性的值。名称必需为一个字符串。如果string是对象中的某个属性的名称，结果就是那个属性的值。例如，getattr(x, "foobar")等同于x.foobar。如果指定的属性不存在，提供了默认值就返回默认值，否则就引发一个AttributeError 错误。
getitem(variable, render=0): 返回一个DTML变量的值。如果render 为真，就运行变量。参见render 函数。
hasattr(object, string): 参数是一个对象和一个字符串。如果这个字符串是对象的某个属性的名称，结果为1，否则结果为0。（这是通过调用getattr(object, name) 和查看它是否引发一个例外来实现的。）
hash(object): 返回对象的散列值（如果它有的话）。散列值是整数。它们用于在一个字典查找期间内快速比较字典键。相等的数字值有相同的散列值（即使它们属于不同的类型，例如1和1.0）。
has_key(variable): 如果DTML名称空间包含variable则返回真。
hex(integer): 把一个整数（任意大小）转换成十六进制的字符。结果是一个有效的Python表达式。注意：这常常产生一个无符号的文字。例如在32-bit 机器上，hex(-1) 结果为0xffffffff。当在一个机器上使用相同的单词大小求值时，这个文字认为是-1；对于不同的单词大小，它可能会变成大的正数或引发一个OverflowError 例外。
int(number): 把一个字符串或数字转换成一个普通整数。如果参数是一个字符串，它必须包含一个可能带有符号的十进制数字，这个数字可以作为一个Python整数提供，并且有可能嵌入空格。这个行为等同于 'string.atoi(number,)’ 。radix 参数给出了转换的基数，可以是2到36 范围内的任何整数。如果指定了radix并且number不是一个字符串，引发一个 TypeError? 错误。另外，参数可以是一个普通整数或长整数或浮点数。浮点数转换成整数按照 C 语言的方法来定义；通常，转换是把小数点后面数字截取为零。
len(sequence): 返回对象的长度（数据项的数量）。参数可以为一个序列（字符串，元组或列表）或一个映射（字典）。
max(s): s 参数唯一时返回非空序列（例如，一个字符串，元组或列表）中的最大项。当有多个参数，它返回参数中的最大一个。
min(s): s 参数唯一时返回非空序列（例如，一个字符串，元组或列表）中的最小项。当有多个参数时，它返回参数中的最小一个。
namespace([name=value]?...): 返回一个新的DTML名称空间对象。关键字参数name=value 对被加入到新的名称空间中。
oct(integer): 把一个整数（任意大小）转换成八进制字符。结果是一个有效的Python表达式。注意：这总是生成一个无正负符号的文字。例如，在一个32-bit 机器上， oct(-1) 生成037777777777。当在一个具有相同单词大小的机器上求值时，这个文字结果为-1；对于一个不同的单词大小，它可能生成一个大整数或引发一个OverflowError 例外。
ord(character): 返回某个字符的ASCII 值。例如，ord("a") 返回整数97 。相反的函数为chr() 。
pow(x, y [,z]?): 返回x的y次方。如果提供了z，它首先求x的y方，再对z求余，返回结果（执行效率高于 'pow(x, y) % z'）。参数必须为数字类型。对于混合操作数类型，应用二进制算法操作符规则。有效的操作数类型也是结果的类型，如果结果不表现为这种类型，函数引发一个例外，例如pow(2, -1) 或 pow(2, 35000)是不允许的。
range([start,]? stop [,step]?): 这是一个用于创建含有算术级数的列表的通用函数。参数必需为普通整数。如果step 参数忽略，默认为1。如果start 参数忽略，默认为0。返回的完整形式是一个普通整数列表 sstart, start + step, start + 2 * step,。如果step 是正数，最后一个元素是小于stop的最大start + i step ；如果step 是一个负数，最后一个元素是大于stop的最大start + i step 。step 不能为0（否则引发一个ValueError 错误）。
round(x [,n]?): 返回x被四舍五入后的浮点值，它截至小数点后n位。如果n忽略，它默认为零。结果是一个浮点数。值被四舍五入到最接近的10的负n次幂处的倍数；如果两个倍数一样近，四舍五入选择远离0的那个（例如，round (0.5)为1.0 ，round (-0.5) 为-1.0）。
render(object): 运行对象。对于DTML 对象，它使用当前的名称空间对DTML求值。对于其他对象，它等同于str(object) 。
reorder(s [,with]? [,without]?): 对s中的数据项根据在with中给定的顺序重新排序，不包括在without中提到的数据项。s中没有在with中提到的数据项被删除。s、with和without都是字符序列或键值元组序列，对键进行排序。这个函数对于构建有序的选择列表是有用的。
SecurityCalledByExecutable?(): 如果当前的对象（例如DTML文档或方法）由一个可执行对象（例如其它的DTML文档或方法，脚本或SQL方法）调用则返回真。
SecurityCheckPermission?(permission, object): 检查指定对象是否关联有指定的许可。例如SecurityCheckPermission("Add Documents, Images, and Files", this())，如果当前的用户被授权能够在当前位置中创建文档、图像和文件，这个函数将返回真。
SecurityGetUser?(): 返回当前用户对象。通常，它等同于REQUEST.AUTHENTICATED_USER 对象。然而，AUTHENTICATED_USER对象是不安全的，这是因为它可以被替换。
SecurityValidate?([object]? [,parent]? [,name]? [,value]?): 如果当前用户可以访问value则返回真。object 是被访问的变量所在的对象，parent 是变量的容器，name 是用于访问变量的名称（例如，如果它通过getattr获得）。你可以忽略其中的一些参数。最好提供所有的参数。
SecurityValidateValue?(object): 如果当前用户可访问object则返回真。这个函数等同于调用SecurityValidate(None, None, None, object) 。
str(object): 返回一个包含一个适当的可打印出来的表示对象的字符串。对于字符串，它返回字符串本身。
test(condition, result ,condition,... [,default]?): 对一对或多对 condition, result 进行测试并返回第一个条件为真的的结果。只返回一个结果，即使有多个条件为真。如果没有条件为真并且给定默认值，那么就返回默认值。如果没有条件为真并且没有默认值，返回None 。

3.2. 属性

None: None 对象等同于Python的内建对象None。它通常用于表示一个空或假值。

3.3. 参见

string module

random module

math module

Python 内建函数

4. if：测试条件

根据条件，if标记符测试条件并且采取不同的行为。if标记符类似于Python中的 if/elif/else 条件测试语句。

4.1. 句法

if标记符句法：

  <dtml-if ConditionVariable|expr="ConditionExpression">
  [<dtml-elif ConditionVariable|expr="ConditionExpression">]
   ...
  [<dtml-else>]
  </dtml-if>

if标记符是一种块标记符。if标记符和可选择的elif 标记符使用一个条件变量名称或一个条件表达式，但只能是其中的一种。如果条件名称或表达式的值为真，那么被if块执行。真意味着不是0、空字符串或一个空列表。如果条件变量没有找到，那么这个条件认为是假。如果初始的条件为假，则按次序测试elif 条件。如果elif 条件为真，那么执行块中的内容。最终如果if和elif 条件没有为真的，就执行可选的else块。只有一个块被执行。

4.2. 例子

测试一个变量：

  <dtml-if snake>
    The snake variable is true
  </dtml-if>

测试表达式条件：

  <dtml-if expr="num > 5">
    num is greater than five
  <dtml-elif expr="num < 5">
    num is less than five
  <dtml-else>
    num must be five
  </dtml-if>

4.3. 参见

Python文档: if 语句

5. in：对序列进行循环

in标记符用于控制循环序列和执行批处理。

5.1. 句法

in标记符句法：

  <dtml-in SequenceVariable|expr="SequenceExpression">
  [<dtml-else>]
  </dtml-in>

in针对序列变量或序列表达式中的每一项循环一次。当前项在每次执行in块时被推入到DTML名称空间中。如果在序列中没有数据项是变量或表达式，则执行可选的else块。

5.2. 属性

mapping: 迭代映射对象而不是实例。这使得映射对象的值可以作为DTML变量被访问。
reverse: 翻转序列。
sort=string: 按照给定的属性名称对序列排序。
start=int: 要显示的第一项的数字，其中数据项计数从1开始。
end=int: 要显示的最后一项的数字，其中数据项计数从1开始。
size=int: 批处理的大小。
skip_unauthorized: 如果遇到一个没有授权的数据项不引发例外。
orphan=int: 预期最小批处理大小。用于如何把序列分隔成批块。如果批块大小比orphan小，则不进行分隔。比如，如果序列的大小是12，批块大小是10，orphan为3，那么由于分隔后的一个批块小于3，则结果将是一个含有12个数据项的批块。
overlap=int: 批处理块之间相互重叠的数据项的数字。默认没有重叠。
previous: 如果有前一个批处理块则迭代一次。为前一个序列设置批处理变量。
next: 如果有下一个批处理块则迭代一次。为下一个序列设置批处理变量。

5.3. 标记符变量

5.3.1. 当前数据项变量

这些变量描述当前的数据项：

sequence-item: 当前的数据项。
sequence-key: 当前键字。当循环表单元组(key，value)时，in标记符把它们转换成 (sequence-key, sequence-item) 。
sequence-index: 当前数据项从0开始的索引。
sequence-number: 当前数据项从1开始的索引。
sequence-roman: 当前数据项以小写罗马数字表示的索引。
sequence-Roman: 当前数据项以大写罗马数字表示的索引。
sequence-letter: 当前数据项以小写字母表示的索引。
sequence-Letter: 当前数据项以大写字母表示的索引。
sequence-start: 如果当前数据项为第一个数据项则为真。
sequence-end: 如果当前数据项为最后一个数据项则为真。
sequence-even: 如果当前数据项索引为偶数则为真。
sequence-odd: 如果当前数据项索引为奇数则为真。
sequence-length: 序列的长度。
sequence-var-variable: 在当前数据项中的一个变量。例如，sequence-var-title是当前数据项的标题变量。通常，你可以直接访问这个变量，这是因为当前的数据项被推到DTML名称空间中。用于帮助显示前一个和下一个批处理信息。
sequence-index-variable: 当前数据项的变量索引。

5.3.2. 总结变量

这些变量总结了有关数据项变量数字方面的信息。要使用这些变量，你必须循环含有数字变量的对象（比如数据库查询结果）。

total-variable: 一个数据项变量的所有实例的总数。
count-variable: 一个数据项变量的实例数。
min-variable: 一个数据项变量的最小值。
max-variable: 一个数据项变量的最大值。
mean-variable: 一个数据项变量的平均值。
variance-variable: 一个数据项的count-1 自由度方差。
variance-n-variable: 一个数据项变量的n自由度方差。
standard-deviation-variable: 一个数据项变量的count-1 自由度标准偏差
standard-deviation-n-variable: 一个数据项变量的n自由度标准偏差。

5.3.3. 分组变量

这些变量使你能够跟踪当前数据项变量的变化：

first-variable: 如果当前数据项是第一个具有特定变量值的数据项则为真。
last-variable: 如果当前数据项是最后一个具有特定变量值的数据项则为真。

5.3.4. 批处理变量

sequence-query: 不包含start变量的查询字符。你可以使用这个变量构建与下一个和前一个批处理块的链接。
sequence-step-size: 批处理块的大小。
previous-sequence: 如果当前批处理块不是第一个则为真。注意，这个变量只对第一次循环迭代为真。
previous-sequence-start-index: 前一个批处理块的开始索引。
previous-sequence-start-number: 前一个批处理块的开始数字。注意，它等同于previous-sequence-start-index + 1。
previous-sequence-end-index: 前一个批处理块的结束索引。
previous-sequence-end-number: 前一个批处理块的结束数字。注意，它等同于previous-sequence-end-index + 1。
previous-sequence-size: 前一个批处理块的大小。
previous-batches: 带有前一个批处理块所有相关信息的映射对象序列。每个映射对象有三个键：batch-start-index、 batch-end-index 和 batch-size 。
next-sequence: 如果当前批处理块不是最后一个批处理块则为真。注意，这个变量只对最后的循环迭代才为真。
next-sequence-start-index: 下一个序列的开始索引。
next-sequence-start-number: 下一个序列的开始数字。注意，这等同于next-sequence-start-index + 1。
next-sequence-end-index: 下一个序列的结束索引。
next-sequence-end-number: 下一个序列的结束数字。注意，这等同于 next-sequence-end-index + 1。
next-sequence-size: 下一个索引的大小。
next-batches: 带有下一个批处理块所有相关信息的映射对象序列。每个映射对象有三个键：batch-start-index, batch-end-index, and batch-size。

5.4. 例子

循环下级对象：

  <dtml-in objectValues>
    title: <dtml-var title><br>
  </dtml-in>

循环元组列表（key，value）：

  <dtml-in objectItems>
    id: <dtml-var sequence-key>, title: <dtml-var title><br>
  </dtml-in>

对两个对象集合进行循环，使用prefix：

  <dtml-let rows="(1,2,3)" cols="(4,5,6)">
    <dtml-in rows prefix="row">
      <dtml-in cols prefix="col">
        <dtml-var expr="row_item  col_item"><br>
        <dtml-if col_end>
          <dtml-var expr="col_total_item  row_mean_item">
        </dtml-if>
      </dtml-in>
    </dtml-in>
  </dtml-let>

对一个 (key, value) 元组列表进行循环:

  <dtml-in objectItems>
    id: <dtml-var sequence-key>, title: <dtml-var title><br>
  </dtml-in>

创建具有交替颜色的表格单元：

  <table>
  <dtml-in objectValues>
  <tr <dtml-if sequence-odd>bgcolor="#EEEEEE"
      <dtml-else>bgcolor="#FFFFFF">
      </dtml-if>
    <td><dtml-var title></td>
  </tr>
  </dtml-in>
  </table>

基本批处理：

  <p>
  <dtml-in largeSequence size=10 start=start previous>
    <a href="<dtml-var absolute_url><dtml-var sequence-query>start=<dtml-var previous-sequence-start-number>">Previous</a>
  </dtml-in>  <dtml-in largeSequence size=10 start=start next>
    <a href="<dtml-var absolute_url><dtml-var sequence-query>start=<dtml-var next-sequence-start-number>">Next</a>
  </dtml-in>
  </p>
  <p>
  <p>
  <dtml-in largeSequence size=10 start=start>
    <dtml-var sequence-item>
  </dtml-in>
  </p>

这个例子可创建“前一页”和“下一页”链接，从而实现在批处理块之间跳转。注意，通过使用sequence-query，当你在批处理块之间跳转时，你不会丢失任何任何GET变量。

6. let：定义DTML变量

let标记符定义DTML名称空间里的变量。

6.1. 句法

let标记符句法：

  <dtml-let [Name=Variable][Name="Expression"]...>
  </dtml-let>

let标记符是一种块标记符。变量通过标记符参数定义。在let块执行的同时，定义的变量被推进到DTML名称空间。变量通过属性定义。let标记符可以有一个或多个任意属性。如果属性用双引号定义，它们被认为是表达式。否则，它们按照名称查找相应变量。属性按顺序处理，因此后边的属性可以引用和覆盖前边的属性。

6.2. 例子

基本用法：

  <dtml-let name="'Bob'" ids=objectIds>
    name: <dtml-var name>
    ids: <dtml-var ids>
  </dtml-let>

和in标记符一起使用let标记符：

  <dtml-in expr="(1,2,3,4)">
    <dtml-let num=sequence-item
              index=sequence-index
              result="numindex">
      <dtml-var num>  <dtml-var index> = <dtml-var result>
    </dtml-let>
  </dtml-in>

这会生成： 1 0 = 0 2 1 = 2 3 2 = 6 4 3 = 12

6.3. 参见

with 标记符

7. mime:用MIME格式数据

mime标记符用于创建MIME编码数据。它主要用在sendmail 标记符中对邮件进行格式处理。

7.1. 句法

mime 标记符句法：

  <dtml-mime>
  [<dtml-boundry>]
  ...
  </dtml-mime>

mime 标记符是一种块标记符。块可以用一个或多个boundry 标记符分隔来创建多部分MIME 消息。mime 标记符可以签套。mime 标记符主要用在sendmail 标记符里。

7.2. 属性

所有的mime 和boundry 标记符都有相同的属性：

encode=string: MIME 内容传输编码报头（Content-Transfer-Encoding header），默认为base64。有效的编码选项包括base64、 quoted-printable、 uuencode、 x-uuencode、 uue、 x-uue 和 7bit。在encode属性设置为7bit，则不编码，数据被假定为一种有效的MIME 格式。
type=string: MIME 内容-类型报头（Content-Type header）。
type_expr=string: 作为变量表达式的MIME 内容-类型报头（Content-Type header）。你不能同时使用type 和 type_expr 。
name=string: MIME 内容-类型报头（Content-Type header）名称。
name_expr=string: 作为变量表达式的MIME 内容-类型报头（Content-Type header）名称。你不能同时使用name 和 name_expr。
disposition=string: MIME 内容-部署报头（Content-Disposition header）。
disposition_expr=string: 作为变量表达式的MIME 内容-部署报头（Content-Disposition header）。你不能同时使用disposition 和 disposition_expr。
filename=string: MIME 内容-部署报头（Content-Disposition header）文件名。
filename_expr=string: 作为变量表达式的MIME 内容-部署报头（Content-Disposition header）文件名。你不能同时使用filename 和 filename_expr 。
skip_expr=string: 一个变量表达式，如果为真就跳过块。你可以使用这个属性来有选择性的包含MIME 块。

7.3. 例子

发送一个文件附件：

  <dtml-sendmail>
  To: <dtml-recipient>
  Subject: Resume
  <dtml-mime type="text/plain" encode="7bit">
  Hi, please take a look at my resume.
  <dtml-boundary type="application/octet-stream" disposition="attachment" 
  encode="base64" filename_expr="resume_file.getId()">
  <dtml-var expr="resume_file.read()"></dtml-mime>
  </dtml-sendmail>

7.4. 参见

Python Library: mimetools

8. raise：引发一个例外

raise标记符引发一个例外，对应于Python的raise语句。

8.1. 句法

raise标记符语句：

  <dtml-raise ExceptionName|ExceptionExpression>
  </dtml-raise>

raise标记符是一种块标记符。它引发一个例外。例外可以是一个exception 类或一个字符串。标记符的内容作为错误的值。

8.2. 例子

引发一个KeyError：

  <dtml-raise KeyError></dtml-raise>

引发HTTP 404 错误:

  <dtml-raise NotFound>Web Page Not Found</dtml-raise>

8.3. 参见

try 标记符

Python 文档: Errors and Exceptions

Python 内建例外

9. return: 返回数据

return 标记符停止执行DTML并返回数据。对应于Python的return 语句。

9.1. 句法

return 标记符句法：

  <dtml-return ReturnVariable|expr="ReturnExpression">

它停止执行DTML并返回一个变量或表达式。DTML输出不被返回。通常，一个返回表达式比起返回一个变量更为有用。用脚本可替代这个标记符的功能。

9.2. 例子

返回一个变量：

  <dtml-return result>

返回一个Python字典：

  <dtml-return expr="{'hi':200, 'lo':5}">

10. sendmail: 通过SMTP发送邮件

sendmail 标记符使用SMTP发送一个电子邮件信息。

10.1. 句法

sendmail 标记符句法：

  <dtml-sendmail>
  </dtml-sendmail>

sendmail 标记符是一种块标记符。它需要一个邮件主机或一个smtphost 参数，但是不是两者都需要。标记符块作为一条邮件消息被发送。块的开始描述电子邮件报头。报头和正文之间用一个空行分开。To、 From 和 Subject报头可以通过标记符参数设置。

10.2. 属性

mailhost: 用于发送电子邮件的Zope邮件主机（MailHost）对象的名称。你不能同时指定mailhost 和 smtphost 。
smtphost: 用于发送电子邮件的SMTP服务器的名称。你不同同时指定mailhost 和 smtphost 。
port: 如果使用smtphost 属性，那么port 属性用于指定连接的端口号。如果没有指定，那么就使用端口 25 。
mailto: 接收地址或一个用逗号分开的接收地址列表。这也可以用 To 报头指定。
mailfrom: 发送者地址。还可以用From 报头指定。
subject: 电子邮件主题。还可以用Subject 报头指定。

10.3. 例子

使用mailhost发送一个电子邮件：

  <dtml-sendmail mailhost="mailhost">
  To: <dtml-var recipient>
  From: <dtml-var sender>
  Subject: <dtml-var subject>
  Dear <dtml-var recipient>,
  You order number <dtml-var order_number> is ready.
  Please pick it up at your soonest convenience.
  </dtml-sendmail>

10.4. 参见

RFC 821 (SMTP Protocol)

mime 标记符

11. sqlgroup：处理复杂的SQL表达式格式

sqlgroup 标记符用来处理复杂的布尔SQL表达式。你可以用它配合sqltest 标记符构建动态SQL查询。这个标记符用在SQL方法对象中。

11.1. 句法

sqlgroup 标记符句法：

  <dtml-sqlgroup>
  [<dtml-or>]
  [<dtml-and>]
  ...
  </dtml-sqlgroup>

sqlgroup 标记符是一种块标记符。它用一个或多个可选的or和and标记符划分成块。sqlgroup 标记符可以签套，从而生成复杂的逻辑。

11.2. 属性

required=boolean: 指出这组SQL语句是否为必需的。如果它不是必需的并且为空，它就不在DTML输出中显示。
where=boolean: 如果为真，则包含字符串 “Where” 。适用于一个SQL select 查询中的最外面的sqlgroup 标记符。

11.3. 例子

例子用法：

  select * from employees 
  <dtml-sqlgroup where>
    <dtml-sqltest salary op="gt" type="float" optional>
  <dtml-and>
    <dtml-sqltest first type="nb" multiple optional>
  <dtml-and>
    <dtml-sqltest last type="nb" multiple optional>
  </dtml-sqlgroup>

如果first 为Bob ，last 为Smith、McDonald，它处理结果为：

  select * from employees
  where
  (first=Bob
   and
   last in (Smith, McDonald)
  )

如果salary 为50000 ，last 为Smith，它处理结果为：

  select * from employees
  where 
  (salary > 50000.0
   and
   last='Smith’
  )

签套的sqlgroup 标记符：

  select * from employees
  <dtml-sqlgroup where>
    <dtml-sqlgroup>
       <dtml-sqltest first op="like" type="nb">
    <dtml-and>
       <dtml-sqltest last op="like" type="nb">
    <dtml-sqlgroup>
  <dtml-or>
    <dtml-sqltest salary op="gt" type="float">
  </dtml-sqlgroup>

给定一些参数，这个模板处理的结果是这样的SQL：

  select * form employees
  where
  (
    (
     name like A*
     and
     last like Smith
     )
   or
   salary > 20000.0
  )

11.4. 参见

sqltest 标记符

12. sqltest: 处理SQL条件测试格式

sqltest 标记符把一个条件测试插入到SQL代码中。它对列及相应的变量进行测试。这个标记符用在SQL方法对象里。

12.1. 句法

sqltest 标记符句法：

  <dtml-sqltest Variable|expr="VariableExpression">

sqltest 标记符是一种独立标记符。它插入一段SQL条件测试语句。它用于构建SQL查询。sqltest 标记对变量进行处理。被指定的变量或变量表达式和SQL列之间使用指定的比较操作符进行比较。

12.2. 属性

type=string

变量的类型。有效的类型包括string、 int、 float 和 nb。nb含义是非空字符串。type属性是必需的，用于把变量转换成适当的类型。

column=string

用来进行测试的SQL列的名称。这个属性默认为变量名称。

multiple=boolean

如果为真，那么变量可以是一个序列。

optional=boolean

如果为真，那么测试是可选择项，如果变量为空或不存在，它将不被处理。

op=string

比较操作。有效的比较包括以下：

eq: 等于
gt: 大于
lt: 小于
ne: 不等于
ge: 大于或等于
le: 小于或等于

默认的比较是等于。

12.3. 例子

基本用法：

  select * from employees
    where <dtml-sqltest name type="nb">

如果name 变量是Bob，那么这会呈递为：

  select * from employees
    where name = Bob

多个值：

  select * from employees
    where <dtml-sqltest empid type=int multiple>

如果empid 变量是(12,14,17)，那么结果为：

  select * from employees
    where empid in (12, 14, 17)

12.4. 参见

sqlgroup 标记符

sqlvar 标记符

13. sqlvar：插入SQL变量

sqlvar 标记符把变量插入到SQL代码中。这个标记符用在SQL方法中。

13.1. 句法

sqlvar 标记符句法:

  <dtml-sqlvar Variable|expr="VariableExpression">

sqlvar 标记符是一种独立标记符。就像var 标记符，sqlvar 标记符查找变量并插入它。不同于var标记符的是，它的格式选项是为了用于调整SQL代码。

13.2. 属性

type=string: 变量的类型。有效的类型包括string、 int,、 float 和 nb。nb含义为非空字符串。类型属性是必需的，用来把一个被插入的变量转换成相应的类型。
optional=boolean: 如果为真并且变量为空或者不存在，那么不插入任何内容。

13.3. 例子

基本用法：

  select * from employees 
    where name=<dtml-sqlvar name type="nb">

这段SQL引用name字符串变量

13.4. 参见

sqltest 标记符

14. tree：插入一个树部件

tree 标记符通过查询Zope对象显示一个动态的树部件。

14.1. 句法

tree 标记符句法：

  <dtml-tree [VariableName|expr="VariableExpression"]>
  </dtml-tree>

tree 标记符是一种块标记符。它显示一个HTML形式的动态树部件。树的根由变量或表达式给定。另外，它默认为当前的对象。通过把当前的节点映射成DTML名称空间，对每个节点进行树处理。树的状态被设置在HTTP cookies中。这样，要使用树，就必须激活cookies 。另外，每页只显示一个树。

14.2. 属性

branches=string: 通过调用指定的方法查找树的分支。默认的方法是tpValues，大多数Zope对象支持它。
branches_expr=string: 通过对表达式求值来查找树的分支。
id=string: 用于判断树的状态的方法或id的名称。它默认为tpId，大多数Zope对象都支持它。这个属性只适合高级用法。
url=string: 用于判断树的数据项URL的方法或属性的名称。它默认为tpURL，大多数Zope对象都支持它。这个属性适合高级用法。
leaves=string: 用来处理没有子项的节点的DTML文档或方法的名称。注意：这个文档应该以<dtml-var standard_html_header>，以<dtml-var standard_html_footer>结束，从而确保正确的在树中显示
header=string: 节点展开以前被显示的DTML文档或方法的名称。如果页眉没有被找到，它就被忽略掉。
footer=string: 节点展开以后被显示的DTML文档或方法的名称。如果页脚没有被找到，它就被忽略掉。
nowrap=boolean: 如果为真，那么节点不是被隐藏起来，节点而是按照现有大小被缩短。
sort=string: 按照指定的属性对分支进行排序。
reverse: 颠倒分支的次序。
assume_children=boolean: 假设节点有子项。如果取得和查询子节点比较费时，则比较适用。加号框可以显示在所有节点旁边。
single=boolean: 只允许一次展开一个分支。当你展开一个新的分支时，任何其他的已经展开的分支关闭。
skip_unauthorized: 忽略用户不允许看到的节点，而不是引发一个错误。
urlparam=string: 这是包含在展开和缩进部件连接里的查询字符串。这个属性只适用于高级用法。
prefix=string: 名称前缀，可用string替代"tree"，并使用“_”符号，而不是“-”符号。前缀必须以字母开始，可包含字母、数字和下划线。

14.3. 标记符变量

tree-item-expanded: 如果当前的节点已经展开则为真。
tree-item-url: 当前节点的URL。
tree-root-url: 根节点的URL。
tree-level: 当前节点的深度。顶级节点的深度为0。
tree-colspan: 正在显示的树的最大层级。当把行插入到树表格中时，这个变量可以随同树级变量用来计算表格行和列跨度设置。
tree-state: 用id列表和id列表子集表示的树的状态。这个变量只适用于高级用法。

14.4. 标记符控制变量

通过设置以下变量，你可以控制树标记符。

expand_all: 如果这个变量为真，那么整个树是展开的。
collapse_all: 如果这个变量为真，那么整个树是合拢的。

14.5. 例子

对当前对象生成树：

  <dtml-tree>
    <dtml-var title_or_id>
  </dtml-tree>

用指定的分支方法在对另外一个对象生成树：

  <dtml-tree expr="folder.object" branches="objectValues">
    Node id : <dtml-var getId>
  </dtml-tree>

15. try：处理例外

try标记符使你能够用DTML处理例外。相应于Python中的try/except 和 try/finally结构。

15.1. 句法

try标记符有两个不同的句法，try/except/else 和 try/finally try/except/else 句法:

  <dtml-try>
  <dtml-except [ExceptionName] [ExceptionName]...>
  ... 
  [<dtml-else>]
  </dtml-try>

try标记符在一个块中捕捉和处理例外。可以使用有一个或多个except标记符处理无例外或多个例外。如果一个except标记符没有指定例外，那么它处理所有的例外。

当例外被引发，立即让第一个标记符处理这个例外。如果没有except标记符来处理例外，那么例外以通常的方式引发。

如果没有引发例外，并且有一个else标记符，那么else标记符在try标记符正文以后执行。

except 和 else标记符是可选择的。

try/finally句法

  <dtml-try>
  <dtml-finally>
  </dtml-try>

finally标记符不能象except 和 else 标记符那样在相同的try块中使用。如果有一个finally标记符，它的块不管例外在try块内是否被引发都将执行。

15.2. 属性

except: 0个或多个例外名称。如果没有列出例外，那么except标记符处理所有的例外。

15.3. 标记符变量

在except块内部定义了这些变量：

error_type: 例外类型。
error_value: 例外的值。
error_tb: 回溯（traceback）

15.4. 例子

捕捉一个数学错误：

  <dtml-try>
  <dtml-var expr="1/0">
  <dtml-except ZeroDivisionError>
  You tried to divide by zero.
  </dtml-try>

返回关于被处理的例外的信息：

  <dtml-try>
  <dtml-call dangerousMethod>
  <dtml-except>
  An error occurred.
  Error type: <dtml-var error_type>
  Error value: <dtml-var error_value>
  </dtml-try>

使用finally来确保正常执行，不管是否引发一个错误：

  <dtml-call acquireLock>
  <dtml-try>
  <dtml-call someMethod>
  <dtml-finally>
  <dtml-call releaseLock>
  </dtml-try>

15.5. 参见

raise 标记符

Python 文档: 错误和例外 Python 内建例外

16. unless：测试一个条件

unless标记符提供了一个测试相反条件的快捷方式。对于更为完整的条件测试，请使用if标记符。

16.1. 句法：

unless 标记符句法:

  <dtml-unless ConditionVariable|expr="ConditionExpression">
  </dtml-unless>

unless标记符是一种块标记符。如果条件变量或表达式求值为假，那么就执行块中所包含内容。就像if标记符，没有提供变量则为假。

16.2. 例子：

测试一个变量：

  <dtml-unless testMode>
    <dtml-call dangerousOperation>
  </dtml-unless>

如果testMode不存在就执行这个块，或者只要为假就退出。

16.3. 参见

if 标记符

17. var：插入一个变量

var标记符使你能够把一个变量插入到DTML输出中。

17.1. 句法

var标记符句法：

  <dtml-var Variable|expr="Expression">

var标记符是一种独立标记符。var标记符通过搜索DTML名称空间查找一个变量，DTML名称空间通常包括当前对象、当前对象的容器和Web请求。如果变量找到，就把它插入到DTML输出中。如果它没有找到，Zope引发一个错误。

var标记符实体句法：

  &dtml-variableName;

实体句法是一种在HTML中插入变量的快捷方式。适用于把当把变量插入到HTML标记符中。

带有属性的var标记符实体句法：

  &dtml.attribute1[.attribute2]...-variableName;

在某种程度上，你可以用实体句法指定属性。可以包含0个或多个用句点分开的属性。你不能使用实体句法为属性提供参数。如果你提供0个或多个属性，那么变量不能自动被HTML引用。这样一来，你可以避免使用这种句法的HTML引用，&dtml.-variableName;。

17.2. 属性

html_quote: 把在HTML中具有特定含义的字符转换成HTML字符实体。
missing=string: 在Zope不能找到变量的情况下，指定一个默认值。
fmt=string: 格式一个变量。Zope提供一些内建的格式，包括C风格的格式字符串。关于C风格的格式字符串方面的信息，请见Python库参考。如果格式字符串不是一个内建格式，那么假定为一个对象方法，然后调用它。
whole-dollars: 按美元格式处理变量。
dollars-and-cents: 按美元和美分格式处理变量。
collection-length: 变量的长度，假设它是一个序列。
structured-text: 按照结构文本格式化变量。关于结构文本方面的更多信息，请见Zope.org Web站点中的Structured Text How-To (http://www.zope.org/Members/millejoh/structuredText)。
null=string: 如果变量为None时使用的默认值。
lower: 把大写字母转换成小写字母。
upper: 把小写字母转换成大写字母。
capitalize: 把被插入的单词的首个字符变成大写。
spacify: 把被插入的值中的下划线更改成空格。
thousands_commas: 在包含数字的值中，从小数点左边开始每隔三个数字插入逗号，例如12000 变为 12,000 。
url: 通过调用对象的absolute_url方法插入对象的URL 。
url_quote: 把URL中具有特殊含义的字符转换成HTML字符实体。
url_quote_plus: URL引用字符，就像url_quote ，但是它还把空格转换成加号。
sql_quote: 把单引号转换为成对的单引号。在SQL字符串中包含字符时需要用到它。
newline_to_br: 把换行符（包含回车）转换成HTML换行符。
size=arg: 按照给定长度截取变量（注意：如果在被截取的字符串的下半部有空格，那么字符串被截取到最右边的空格。
etc=arg: 指定一个用来添加到被截取的字符串（通过设置前边所述的size属性）结尾处的字符串。默认为… 。

17.3. 例子

在一个文档中插入一个简单变量：

  <dtml-var standard_html_header>

补加：

  <dtml-var colors size=10 etc=", etc.">

如果colors是字符串red yellow green，生成以下输出： red yellow, etc.

C风格字符格式：

  <dtml-var expr="23432.2323" fmt="%.2f">

结果为 23432.23

用实体句法在一个HTML A标记符内插入一个变量链接：

  <a href="&dtml-link;">Link</a>

使用带有属性的实体句法给一个文档 doc 加入一个链接：

  <a href="&dtml.url-doc;"><dtml-var doc fmt="title_or_id"></a>

这样就给这个对象创建一个使用它的URL和标题的HTML链接。这个例子针对URL（使用url属性）调用对象的absolute_url 方法，针对标题调用它的title_or_id方法。

18. with：控制查找DTML变量

with标记符把一个对象推进到DTML名称空间。变量首先在被加入的对象中查找。

18.1. 句法

with标记符句法：

  <dtml-with Variable|expr="Expression">
  </dtml-with>

with 标记符是一种块标记符。它在with块的持续期间内把指定的变量或变量表达式推进到DTML名称空间中。这样，首先就在被添加的对象中查找名称。

18.2. 属性

only: 把DTML名称空间限制在with标记符中定义的名称空间。
mapping: 表示变量或表达式是一个映射对象。这样就确保在mapping对象里正确查找变量。

18.3. 例子

在REQUEST里查找一个变量：

  <dtml-with REQUEST only>
    <dtml-if id>
      <dtml-var id>
    <dtml-else>
      id was not in the request.
    </dtml-if>
  </dtml-with>

把first child添加到DTML名称空间：

  <dtml-with expr="objectValues()[0]">
    First child's id: <dtml-var id>
  </dtml-with>

18.4. 参见

let 标记符

From Jamiesun Sat Mar 20 17:53:52 +0800 2004 From: Jamiesun Date: Sat, 20 Mar 2004 17:53:52 +0800 Subject: 他 Message-ID: <20040321095352+0800@www.czug.org>

由于不能

中国Zope/Plone用户组

Sections

Personal tools

Document Actions

DTML参考

1. call:调用一个方法

1.1. 句法

1.2. 例子

1.3. 参见

2. comment: 注释DTML

2.1. 句法

2.2. 例子

3. Functions：DTML函数

3.1. 函数

3.2. 属性

3.3. 参见

4. if：测试条件

4.1. 句法

4.2. 例子

4.3. 参见

5. in：对序列进行循环

5.1. 句法

5.2. 属性

5.3. 标记符变量

5.3.1. 当前数据项变量

5.3.2. 总结变量

5.3.3. 分组变量

5.3.4. 批处理变量

5.4. 例子

6. let：定义DTML变量

6.1. 句法

6.2. 例子

6.3. 参见

7. mime:用MIME格式数据

7.1. 句法

7.2. 属性

7.3. 例子

7.4. 参见

8. raise：引发一个例外

8.1. 句法

8.2. 例子

8.3. 参见

9. return: 返回数据

9.1. 句法

9.2. 例子

10. sendmail: 通过SMTP发送邮件

10.1. 句法

10.2. 属性

10.3. 例子

10.4. 参见

11. sqlgroup：处理复杂的SQL表达式格式

11.1. 句法

11.2. 属性

11.3. 例子

11.4. 参见

12. sqltest: 处理SQL条件测试格式

12.1. 句法

12.2. 属性

12.3. 例子

12.4. 参见

13. sqlvar：插入SQL变量

13.1. 句法

13.2. 属性

13.3. 例子

13.4. 参见

14. tree：插入一个树部件

14.1. 句法

14.2. 属性

14.3. 标记符变量

14.4. 标记符控制变量

14.5. 例子

15. try：处理例外

15.1. 句法

15.2. 属性

15.3. 标记符变量

15.4. 例子

15.5. 参见

16. unless：测试一个条件

16.1. 句法：

16.2. 例子：