例

ユーザの名前を挿入する :

        <p tal:content="user/getUserName">Fred Farkas</p>

HTML/XML を挿入する :

        <p tal:content="structure here/getStory">marked <b>up</b>

        content goes here.</p>

こちらも参照してください

tal:replace

define: 変数を定義する

構文

tal:define の構文:

        argument       ::= define_scope [';' define_scope]*
        define_scope   ::= (['local'] | 'global') define_var
        define_var     ::= variable_name expression
        variable_name  ::= Name

*注意: '式' にセミコロン(;)を含めたい場合はセミコロンを2つ並べて(;;)エスケープしてください。*

説明

tal:define 文は変数を定義します。 ローカルとグローバルの2種類のTAL変数を定義できます。 エレメントでローカル変数を定義すると、定義されたエレメント内においてのみその変数を使うことができます。 エレメントの入れ子になった内側で同じ名前のローカル変数を定義すると、新しく定義したことによって、外側のエレメントで定義したことは、内側のエレメント内では有効ではありません。 グローバル変数は、定義したエレメントより後にある任意のエレメントで使えます。 グローバル変数を定義しなおすと、定義しなおした箇所より後にあるテンプレートで、定義が置き換えられます。

*注意: デフォルトではローカル変数です*

変数の式が nothing と評価されると、その変数の値は nothing になり、以降の式で nothing として使えます。 同様に、変数の式が default と評価されると、その変数の値は default になり、以降の式で default として使えます。

例

グローバル変数を定義する :

        tal:define="global company_name string:Zope Corp, Inc."

変数を2つ定義する(2つめの変数は1つめの変数に依存) :

        tal:define="mytitle template/title; tlen python:len(mytitle)"

omit-tag: コンテンツを残したまま、エレメントを削除する

構文

tal:omit-tag の構文:

        argument ::= [ expression ]

説明

tal:omit-tag 文は開始タグと終了タグを除去しますが、エレメントのコンテンツはそのままにします。

式が「偽」と評価されるとエレメントは普通に処理され、タグは削除されません。 「真」と評価されたり式がない場合は、文のエレメントはコンテンツに置き換えられます。

Zope は空の文字列、空のシーケンス、0、 None、 nothing を「偽」とみなします。 それ以外のすべての値は default も含めて「真」とみなします。

例

常にタグを削除する :

        <div tal:omit-tag="" comment="このタグは削除されます">
          <i>...だけど、テキストはそのままです。</i>
        </div>

場合によってはタグを削除する :

        <b tal:omit-tag="not:bold">ここはボールド体かもしれない</b>

上の例では bold 変数が「偽」と評価されると b を削除します。

囲っている span タグを表示せずに p タグを10個作成します。 :

        <span tal:repeat="n python:range(10)"
              tal:omit-tag="">
          <p tal:content="n">1</p>
        </span>

on-error: エラー処理

構文

tal:on-error の構文:

        argument ::= (['text'] | 'structure') expression

説明

tal:on-error 文はテンプレートでのエラー処理に使います。 TAL 文がエラーになると、TAL インタープリタは同じエレメント、エレメントが囲まれているエレメント、、、というように tal:on-error 文を探します。 最初に見つかった tal:on-error が呼び出されて、 tal:content 文として扱われます。

A local variable error is set. This variable has these attributes:

エラーが起こるとローカル変数の error がセットされ、この変数には次の3つのアトリビュートがあります。 :

        'type' -- 例外の型

        'value' -- 例外のインスタンス

        'traceback' -- トレースバックオブジェクト

もっとも単純な tal:on-error 文は式がエラーメッセージ用の文字列か nothing です。 もう少し複雑な処理になると、エラーを伝えるために、エラーを調べ、エラーメッセージを送信したり、例外を投げるスクリプトを呼び出します。

例

単純なエラーメッセージ :

        <b tal:on-error="string: Username が定義されていません!" 
         tal:content="here/getUsername">Ishmael</b>

エラーの際にはエレメントを削除する:

        <b tal:on-error="nothing"
           tal:content="here/getUsername">Ishmael</b>

エラー処理用スクリプトを呼び出す:

        <div tal:on-error="structure here/errorScript">
          ...
        </div>

