HTML::Template の使い方

構文

テンプレート変数の構文は、標準では <TMPL_VAR NAME=varname> です。 そして、スクリプトで HTML::Template オブジェクトの param() メソッドによって、 置換することができます。

$template->param( varname  => 'こんにちは' );

これで <TMPL_VAR NAME=varname> の部分が「こんにちは」に置き換わります。

テンプレート変数の構文の大文字・小文字は区別されません。 <TMPL_VAR NAME=varname> も <tmpl_var name=varname> も同じに扱われます。 また、varname の部分もデフォルトでは大文字・小文字の区別はありません。 <TMPL_VAR NAME=varname> も <TMPL_VAR NAME=VARNAME> も期待通りに置換されます。

ただし、HTML::Template オブジェクト生成時にパラメータ case_sensitive に 1 を指定すると vername の部分は大文字・小文字が区別されます。

my $template = HTML::Template->new(
    case_sensitive => 1,
    ...
);

テンプレート変数の構文としては、HTML 構文と同様に、属性値をダブルクォーテーションで囲むこともできます。 つまり、<TMPL_VAR NAME="varname"> という記法も許されます。

HTML エスケープ

HTML::Template はテンプレート内の変数を置換する際に、HTML エスケープする機能を用意しています。 次のテンプレートとスクリプトを考えてみましょう。

連絡先：<TMPL_VAR NAME="contact">

$template->param( contact  => '田中太郎 <taro.tanaka@example.jp>' );

置換文字列の中に < や > が含まれるため、HTML として出力すると期待通りにレンダリングされません。 置換文字列を HTML エスケープしないといけません。この場合、テンプレートでは次のように記述します。

連絡先：<TMPL_VAR NAME="contact" ESCAPE="html">

これによって、次のように出力されます。

連絡先：田中太郎 <taro.tanaka@example.jp>

デフォルトエスケープ

HTML エスケープするために、すべての変数の変換でテンプレートに <TMPL_VAR NAME="contact" ESCAPE="html"> と記述するのは面倒です。 そこで、デフォルトのエスケープを設定することで、ESCAPE="html" なしに HTML エスケープすることができるようになります。

HTML::Template オブジェクト生成時に default_escape => 'html' を指定します。

my $template = HTML::Template->new(
    ...
    default_escape => 'html',
);

Vanguard 互換モード

Vanguard 互換モードを有効にすると、<TMPL_VAR NAME="varname"> というテンプレート記述を %varname% という記述に簡素化できます。 Vanguard 互換モードを有効にするには、HTML::Template オブジェクト生成時にパラメータ vanguard_compatibility_mode に 1 をセットします。

my $template = HTML::Template->new(
    ...,
    vanguard_compatibility_mode => 1,
);

一見便利そうに見える Vanguard 互換モードですが、2 点注意が必要です。

一つ目は、Vanguard 互換モードを有効にすると、自動的にパラメータ die_on_bad_params に 0 がセットされます。たとえ明示的に die_on_bad_params に 1 をセットしても、それは無効になります。 これにより、もしテンプレートに記述されていない変数を Perl スクリプト側でセットしてもエラーにはなりません。 つまり、Perl スクリプト側で変数名を間違えても、気付きにくくなりますので注意が必要です。

二つ目は、Vanguard 互換モードを有効にすると、HTML エスケープをテンプレート側で指示できなくなります。 デフォルトモードであれば <TMPL_VAR NAME="contact" ESCAPE="html"> と記述することで HTML エスケープをテンプレート側で指示できました。 Vanguard 互換モードを使うなら、Perl スクリプト側で事前に HTML エスケープするか、または、 HTML::Template オブジェクト生成時に default_escape => 'html' を指定するのが良いでしょう。

構文

HTML::Template のテンプレート構文で繰り返し処理には TMPL_LOOP を使います。

<ul>
    <TMPL_LOOP NAME="mlist">
        <li><TMPL_VAR NAME="name" ESCAPE="html"> (<TMPL_VAR NAME="age">)</li>
    </TMPL_LOOP>
</ul>

Perl スクリプトでは、arrayref を与えます。

my $mlist = [ { name => '太郎', age => 24 }, { name => '次郎', age => 21 } ];
$template->param( mlist => $mlist );

arrayref (ここでは変数 $mlist) の各要素は hashref でなければいけない点に注意してください。 このサンプルコードは次のような結果を出力します。

<ul>

        <li>太郎 (24)</li>

        <li>次郎 (21)</li>

</ul>

変数のスコープ

HTML::Template では、テンプレート変数にもスコープという概念があります。 次の HTML テンプレート構文を見てみましょう。

<TMPL_LOOP NAME="product_list">
    <a href="%product_path%/%product_code%.html">%product_name%</a>
</TMPL_LOOP>

ここでテンプレート変数 %product_path% に注目してください。 この変数の値は、この繰り返しですべて同じ値だとします。 恐らく、Perl スクリプトを書くなら、このように書きたくなるのではないでしょうか。

my $product_path = '/products';
my $product_list = [
    { product_name => '商品A', product_code => 'A' },
    { product_name => '商品B', product_code => 'B' }
];
$template->param( product_path => $product_path );
$template->param( product_list => $product_list );

しかし、結果は期待通りにはなりません。%product_path% が置換されずに結果が出力されてしまいます。

    <a href="/A.html">商品A</a>

    <a href="/B.html">商品B</a>

HTML::Template のデフォルトの挙動では、TMPL_LOOP にセットした arrayref の外で定義された変数の値は、 TMPL_LOOP の中では使えません。 この点は、Perl の変数のスコープと異なりますので、違和感を感じますね。

もし TMPL_LOOP にセットした arrayref の外で定義された変数の値を TMPL_LOOP の中でも利用できるようにするには、 HTML::Template オブジェクト生成時でパラメータ global_vars に 1 を指定します。

my $template = HTML::Template->new(
    ...,
    global_vars => 1
);

これにより、結果は次のようになります。

    <a href="/products/A.html">商品A</a>

    <a href="/products/B.html">商品B</a>

ループコンテキスト変数

HTML::Template オブジェクトを生成する際に、パラメータ loop_context_vars に 1 を指定すると、TMPL_LOOP の中でループコンテキスト変数を利用することができます。

my $template = HTML::Template->new(
    ...,
    loop_context_vars => 1
);

ループコンテキスト変数は繰り返し処理に特化したプリセットの変数で、Perl スクリプトで定義する必要はありません。 HTML::Template で使えるループコンテキスト変数は以下の通りです。

次のテンプレートをご覧ください。

<TMPL_LOOP NAME="product_list">
    %__counter__%. %product_name%<TMPL_IF NAME="__last__"> (新製品)</TMPL_IF>
</TMPL_LOOP>

このテンプレートはループの各項目の冒頭に 1 から順に番号を振ります。 そして、最後だけ (新商品) を付け加えます。 これを実現する Perl スクリプトは次の通りです。

my $template = HTML::Template->new(
    ...,
    loop_context_vars => 1
);

my $product_list = [
    { product_name => '商品A' },
    { product_name => '商品B' },
    { product_name => '商品C' }
];
$template->param( product_list => $product_list );

このサンプルコードを実行すると、次のような結果が出力されます。

    1. 商品A

    2. 商品B

    3. 商品C (新製品)