導入 - テンプレートの構文

PEAR マニュアル
前のページ		次のページ

プレースホルダ

プレースホルダのデフォルトの書式は
{[0-9A-Za-z_-]+}
です。つまり、プレースホルダの名前には、大文字と小文字そしてアンダースコアとハイフンが使用できるということです。名前は、波括弧の間にスペースなしで配置しなければなりません。

プレースホルダに実際の値を設定するには、 setVariable() および setGlobalVariable() メソッドを使用します。値を設定していないプレースホルダは、デフォルトでは出力時に削除されます。

ブロック

ブロックの書式は
 ... ブロックの内容 ... 
となります。ブロック名についての規則は、プレースホルダと同じです。プレースホルダとは対照的に、ブロックのマークアップ内ではスペースが必要です。

ブロックは入れ子にすることができます。しかし、パース時には注意しましょう。まず、もっとも内側にあるブロックから parse() し、それから順に外側に向かって処理を進めていく必要があります。

Sigma においては、テンプレート全体が "__global__" という仮想ブロックとして扱われます。大半のブロック関連の関数は、このブロック名をデフォルトで使用します。

文

テンプレートの内容を、他のテンプレートファイルから読み込むには  文を使用します。
... 何らかの内容 ...  ... さらに何らかの内容 ...
このようなテンプレートファイルが読み込まれると、  の部分が filename.html の内容で置き換えられます。

注意すべき点をまとめます。

 文が処理されるのは、テンプレートファイルをディスクから読み込んだ場合のみです。 setTemplate() メソッドでテンプレートを設定したり addBlock() と replaceBlock() でブロックとして動作させたりする場合は、テンプレート内にある  文の置換は行われません!
この機能は addBlockfile() を用いて実装されていますが、addBlockfile() とは異なり、新しいブロックをテンプレート内で作成することはできません。
 文は、変数の置換が行われる前に処理されます。つまり、  は期待通りに動作しません。もちろん、実際に {placeholder} という名前のファイルがあって、それを読み込みたいのなら別ですが (実際はそんなことはないでしょう)。

テンプレート関数

Sigma テンプレートには、単純な関数コールを含めることができます。つまり、テンプレートの作者が特別なプレースホルダを追加できるということです。
... 何らかの内容 ... func_h1("embedded in h1") ... さらに何らかの内容 ...
Sigma はこれらのプレースホルダを含むテンプレートをパースし、 setCallbackFunction() でコールバック関数を定義できるようにします。コールバックは、このような関数コールを含むブロックが parse() された場合に自動的にコールされます。

関数名の書式は、次のようになります。
func_[_a-zA-Z]+[A-Za-z_0-9]*
つまり、最初は必ず 'func_' で始まり、次に英字あるいはアンダースコアが続き、その後は英数字あるいはアンダースコアとなります。テンプレート関数の引数には、変数のプレースホルダを含めることができます。
func_translate('Hello, {username}')
しかし、ブロックや他の関数コールを含めることはできません。

テンプレート関数の引数のクォート

注意この節の情報は、HTML_Template_Sigma バージョン 1.1.2 以降に適用されます。それ以前のバージョンを使っていてテンプレート関数の引数で問題が発生した場合は、アップグレードしてください。

関数の引数のクォートは必須ではありません。以下のような使用法も可能です
func_uppercase(クォートしていないテキスト)
しかし、次のような例を考えてみましょう。関数の引数は括弧で囲まれており、カンマで区切られています。つまり、関数の引数内で閉じ括弧 ')' やカンマ ',' が用いられるのなら、それをクォートしなければなりません。

次に考慮する必要があるのは、HTML_Template_Sigma が対象としているのが HTML の生成であるということです。つまり、引数内のクォートされた文字列は、多くの場合にタグの属性となります。これらの文字列内ではカンマや括弧はパースされません。そのため、以下の例もテンプレート関数として有効なものになります。
func_foo(<a href="javascript:foo(bar, baz)">Do foo</a>)
しかし、引数内のシングルクォートあるいはダブルクォートの数がマッチしていない場合や引数がクォートで始まっている場合は、それをクォートする必要があります。

最後に、引数が空の文字列である場合や、前後に空白を含む引数を使用する場合にも引数をクォートしなければなりません (クォートしなければ、引数の前後の空白は削除されます)。