エラー処理用のスクリプトは次のようになるでしょう :

        ## Script (Python) "errHandler"
        ##bind namespace=_
        ##
        error=_['error']
        if error.type==ZeroDivisionError:
            return "<p>0 では割れません</p>"
        else
            return """<p>エラーが起きました</p>
                      <p>Error type: %s</p>
                      <p>Error value: %s</p>""" % (error.type,
                                                   error.value)

こちらも参照してください

Python Tutorial: Errors and Exceptions

Python Built-in Exceptions

repeat: エレメントを繰り返す

構文

tal:repeat の構文:

        argument      ::= variable_name expression
        variable_name ::= Name

説明

tal:repeat 文はドキュメントの一部を1アイテムずつ走査します. 式はシーケンス(リスト)でなければいけません。 シーケンスが空の場合は、エレメントは削除され、空でなければシーケンスの各アイテムを繰り返します。 式が default の場合は、エレメントは変更されず、新たに変数が定義されることもありません。

ローカル変数と繰り返し変数の定義には variable_name が使われます。 繰り返すたびに、ローカル変数が現在のシーケンスのアイテムにセットされ、繰り返し変数は繰り返しオブジェクトにセットされます。

繰り返し変数

現在の(インデックスなど)繰り返しについて知るには、繰り返し変数を使います。 繰り返し変数はローカル変数と同じ名前ですが、組み込み変数の repeat からしかアクセスできません。

繰り返し変数を使うと以下のような情報を取得することができます :

• index - 0空始まる繰り返し数
• index - 1から始まる繰り返し数
• even - 繰り返しのインデックスが偶数の場合に真となる(0, 2, 4, ...).
• odd - 繰り返しのインデックスが奇数の場合に真となる(1, 3, 5, ...).
• start - 繰り返しの最初で真となる(インデックスは 0).
• end - 繰り返しの最後で真となる
• first - グループの中で先頭の場合に真となる - 下の注をご覧ください
• last - グループの中で最後の場合に真となる - 下の注をご覧ください
• length - シーケンスの長さで、繰り返す総数です。
• letter - 繰り返しの番号に、小文字を使います: "a" - "z", "aa" - "az", "ba" - "bz", ..., "za" - "zz", "aaa" - "aaz", などなど。
• Letter - letter を大文字にしたものです。
• roman - 繰り返し番号の小文字のローマ数字を使います: "i", "ii", "iii", "iv", "v", etc.
• Roman - roman の大文字版です。

「繰り返し変数」にアクセスするには path 式、あるいは Python 式を使います。 path 式を使う場合、repeat という文字列に続けて変数名を記述し、その後得たい情報の3つを記述します。 たとえば、'repeat/item/start'のようにします。 Python 式では、繰り返し変数の取得には辞書と同じ表記法を使い、知りたい情報はアトリビュートでアクセスします。 たとえば、 "python:repeat['item'].start" のようにします。

start, end, index を例外として、残りすべての繰り返し変数のアトリビュートはメソッドです。 したがって、Python 式でこれらにアクセスする場合、 "python:repeat['item'].length()" というように呼び出さなくてはいけません。

first と last はソートされたシーケンスのためのものであることに注意してください。 シーケンスを同じ値同士でグループに分けようとするからです。

パスを指定すると、 シーケンスをパスからたどって得られる値でグループ化が行われ、 指定しなければ、アイテムの値がgグループ化に使われます。

"python:repeat['item'].first(color)" というようにパラメータに渡したり、 "repeat/item/first/color" というように繰り返し変数の最後につけることでパスを指定することもできます。

例

文字のシーケンスを走査します:

        <p tal:repeat="txt python:'one', 'two', 'three'">

           <span tal:replace="txt" />
        </p>

繰り返し変数を使って、番号を振った行をテーブルに挿入します :

        <table>
          <tr tal:repeat="item here/cart">

              <td tal:content="repeat/item/number">1</td>
              <td tal:content="item/description">Widget</td>
              <td tal:content="item/price">$1.50</td>
          </tr>

        </table>

入れ子になった繰り返し :

        <table border="1">
          <tr tal:repeat="row python:range(10)">
            <td tal:repeat="column python:range(10)">

              <span tal:define="x repeat/row/number; 
                                y repeat/column/number; 
                                z python:x*y"
                    tal:replace="string:$x * $y = $z">1 * 1 = 1</span>
            </td>
          </tr>
        </table>

