HTML::Template メソッドリファレンス

HTML::Templateの記事に手を入れていたら、長くなったので分割。こっちはメソッド関係。

(2013/07/21追記)newに指定できるencode系オプションについて追記。

new()

新しいテンプレートオブジェクトを作る。

# ファイル名でも
$tpl = HTML::Template->new(filename => 'template.html');

# テンプレートを格納した変数へのリファレンス
$template_text = "(テンプレート)";
$tpl = HTML::Template->new(scalarref => \$template_text);

# テンプレートを格納した配列へのリファレンス
open FH, '<', 'template.html';
@template = <FH>;
close FH;
$tpl = HTML::Template->new(arrayref => \@template);

# ファイルハンドルでも。
open $fh, '<', 'template.html';
$tpl = HTML::Template->new(filehandle => $fh);

それぞれ、以下のような別名も

$tpl = HTML::Template->new_file('template.html');
$tpl = HTML::Template->new_scalar_ref(\$template_text);
$tpl = HTML::Template->new_array_ref(\@template);
$tpl = HTML::Template->new_filehandle($fh);

各ソースタイプ共通で、これもOK

$tpl = HTML::Template->new(
    type => 'filename',
    source => 'template.html',
);

オプションは、かなりいろいろあります。よく使うものを紹介。

associate

他のオブジェクトから、パラメータ値を継承する。 CGI.pmのqueryオブジェクトを継承すると便利。

my $query = CGI->new();

# （入力内容のチェックとかをして...）

# 出力
my $template = HTML::Template->new(
    filename => "filename.tpl",
    associate => $query,
);

# フォーム等から受け取った各変数について、
# $template->param( '変数名', $query->param('変数名') );
# を実行済みであるかのように動く。
$template->output;

die_on_bad_param

0を指定すると、テンプレートにない変数名でもparamを呼び出せる。デフォルトは1（呼び出せない）。

strict

0を指定すると、TMPL_*タグのように見えるがタグで無いものを、単に無視する。デフォルトは1（エラーになる）。

utf8

テンプレートをファイル名で渡す時、このオプションに1を指定すると、テンプレートファイルをutf8として読み込んでくれる。
プログラムでuse utf8;している時に使おう。

（当たり前ですが）スカラーやオープン済みのファイルハンドルを渡す場合は、自分でencodingの面倒を見なければならない。

open_mode

プログラムでuse utf8;したいのに、テンプレートファイルはutf8以外の文字コードで書かれているという時に。

my $template = HTML::Template->new(
	filename  => 'templatefile.html',
	open_mode => '<:encoding(euc)',
);

こちらも、テンプレートをファイル名渡しする時用。

case_sensitive

trueを指定すると、テンプレートの変数名の大文字・小文字を区別する。デフォルトはfalse（区別しない）。

loop_context_vars

trueを指定すると、4つのループ・コンテキスト変数「__first__」「__last__」「__inner__」「__odd__」と、行カウンター「__counter__」を使えるようになる。デフォルトはfalse（使えない）。

<TMPL_LOOP NAME="FOO">

    この部分は、普通のループなので、毎回出力される。
    ループ回数を「<TMPL_VAR NAME="__counter__">」で出力できる。

    <TMPL_IF NAME="__first__">
        この部分は、ループの最初の回だけ出力される。
    </TMPL_IF>

    <TMPL_IF NAME="__odd__">
        この部分は、ループの奇数回だけ出力される。
    </TMPL_IF>

    <TMPL_UNLESS NAME="__odd__">
        この部分は、ループの偶数回（奇数回のUNLESS）だけ出力される。
    </TMPL_IF>

    <TMPL_IF NAME="__inner__">
        この部分は、ループの最初と最後以外、毎回出力される。
    </TMPL_IF>

    <TMPL_IF NAME="__last__">
        この部分は、ループの最後の回だけ出力される。
    <TMPL_IF>

</TMPL_LOOP>

ループが1回だけの場合、firstとlastは出力され、innerはスキップされる。

max_includes

テンプレートの差込が行える深さを指定。指定数を超えて差し込もうとするとエラーになる。 0を指定すると、深さチェックを行わない。デフォルトは10。

no_includes

1を指定すると、テンプレートの差込を行わない（TMPL_INCLUDEを無効に）。デフォルトは0（差込を行う）。

global_vars

1を指定すると、ループの中でも、ループ外で指定した変数を使えるようにする。デフォルトは0(使えない)。

[ ページ先頭へ ]

output()

テンプレートの最終結果を返します。

# そのまま出力してもいいし
print $tpl->output();

# 結果をさらに何か加工するなら
my $result = $tpl->output();

[ ページ先頭へ ]

param()

テンプレートに差し込む値を設定します。

個人的には、もっぱらnew時のassociateで値を入れているので、使用頻度低めです。

# TMPL_VARで出力するデータ
$template->param('変数名' => '値');
$template->param('変数名' => 値を返すサブルーチンへのリファレンス );

# TMPL_LOOPで出力するデータは、配列のリファレンスとして
$template->param('ループパラメータ名' =>
    [
        { 'ループ内変数名' => '値', ... },
        { 'ループ内変数名' => '値', ... },
    ]
);

# 複数の値をまとめて指定
$tamplate->param(
    '変数名1' => '値1',
    '変数名2' => '値2',
    'ループパラメータ名1' =>
    [
        { 'ループ1内変数名' => '値', ... },
        { 'ループ1内変数名' => '値', ... },
    ],
    'ループパラメータ名2' =>
    [
        { 'ループ2内変数名' => '値', ... },
        { 'ループ2内変数名' => '値', ... },
    ]
);

# 変数=>値を格納したハッシュを指定
$template->param(\%values);

現在設定済みの値などを取得することもできます。こっちはほぼ使ったことない感じ...。

# テンプレートの変数名リストを取得
my @parametar_names = $template->param();

# 設定された値を返す
my $value = $template->param('変数名');

[ ページ先頭へ ]

clear_params()

テンプレートのすべての変数をundefに設定します。

これも、あんまり使ったことないです...。

[ ページ先頭へ ]

query()

テンプレート構造の情報を取得。

# テンプレートにパラメータがあるかどうか確認
if ( $template->query(name => '変数名') ) {
    # 変数あり
}

# パラメータタイプを確認
if ( $template->query(name => '変数名') eq "VAR" ) {
    # 普通の変数
}
elsif ( $template->query(name => '変数名') eq "LOOP" ) {
    # ループ
}

TMPL_IF, TMPL_UNLESSは、TMPL_LOOPで使われている名前なら「LOOP」を、そうでなければ「VAR」を返す。

リストコンテキストでは、LOOPの内側のパラメータリストを返す。ループがネストしている場合も、再帰的にすべてのパラメータを参照できる。

名前はすべて小文字で、タイプは大文字で返される。

[ ページ先頭へ ]

参照

perldoc.jp HTML::Templateドキュメント和訳

cpan HTML::Template

最終更新日：2013/07/21

[ ページ先頭へ ]