引数のクォートには、シングルクォートあるいはダブルクォートのどちらでも使用できます。引数の中に同じ型のクォートが含まれている場合は、バックスラッシュ '\' を使用してそれをエスケープしなければなりません。バックスラッシュ記号自身もまたエスケープする必要があります。
func_foo('O\'really') func_foo('AC\\DC')
これは、O'really および AC\DC を関連するコールバックに渡します。

例 47-1テンプレート関数の引数として有効あるいは無効なもの

有効な引数:
func_foo(Some unquoted text)
func_foo("Some quoted text")
func_foo(<a href="javascript:foo(bar, baz)">Do foo</a>)
func_foo('O\'really')
func_foo('AC\\DC')

無効な引数:
func_foo(Hello, {username}) カンマを含んでおり、ふたつの引数とみなされます
func_foo(O'really) マッチするシングルクォートがありません
func_foo('O'really') マッチするシングルクォートがありません
func_foo(, 'whatever') 空の引数はクォートしなければいけません

テンプレート関数の省略形

リリース 1.1.0 以降では、
func_callback({var})
と書くかわりに
{var:callback}
とすることができます。自動的に登録されるテンプレート関数には次の三種類があります。

'h' は htmlspecialchars() と同じです。
'e' は htmlentities() と同じです (リリース 1.2.0 以降で使用可能)。
'u' は urlencode() と同じです。
'r' は rawurlencode() と同じです (リリース 1.2.0 以降で使用可能)。
'j' は Sigma のメソッドで、文字列をエスケープして Javascript の文字列定数として使用できるようにします。

したがって、プレースホルダ {var:h} をテンプレートに追加すると、var の中の安全でない文字が HTML エンティティに置き換えられます。

リリース 1.2.0 以降、'h' コールバックおよび 'e' コールバック用のパラメータ charset を setOption() で指定できるようになりました。

テンプレートのコメント

リリース 1.2.0 以降、コメントをテンプレートファイルに追加できるようになりました。
 Some text here 
このコメントは出力からは削除されます。この点が通常の HTML のコメントとは異なります。

使用例

その他の使用例 パッケージのアーカイブにいくつかの使用例が含まれており、その機能の大半については網羅されています。それらのサンプルを見ながらドキュメントを読んでいくといいでしょう。

例 47-2テンプレートファイル table.html

<html>
<body>
<table cellpadding="2" cellspacing="0" border="1">
<!-- INCLUDE table_header.html -->
<!-- BEGIN table_row -->
    <tr>
        <td bgcolor="func_bgcolor('#CCCCCC', '#F0F0F0')">{first_name}</td>
        <td bgcolor="func_bgcolor('#CCCCCC', '#F0F0F0')">{last_name}</td>
    </tr>
<!-- END table_row -->
</table>
</body>
</html>

例 47-3テンプレートファイル table_header.html

<!-- COMMENT -->
This text will not appear in output.
<!-- /COMMENT -->
    <tr>
        <th>First name</th>
        <th>Last name</th>
    </tr>

例 47-4スクリプト

<?php

require_once 'HTML/Template/Sigma.php';

function toggle($item1, $item2)
{
    static $i = 1;

    return $i++ % 2? $item1: $item2;
}

$data = array (
    array("Stig", "Bakken"),
    array("Martin", "Jansen"),
    array("Alexander", "Merz")
);

$tpl =& new HTML_Template_Sigma('.');

$tpl->loadTemplateFile('table.html');

$tpl->setCallbackFunction('bgcolor', 'toggle');

foreach ($data as $name) {
    // データの代入
    $tpl->setVariable(array(
        'first_name'  => $name[0],
        'last_name' => $name[1]
    ));
    // ブロックの処理
    $tpl->parse('table_row');
}

// 結果の出力
$tpl->show();
?>

例 47-5出力

<html>
<body>
<table cellpadding="2" cellspacing="0" border="1">
    <tr>
        <th>First name</th>
        <th>Last name</th>
    </tr>


    <tr>
        <td bgcolor="#CCCCCC">Stig</td>
        <td bgcolor="#CCCCCC">Bakken</td>
    </tr>

    <tr>
        <td bgcolor="#F0F0F0">Martin</td>
        <td bgcolor="#F0F0F0">Jansen</td>
    </tr>

    <tr>
        <td bgcolor="#CCCCCC">Alexander</td>
        <td bgcolor="#CCCCCC">Merz</td>
    </tr>

</table>
</body>
</html>

前のページ	ホーム	次のページ
HTML_Template_Sigma	上に戻る	導入 - キャッシュ