オブジェクトの挿入。 ルールを決ることにより、オブジェクトをメタタイプごとにグループにする。 :

        <div tal:repeat="object objects">
          <h2 tal:condition="repeat/object/first/meta_type"
            tal:content="object/meta_type">Meta Type</h2>
          <p tal:content="object/getId">Object ID</p>
          <hr tal:condition="repeat/object/last/meta_type" />

        </div>

注意: 上の例では、オブジェクトはメタタイプによってソートされていなければいけません。

replace: エレメントを置き換える

構文

tal:replace の構文:

        argument ::= (['text'] | 'structure') expression

説明

tal:replace 文はエレメントを動的なコンテント(文字列など)に置き換えます。 つまり、文のエレメントをテキストや structure(エスケープされていないマークアップ) に置き換えます。 文は式で、場合によっては型をあらわす接頭語を伴います。 接頭語に text を使ったり、接頭語を省くと、式はエスケープされた文字列になります。 structure を使うと、エスケープされないまま挿入されます。 文字列のエスケープは "&" を "&amp;"に、 "<" を "&lt;"に、 ">" を "&gt;" に変換します。

値が value の場合、エレメントは削除されます。値が default の場合、エレメントは元のままです。

例

テンプレートのタイトルを挿入するには2通りあります。 :

        <span tal:replace="template/title">タイトル</span>

        <span tal:replace="text template/title">タイトル</span>

HTML/XML を挿入します。 :

        <div tal:replace="structure table" />

何も挿入しません。 :

        <div tal:replace="nothing">このエレメントはコメントです</div>

こちらも参照してください

tal:content

TALES の概要

Template Attribute Language Expression Syntax (TALES) の仕様では、 TALとMETALにデータを与える「式」について解説します。 TALES はこれらの言語で使える *唯一の* 式を表す構文ですが、 限定されてはいません。 同様に、TALES は TAL や METAL と関係のないところで使用することもできます。

高級言語のレイヤーにあたる「区切り文字」や「引用記号」などを省くと、TALES 式は下で書かれているようになります。 TALES 構文の基本となる構文は次のように定義されています :

      Expression  ::= [type_prefix ':'] String
      type_prefix ::= Name

シンプルな例です :

      a/b/c
      path:a/b/c
      nothing
      path:nothing
      python: 1 + 2
      string:Hello, ${user/getUserName}

オプションの「型の接頭語」はそれに続く *式* のセマンティックと構文を決定します。 TALES では好きな構文で式の型をいくらでも定義できるよう実装されています。 接頭語を省くとどの型になるのかということも定義されています。

「型プリフィクス」を指定しなければ、Zope は path 式と解釈します。

TALES 式の型

Zope の TALES 式では次にあげる型に対応しています :

• path expressions - パスで値を指定します
• exists expressions - パスが存在するかテストします
• nocall expressions - パスでオブジェクトを指定します
• not expressions - 式の否定です
• string expressions - 文字列を整形します
• python expressions - Python の式を実行します

組み込みの名前

Zope の TALES 式では次に挙げる名前が使えます。

• nothing - (void, None, Nil, NULL) のような「無」をあらわすのに使われる特別な値です。
• default - 元のテキストを置き換えないようにする際に使われる特別な値です。 各 TAL 文が default をどう解釈するかは個別のドキュメントをご覧ください。
• options - テンプレートに渡す *キーワード* 引数です。 テンプレートがメソッドやスクリプトから呼び出された際にオプションを利用する場合が多いでしょう。
• repeat - repeat 変数です。 tal:repeat のドキュメントをご覧ください。
• attrs - 文のタグに含まれるアトリビュートの初期値を収めた辞書です。
• CONTEXTS - 名前のリストです(このリストのことです)。 ローカル変数やグローバル変数が組み込みの変数が隠している場合に、組み込み変数にアクセスする際に使います。
• root - システムの最上に似あるオブジェクトです。Zope のルートフォルダです。
• here - テンプレートを適用しているオブジェクトです。
• container - テンプレートのあるフォルダです。
• template - テンプレートそのものです。
• request - リクエストオブジェクトです。
• user - 認証ユーザのオブジェクトです。
• modules - アクセス可能な Python モジュールやパッケージを集めたものです。 Zope のセキュリティ・ポリシーで認められたもののみがアクセスできます。

