プレースホルダのデフォルトの書式は
{[0-9A-Za-z_-]+}
です。つまり、プレースホルダの名前には、 大文字と小文字そしてアンダースコアとハイフンが使用できるということです。 名前は、波括弧の間にスペースなしで配置しなければなりません。
プレースホルダに実際の値を設定するには、 setVariable() および setGlobalVariable() メソッドを使用します。値を設定していないプレースホルダは、 デフォルトでは出力時に削除されます。
ブロックの書式は
となります。ブロック名についての規則は、プレースホルダと同じです。 プレースホルダとは対照的に、ブロックのマークアップ内ではスペースが必要です。
ブロックは入れ子にすることができます。しかし、パース時には注意しましょう。 まず、もっとも内側にあるブロックから parse() し、それから順に外側に向かって処理を進めていく必要があります。
Sigma においては、テンプレート全体が
"__global__"
という仮想ブロックとして扱われます。
大半のブロック関連の関数は、このブロック名をデフォルトで使用します。
テンプレートの内容を、他のテンプレートファイルから読み込むには
<!-- INCLUDE filename -->
文を使用します。
このようなテンプレートファイルが読み込まれると、
<!-- INCLUDE filename.html -->
の部分が filename.html
の内容で置き換えられます。
注意すべき点をまとめます。
<!-- INCLUDE -->
文が処理されるのは、
テンプレートファイルをディスクから読み込んだ場合のみです。
setTemplate()
メソッドでテンプレートを設定したり
addBlock() と
replaceBlock()
でブロックとして動作させたりする場合は、テンプレート内にある
<!-- INCLUDE -->
文の置換は行われません!
この機能は addBlockfile() を用いて実装されていますが、addBlockfile() とは異なり、新しいブロックをテンプレート内で作成することはできません。
<!-- INCLUDE -->
文は、変数の置換が行われる前に処理されます。つまり、
<!-- INCLUDE {placeholder} -->
は期待通りに動作しません。もちろん、実際に
{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 以降に適用されます。 それ以前のバージョンを使っていてテンプレート関数の引数で問題が発生した場合は、 アップグレードしてください。
関数の引数のクォートは必須ではありません。 以下のような使用法も可能です
しかし、次のような例を考えてみましょう。
関数の引数は括弧で囲まれており、カンマで区切られています。
つまり、関数の引数内で閉じ括弧
')'
やカンマ ','
が用いられるのなら、それをクォートしなければなりません。
次に考慮する必要があるのは、HTML_Template_Sigma が対象としているのが HTML の生成であるということです。 つまり、引数内のクォートされた文字列は、多くの場合にタグの属性となります。 これらの文字列内ではカンマや括弧はパースされません。 そのため、以下の例もテンプレート関数として有効なものになります。
しかし、引数内のシングルクォートあるいはダブルクォートの数がマッチしていない場合や 引数がクォートで始まっている場合は、それをクォートする必要があります。
最後に、引数が空の文字列である場合や、前後に空白を含む引数を使用する場合にも 引数をクォートしなければなりません (クォートしなければ、 引数の前後の空白は削除されます)。
引数のクォートには、シングルクォートあるいはダブルクォートのどちらでも使用できます。
引数の中に同じ型のクォートが含まれている場合は、バックスラッシュ
'\'
を使用してそれをエスケープしなければなりません。
バックスラッシュ記号自身もまたエスケープする必要があります。
これは、O'really
および AC\DC
を関連するコールバックに渡します。
テンプレート関数の引数として有効あるいは無効なもの
リリース 1.1.0 以降では、
func_callback({var})
と書くかわりに
{var:callback}
とすることができます。自動的に登録されるテンプレート関数には次の三種類があります。
したがって、プレースホルダ {var:h}
をテンプレートに追加すると、var の中の安全でない文字が
HTML エンティティに置き換えられます。
リリース 1.2.0 以降、'h' コールバックおよび 'e' コールバック用のパラメータ charset を setOption() で指定できるようになりました。
リリース 1.2.0 以降、コメントをテンプレートファイルに追加できるようになりました。
このコメントは出力からは削除されます。この点が通常の HTML のコメントとは異なります。
その他の使用例パッケージのアーカイブにいくつかの使用例が含まれており、 その機能の大半については網羅されています。 それらのサンプルを見ながらドキュメントを読んでいくといいでしょう。
テンプレートファイル table.html
テンプレートファイル table_header.html
スクリプト
<?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();
?>
出力