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

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

導入 - テンプレートの構文 -- テンプレートの作成および編集

プレースホルダ

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

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

ブロック

ブロックの書式は 
<!-- BEGIN [0-9A-Za-z_-]+ -->
... ブロックの内容 ...
<!-- END [0-9A-Za-z_-]+ -->
となります。ブロック名についての規則は、プレースホルダと同じです。 プレースホルダとは対照的に、ブロックのマークアップ内ではスペースが必要です。

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

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

<!-- INCLUDE --> 文

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

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

テンプレート関数

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 を関連するコールバックに渡します。

例 43-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}
とすることができます。自動的に登録されるテンプレート関数には次の三種類があります。

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

使用例

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

例 43-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>

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

<tr>
        <th>First name</th>
        <th>Last name</th>
    </tr>

例 43-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();
?>

例 43-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上に戻る導入 - キャッシュ