root, here, container, template, request, user,modules はZopeでサポートされている名前であって、 TALES の規格には含まれていないことに注意してください。

こちらも参照してください

TAL Overview

METAL Overview

exists expressions

nocall expressions

not expressions

string expressions

path expressions

python expressions

TALES の exist 式

構文

exist 式の構文 :

        exists_expressions ::= 'exists:' path_expression

説明

exist 式はパスが存在するかどうか(exist)テストします。 exist 式は exist に続けて書かれたPath式が値を返すと真を返します。 Path式がオブジェクトを見つけられないと、偽を返します。

例

シーケンスをテスト :

        <p tal:condition="not:here/objectIds">
          オブジェクトは含まれていません
        </p>

TALES のPath式

構文

Path 式の構文 :

        PathExpr    ::= Path [ '|' Expression ]
        Path        ::= variable [ '/' PathSegment ]*
        variable    ::= Name
        PathSegment ::= ( '?' variable ) | PathChar+
        PathChar    ::= AlphaNumeric | ' ' | '_' | '-' | '.' | ',' | '~'

説明

Path式は「パス」と、場合によっては垂直なバー(|)に続く「代替の式」から構成されます。 パスは、スラッシュで区切られた一つ以上の「空でない文字列」からなります。 最初の文字列は変数名(組み込み変数かユーザが定義した変数)でなくてはならず、残りの文字列(「パスの一部」)は文字列、数字、スペース、アンダースコア、ダッシュ、ピリオド、コンマ、チルダの文字が使えます。

パスの一部で変数名を ? ではじめることにより、「間接参照」も使えます。

例:

        request/cookies/oatmeal
        nothing
        here/some-file 2001_02.html.tar.gz/foo
        root/to/branch | default

        request/name | string:Anonymous Coward
        here/?tname/macros/?mname

Path式が評価されると、パスを左から右へZopeは成功するするかパスの最後にたどり着くまでトラバースします。 パスをトラバースする際には、最初に変数に保存されたオブジェクトを取得します。 パスの各部分では、現在のオブジェクトの位置から、次のパスに書かれているサブオブジェクトへトラバースします。 サブオブジェクトはZopeがトラバースするルール(getattr, getitem, トラバース・フックを使う)によって探されます。

パスをうまくトラバースできると、帰ってくるオブジェクトはその式の値です。 メソッドやテンプレートのように、呼び出し可能なオブジェクトの場合、呼び出されます。

トラバースの段階で失敗し、かつ代わりの式もない場合、エラーになります。 代わりの式があれば、そちらが評価されます。

代わりの式はどんな TALES 式でもかまいません。 たとえば、 request/name | string:Anonymous Coward というPath式も大丈夫です。 (Path式では表せられない)文字列や数字などをデフォルトの値にしたい場合にとりわけ便利です。 代わりの式はPath式でもいいので、次のようにPath式を「つなげる」こともできます first | second | third | nothing 。

パスが指定されない場合、 nothing 扱いになります。

パスは変数名ではじめなければいけないので、別のオブジェクトや値を見つけるためにはいくつかの開始変数が必要です。 組み込み変数のリストは TALES の概要をご覧ください。 変数名はローカル空間、グローバル空間、組み込みの順に探索されるので、組み込み変数の扱いは Python でのそれと同じです。 組み込み変数はいつでも使えますが、ローカル変数やグローバル変数の宣言によって、隠蔽されてしまうこともあります。 組み込み変数は CONTEXTS を明示的に接頭すれば、いつでもアクセス可能です(つまり、 CONTEXTS/root, CONTEXTS/nothing, など)。

例

クッキーの変数を挿入するか、なければプロパティを挿入します :

        <span tal:replace="request/cookies/pref | here/pref">
          preference
        </span>

ユーザ名を挿入します :

        <p tal:content="user/getUserName">
          User name
        </p>

構文

Python 式の構文 :

        任意のPython式

説明

Python式はセキュリティ上の制約のある環境でPythonのコードを評価します。 Python式は Script Python や DTML でのものと同じことができます。

セキュリティの制約

Python式は Script(Python) と同じセキュリティ上の制約があります。 次の制約があります:

アクセス制限

Python式はZopeのパーミッションとロールセキュリティの制限を受けます。 さらに、Python式では、名前がアンダースコアではじまるオブジェクトにアクセスできません。

書き込み制限

Python 式では Zope オブジェクトのアトリビュートを変更できません。

このような制約があっても、悪意のある Python 式が問題を引き起こすことがあります。

組み込み関数

Python 式には Script Python の使える組み込み関数にさらに追加された関数が使えます。

次にあげる Python 標準の組み込み関数が使えます : None, abs, apply, callable, chr, cmp, complex, delattr, divmod, filter, float, getattr, hash, hex, int, isinstance, issubclass, list, len, long, map, max, min, oct, ord, repr, round, setattr, str, tuple.

range 関数と pow 関数は利用でき、標準のPythonと同じように振舞いますが、大きな数やシーケンスは制限されています。 この制限はZopeをサービス・アタックから守るのに役立っています。

さらに、次にあげるユーティリティ関数が使えます: DateTime, test, same_type 。 これらの関数にういては、 DTML 関数の欄をご覧ください。

次にあげる関数は Script(Python)にはありませんが、 Python式では使えます :

path(string)

TALES のPath式を評価

string(string)

TALES の文字列の式を評価

exists(string)

TALES の exist 式を評価

nocall(string)

TALES の nocall 式を評価

Python モジュール

デフォルトの状態で利用できるPythonモジュールがあります。 また、もっとたくさんのモジュールを使えるようにすることもできます。 モジュールは ( module/string/join のように) Path式でアクセスするか、 (modules["string"].join のように) modules を 辞書オブジェクトとしてアクセスすることができます。 デフォルトで利用できるモジュールです ::

string

Python string module です。このモジュールにある多くの関数はストリングメソッドとしても呼び出せることに注意してください。

random

Python random module です.

math

Python math module です.

sequence

強力なソート関数を備えたモジュールです。詳細はシーケンスをご覧ください。

Products.PythonScripts.standard

DTML でつかえるHTMLをフォーマットするためのさまざまな関数です。 詳細は Products.PythonScripts.standard をご覧ください。

ZTUtils

dtml-in にあるものに似たバッチ処理用のものです。 詳細は ZTUtils をご覧ください。

AccessControl

セキュリティとアクセス権限を確認するためのものです。 詳細は AccessControl をご覧ください。

例

モジュールの使い方です(リストの中からランダムに一つ選択します):

        <span tal:replace="python:modules['random'].choice(['one', 
                             'two', 'three', 'four', 'five'])">

          1から5の間にあるランダムな数
        </span>

文字列処理 (ユーザ名の一文字目を大文字にします):

        <p tal:content="python:user.getUserName().capitalize()">
          ユーザ名
        </p>

初歩的な数学 (画像のサイズをメガバイトに変換):

        <p tal:content="python:image.getSize() / 1048576.0">
          12.2323
        </p>

文字の整形 (浮動小数点を小数点以下２桁まで表示):

        <p tal:content="python:'%0.2f' % size">

          13.56
        </p>

TALES の文字列式

構文

String 式の構文 :

        string_expression ::= ( plain_string | [ varsub ] )*
        varsub            ::= ( '$' Path ) | ( '${' Path '}' )
        plain_string      ::= ( '$$' | non_dollar )*
        non_dollar        ::= any character except '$'

説明

「String 式」は文字列の式をテキストとみなします。 式に文字列を与えなかった場合、文字列は「空」の文字列になります。 文字列には置換用の変数を $name や ${path} というように含めることができます。ここで、 name は変数の名前で、 path はPath式です。 Path式の値はエスケープされて文字列に挿入されます。 '$' を置換用の記号と認識させないためには、 $$ でエスケープします。

例

基本的な文字列の整形 :

        <span tal:replace="string:$this and $that">
          スパムと卵
        </span>

Path式を使う:

        <p tal:content="string:total: ${request/form/total}">
          total: 12
        </p>

ドル記号を含める :

        <p tal:content="string:cost: $$$cost">
          cost: $42.00
        </p>

METAL の概要

*Macro Expansion Template Attribute Language(マクロ展開テンプレートアトリビュート言語)* (METAL) は HTML/XML のマクロを処理するためのものです。 METAL は TAL や TALES と一緒に使うことも個別に使うこともできます。

マクロはテンプレートで見た目の一部を定義するもので、異なるテンプレートであっても同じマクロを共有できます。 そのためマクロに変更を加えると、同じマクロを使っているテンプレート全部が直ちに反映されます。

さらに、テンプレートのソーステキストであっても、テンプレートがレンダリングされた状態に見えるよう、マクロは常に完全に展開されます。

METAL の名前空間

METAL 用名前空間のURIと推奨されるエイリアスは、現在次のように定義されています。 :

        xmlns:metal="http://xml.zope.org/namespaces/metal"

TAL名前空間のURIと同様、URI はウェブページのためではなく、単に一意的な識別名です。

Zope では text/html というコンテント・タイプのテンプレートが作成された時に XML 名前空間が宣言されなくてもかまいませんが、その他すべてのコンテント・タイプに対しては、XML名前空間を宣言しなければいけません。

METAL Statements

METAL 文

METAL defines a number of statements:

METAL はいくつかの文を定義しています:

• metal:define-macro - マクロを定義する。
• metal:use-macro - マクロを使う。
• metal:define-slot - カスタマイズ可能なマクロを定義する。
• metal:fill-slot - マクロをカスタマイズする。

METAL は非終端の式を表す構文を実装に任せていて、定義していませんが、 METAL 引数で使われる 正準式の構文は TALES の仕様で述べられています。

こちらも参照してください

TAL Overview

TALES Overview

metal:define-macro

metal:use-macro

metal:define-slot

metal:fill-slot

define-macro: マクロを定義

構文

metal:define-macro の構文:

        argument ::= Name

説明

metal:define-macro 文はマクロを定義します。 マクロは式文によって名づけられ、エレメントと部分木で定義されます。

Zopeでは、マクロの定義はテンプレートの macro オブジェクトのサブオブジェクトとして利用できます。 たとえば、テンプレート master.html にある header というマクロにアクセスするには、 master.html/macros/header というPath式が使えます。

例

単純なマクロの定義 :

        <p metal:define-macro="copyright">
          Copyright 2004, <em>Foobar</em> Inc.
        </p>

こちらも参照してください

metal:use-macro

metal:define-slot

define-slot: カスタムできるマクロを定義

構文

metal:define-slot の構文:

        argument ::= Name

説明

metal:define-slot 文は、部分的にカスタマイズ可能な部分や「スロット(slot)」を定義します。 マクロを利用する際、マクロの一部をカスタマイズするために「スロット」内部を置換することができます。 また、スロットの定義はスロット内の「デフォルトコンテント」を提供します。 マクロを利用する際、スロットを利用しないとデフォルトコンテントが利用されます。

metal:define-slot 文は、必ず metal:define-macro 文の中で利用してください。

またスロットの名前はマクロの中で一意である必要があります。

例

スロットのついた単純なマクロ :

        <p metal:define-macro="hello">
          Hello <b metal:define-slot="name">World</b>
        </p>

この例では、name という名前のスロットを定義しています。 このマクロを利用する際、b エレメントは name というスロットで埋められます。

こちらも参照してください

metal:fill-slot

fill-slot: Customize a macro

構文

metal:fill-slot の構文:

        argument ::= Name

説明

metal:fill-slot 文は、スロットのエレメント(およびコンテント) を置き換えることによってマクロをカスタマイズします。

metal:fill-slot 文は 必ずmetal:use-macro 文内で利用する必要があります。

またスロットの名前はマクロの中で一意である必要があります。

マクロ内に指定された名前のスロットが存在しない場合、スロットのコンテントはマクロに影響を与えません。

例

このようなマクロが定義されている場合:

        <p metal:define-macro="hello">
          Hello <b metal:define-slot="name">World</b>

        </p>

name スロットを以下のように「埋める(fill)」ことができます:

        <p metal:use-macro="container/master.html/macros/hello">
          Hello <b metal:fill-slot="name">Kevin Bacon</b>

        </p>

こちらも参照してください

metal:define-slot

use-macro: Use a macro

構文

metal:use-macro 構文:

        argument ::= expression

説明

metal:use-macro 文はマクロ内のエレメントを入れ替えます。 文の「式」はマクロの定義を示します。

Zopeでは、マクロの「式」は他のテンプレート上に定義されたするマクロをpath 式になります。 詳しくは "metal:define-macro" の欄をご覧ください。

マクロを展開するということは、別のドキュメント(または現在のドキュメント)にある部分を 特定のエレメント内に移植するようなものです。 スロットが定義されていれば、エレメント内にある特定のパーツはそのままの形で残ります。 詳しくは metal:define-slot という節を参照してください。 マクロの本文が他のマクロを含んでいる場合には、まずそのマクロが展開されます。

マクロが展開されるとき、マクロ内の metal:define-macro アトリビュートが metal:use-macro アトリビュートを置き換えます。 展開されたマクロ宣言があるエレメントが、use-macro が宣言されているエレメントに置換されます。

例

マクロの基本的な使用方法:

        <p metal:use-macro="container/other.html/macros/header">
          other.html テンプレートに定義されているヘッダ用マクロ
        </p>

この例では、 other.html テンプレートに定義されているヘッダのマクロを参照しています。 テンプレートはマクロを参照しているテンプレートと同じフォルダに設置されています。 マクロが展開されると、p エレメントとエレメント内のコンテントがマクロで置き換わります。

こちらも参照してください

metal:define-macro

metal:fill-slot

ZPT 固有の振る舞いについて

Zope Page Templates の「振る舞い」については、ほぼすべてTAL、TALES、METAL の仕様に記載されています。 Zope Page Templates には、これ以外にも追加の機能が存在します。

HTML をサポートする機能

Page Template の コンテント・タイプ が text/html に設定されている場合、Zope はテンプレートの出力に特別な処理を施します。 「TAL の名前空間」ですでに述べたように、HTML 文書では名前空間の宣言を必要としません。tal と metal の名前空間はデフォルトで提供されています。

HTML 文書は非XMLパーサによってパースされます。このため、記述に多少不正があってもエラーは起きません。 特に、パラグラフやリストといった「閉じタグ」のないタグは、tal 式が存在のであればエラーとして扱われません。 パースが曖昧に行われるため、次のような場合にはややこしいエラーを誘発するかも知れません。 <div> エレメントはブロック要素ですので、厳密には <p> タグの中に入れ子にすることはできません。このため、 <p> エレメントの次に <div> エレメントがあると、 <p> エレメントは「暗黙に」閉じたものとして扱われます。 このため、「閉じタグ」である </p> はエラーを起こします。<p> エレメントは暗黙に「閉じて」いるため、エレメントの対応が取れないのです。 この問題を回避するためには <span> を代わりに利用してください。

tal 式を持つエレメントが閉じていない場合は常にエラーになります。エレメントの終了部分の推測を誤ってわかりにくいエラーを誘発することを避けるためです。 このため、img や input といった、通常「閉じタグ」を記述する必要がないエレメントについても閉じタグを記述するか、XHTML 形式で<img ... /> のように記述する必要があります。

checked や selected のような「あるかないか」によって挙動を変えるアトリビュートについては、 tal:attributes と組み合わせて使う際に注意が必要です。 「値」は「真」または「偽」として評価されます( tal:condition での「真偽値」と同様です)。 「値」が真の場合、attr="attr" の attr がセットされ、「偽」の場合には省略されます。 値が default の場合は、アトリビュートがすでに存在している場合には「真」と同じ処理となり、存在していない場合には「偽」と同じ処理をします。 以下が例です :

        <input type="checkbox" checked tal:attributes="checked default">
        <input type="checkbox" tal:attributes="checked string:yes">
        <input type="checkbox" tal:attributes="checked python:42">

上の例はつずれも次のように出力されます:

        <input type="checkbox" checked="checked">

一方、次のような例は:

        <input type="checkbox" tal:attributes="checked default">
        <input type="checkbox" tal:attributes="checked string:">
        <input type="checkbox" tal:attributes="checked nothing">

以下のように出力されます:

        <input type="checkbox">

このような表記法は、手元にある Web ブラウザで動作することを確認済みです。