[pod] [xml]

NAME

HTML::Template - CGI スクリプトから HTML テンプレートを使うための Perl モジュール

SYNOPSIS

最初にテンプレートを作ります - これは <TMPL_VAR> のようにとても簡単な、 2・3 の特殊なタグが入った普通の HTML ファイルです。

例えば、 test.tmpl:

  <html>
  <head><title>Test Template</title>
  <body>
  My Home Directory is <TMPL_VAR NAME=HOME>
  <p>
  My Path is set to <TMPL_VAR NAME=PATH>
  </body>
  </html>

そして小さな CGI プログラムを作ります:

  #!/usr/bin/perl -w
  use HTML::Template;
  # open the html template
  my $template = HTML::Template->new(filename => 'test.tmpl');
  # fill in some parameters
  $template->param(HOME => $ENV{HOME});
  $template->param(PATH => $ENV{PATH});
  # send the obligatory Content-Type and print the template output
  print "Content-Type: text/html\n\n", $template->output;

これですべてがうまくいっていれば、ブラウザでそのCGIにいくと、 以下のようなものが表示されます:

  My Home Directory is /home/some/directory
  My Path is set to /bin;/usr/bin

DESCRIPTION

このモジュールは HTML テンプレートを使うことを簡単に、自然にしようとします。 これは標準の HTML をいくつかの新しいHTML風のタグ - <TMPL_VAR>, <TMPL_LOOP>, <TMPL_INCLUDE>, <TMPL_IF>, <TMPL_ELSE>, <TMPL_UNLESS> で拡張します。 HTML とこれらの新しいタグで書かれたファイルはテンプレートと呼ばれます。 これは通常スクリプトとは別に保存されます - もしかしたら他の誰かによって作成されることさえあるかもしれません! このモジュールを使って、変数のための値を埋めたり、テンプレートで 宣言されたループや分岐をおこないます。 これにより Perl スクリプトで作成されるデータからデザイン - HTML - を 分けることが出来ます。

このモジュールは GPL の元でライセンスされます。 詳細についてはライセンス(LICENSE)・セクションをご覧下さい。

TUTORIAL

(チュートリアル)

もしあなたが HTML::Template を使うのが初めてなら、 HTML::Template ウェブサイトにある紹介文書から始めることを お勧めします。

   http://html-template.sourceforge.net

MOTIVATION

(動機)

HTML テンプレートを行っているパッケージがたくさんあることは事実です。 HTML::Embperl のように HTML に自由に Perl を混ぜることを許すものもあります。 さらに一方では自家製の変数置換による解決法もあります。 このモジュールが、それら 2 つの間に居場所を見つけられることを望んでいます。

このモジュールのフルの HTML::Embperl のような解決法に対する有利な点の 1 つは、 重要な分割 - デザインとプログラミング - を強制することです。 プログラマには簡単な変数とループを HTML で使うことに限定し、 テンプレートはデザイナやその他の perl を知らない人たちからも アクセスできるようになっています。 HTML のような文法を使っているので、 他のものと比べてそのフォーマットを非常に理解しやくなっています。 似ていることから、将来的に既存の HTML エディタ／アナライザが HTML::Template をサポートするように拡張しやすくなっています。

自家製のタグ置換法に対する有利な点はループをサポートしていることです。 私は仕事の中で、HTML でテーブルを作成するためによく呼び出しています。 HTML そのものはループを表すことが出来ないので、 簡単に割り切りすぎた HTML を使うと CGI の中に大量の HTML が入ってしまいます。 HTML にループ・ステートメントを導入するとこの状況をとても簡単にします。 デザイナは 1 つの行をレイアウトし、 プログラマは必要に合わせて何回も埋めることが出来ます - それらはすべてパラメータ名について合意しておく必要があります。

なにより、私がこのモジュールについて最もよいことだと思っていることは、 それは 1 つのことしかしませんし、それを速く、注意深く行います。 それは Perl や HTML を置き換えようとはしません。 相互への影響をちょっとだけ増やすだけです。そしてそれはかなり速いのです。

THE TAGS

(タグ)

TMPL_VAR

  <TMPL_VAR NAME="PARAMETER_NAME">

<TMPL_VAR> タグはとても簡単です。 テンプレートの中の各 <TMPL_VAR> タグのために、 $template->param(PARAMETER_NAME => "VALUE") を呼びます。 テンプレートが出力されるとき <TMPL_VAR> は指定された VALUE の文字列で 置きかえられます。パラメータに値を設定しなければ、出力の際に飛ばされます。

オプションで、出力から戻される前に値が HTML-エスケープしたいことを示すために、 タグの中で"ESCAPE=HTML"オプションを使うことが出来ます (昔の ESCAPE=1 という書き方もまだサポートされています)。 つまり ", <, >, & といった文字は、&quot;, &lt;, &gt;, &amp; に それぞれ変換されます。 それらの文字がトラブルを起こしかねない場所で TMPL_VAR を使いたいときに便利です。

   <input name=param type=text value="<TMPL_VAR NAME="PARAM">">

もし'sam"my'のような値でparam()を呼び出すと、 ダブルクオートについての HTML の考え方のせいで厄介なことになります。 対して以下のように ESCAPE=HTML を使うと：

   <input name=param type=text value="<TMPL_VAR ESCAPE=HTML NAME="PARAM">">

param に渡された値に関わらず、欲しいものを手に入れることが出来ます。 ESCAPE="HTML", ESCAPE='HTML', ESCAPE='1' とも書けます。 HTML を 0 で置換すると、エスケープをオフとし、それはデフォルトです。

"ESCAPE=URL" オプションもあります。 これは URL に適した VAR に使うことが出来ます。 それは' 'を + に、'/' を '%2F' に置きかえるといった、 URL エスケープをおこないます。

DEFAULT 属性を使って変数のデフォルト値を設定することもできます。 例えば、"who" 変数が設定されていないときは "the devil gave me a taco" と 表示させるためには、以下のようにします。

  The <TMPL_VAR NAME=WHO DEFAULT=devil> gave me a taco.

TMPL_LOOP

  <TMPL_LOOP NAME="LOOP_NAME"> ... </TMPL_LOOP>

<TMPL_LOOP> タグは <TMPL_VAR> よりちょっとだけ複雑です。 <TMPL_LOOP> タグはテキストのセクションを区切り、 名前をつけることを可能とします。 この名前つきループの内側に <TMPL_VAR> を置きます。 そしてこのループでパラメータに代入する(ハッシュ・リファレンスの param() にリスト(配列リファレンス)を渡します。 ループはリストの間、繰り返され、 渡す度にテキスト・ブロックからの出力を作成します。 設定されないパラメータは飛ばされます。以下に例を示します:

 In the template:
   <TMPL_LOOP NAME=EMPLOYEE_INFO>
      Name: <TMPL_VAR NAME=NAME> <br>
      Job:  <TMPL_VAR NAME=JOB>  <p>
   </TMPL_LOOP>
 In the script:
   $template->param(EMPLOYEE_INFO => [ 
                                       { name => 'Sam', job => 'programmer' },
                                       { name => 'Steve', job => 'soda jerk' },
                                     ]
                   );
   print $template->output();
  
 The output in a browser:
   Name: Sam
   Job: programmer
   Name: Steve
   Job: soda jerk

上記にあるように <TMPL_LOOP> は変数代入のリストを取り、 出力を作成するループ本体を繰り返します。

しばしば、<TMPL_LOOP> の内容をプログラム的に作成したいことでしょう。 以下にそれをどのように行うかの例を示します (他にもいろんな方法が可能です!):

   # a couple of arrays of data to put in a loop:
   my @words = qw(I Am Cool);
   my @numbers = qw(1 2 3);
   my @loop_data = ();  # initialize an array to hold your loop
   while (@words and @numbers) {
     my %row_data;  # get a fresh hash for the row data
     # fill in this row
     $row_data{WORD} = shift @words;
     $row_data{NUMBER} = shift @numbers;
 
     # the crucial step - push a reference to this row into the loop!
     push(@loop_data, \%row_data);
   }
   # finally, assign the loop data to the loop param, again with a
   # reference:
   $template->param(THIS_LOOP => \@loop_data);

上記の例は以下のようなテンプレートで機能します:

   <TMPL_LOOP NAME="THIS_LOOP">
      Word: <TMPL_VAR NAME="WORD">     <br>
      Number: <TMPL_VAR NAME="NUMBER"> <p>
   </TMPL_LOOP>

それは以下のような出力を作成します:

   Word: I
   Number: 1
   Word: Am
   Number: 2
   Word: Cool
   Number: 3

<TMPL_LOOP> の中の <TMPL_LOOP> は問題なく、期待通りに機能します。 param() 呼び出しのための文法が悩ましているのであれば、 1 つのネストしたループでの param 呼び出しの例を以下に示します：

  $template->param(LOOP => [
                            { name => 'Bobby',
                              nicknames => [
                                            { name => 'the big bad wolf' }, 
                                            { name => 'He-Man' },
                                           ],
                            },
                           ],
                  );

基本的に、各 <TMPL_LOOP> は 1 つの配列リファレンスを取得します。 配列の内側にはハッシュ・リファレンスをいくつでも入れることが出来ます。 これらのハッシュにはループ・テンプレートに 1 つずつ渡す名前 => 値の組が 入っています。

<TMPL_LOOP> の内側では、<TMPL_LOOP> から利用できる変数だけが入ります。 外側のブロックの変数はテンプレート・ループの中では見えません。 コンピュータ・サイエンス的にいえば、 <TMPL_LOOP> は perl サブルーチンのように新しいスコープを導入したのです。 変数をグローバルにしたければ、 下記で説明する new() へ'global_vars'を使うことが出来ます。

TMPL_INCLUDE

  <TMPL_INCLUDE NAME="filename.tmpl">

このタグは現在のテンプレートのタグのある場所に直接テンプレートを入れます。 入れられるテンプレートの内容は、その内容がマスター・テンプレートに 物理的に入れられているのとまったく同じように使われます。

ファイルは絶対パス(例えばUnix では '/'から始まる)で指定することが出来ます。 もし絶対パスでなければ、囲まれたファイルへのパスが最初に試されます。 その後、もしあれば環境変数 HTML_TEMPLAGE_ROOT でのパスが試されます。 次に "path" オプションが試されます。まずはそのまま、 その後 HTML_TEMPLATE_ROOT が利用可能ならそれを前につけて試されます。 最後にファイル名が直接 open() に渡されます。 HTML_TEMPLATE_ROOT と new() への "path" オプションについての詳細は 下記をご覧下さい。

無限に再帰するインクルードを避けるため、 深さは 10 レベルに制限されています。 この制限は"max_includes"オプションで変えることが出来ます。 "max_includes"オプションの詳細については、下記をご覧下さい。

TMPL_IF

  <TMPL_IF NAME="PARAMETER_NAME"> ... </TMPL_IF>

<TMPL_IF> タグは与えられたパラメータ名の値に基づいて、 テンプレートのブロックを入れるか入れないかを可能にします。 与えられたパラメータの値が Perl での true - '1' のような - であれば、 ブロックは出力に入れられます。未定義であるか、 false の値 - '0' のような - であれば、飛ばされます。 パラメータは TMPL_VAR と同じ方法で指定されます。

例のテンプレート：

   <TMPL_IF NAME="BOOL">
     Some text that only gets displayed if BOOL is true!
   </TMPL_IF>

そこで $template->param(BOOL => 1) を呼び出すと、 上記のブロックが出力に入ります。

<TMPL_IF> </TMPL_IF> ブロックは正しい HTML::Template構造であれば - VAR, LOOP そして他の IF/ELSE ブロック - どこにでもいれることができます。 しかし <TMPL_IF> と <TMPL_LOOP> が交差するのは正しくないことに注意してください。

   Not going to work:
   <TMPL_IF BOOL>
      <TMPL_LOOP SOME_LOOP>
   </TMPL_IF>
      </TMPL_LOOP>

もし TMPL_LOOP の名前が TMPL_IF で使われていれば、 もし LOOP が 1 つでも行を持っていれば、IF ブロックは出力します。例えば：

  <TMPL_IF LOOP_ONE>
    This will output if the loop is not empty.
  </TMPL_IF>
  <TMPL_LOOP LOOP_ONE>
    ....
  </TMPL_LOOP>

警告: HTML::Template の大きな利点は Perl と HTML を分けることです。 もし TMPL_IF のあるところでたくさんのケースを導入し、 それが Perl の if() に対応しているのであれば、 2 つの同期を保持するためのメンテナンス上の問題をおこすでしょう。 Perl のコードでの if() に対応することを要求せずにそうできるときにのみ、 TMPL_IF を実際に利用するように提案します。

TMPL_ELSE

  <TMPL_IF NAME="PARAMETER_NAME"> ... <TMPL_ELSE> ... </TMPL_IF>

TMPL_ELSE を使うことにより TEMPL_IF ブロックの代りのブロックを 入れることが出来ます。 注意:ブロックを終わらせるのは、 まだ </TMPL_IF> であって </TMPL_ELSE> ではありません！ 

   Example:
   <TMPL_IF BOOL>
     Some text that is included only if BOOL is true
   <TMPL_ELSE>
     Some text that is included only if BOOL is false
   </TMPL_IF>

TMPL_UNLESS

  <TMPL_UNLESS NAME="PARAMETER_NAME"> ... </TMPL_UNLESS>

このタグは <TMPL_IF> の反対です。 CONTROL_PARAMETER が false に設定されているか未定義であると ブロックが出力されます。 <TMPL_ELSE> を <TMPL_IF> とまったく同じように <TMPL_UNLESS> と 一緒に使うことも出来ます。

  Example:
  <TMPL_UNLESS BOOL>
    Some text that is output only if BOOL is FALSE.
  <TMPL_ELSE>
    Some text that is output only if BOOL is TRUE.
  </TMPL_UNLESS>

TMPL_UNLESS で TMPL_LOOP の名前が使われていれば、 UNLESS ブロックはループに行がなければ出力されます。

  <TMPL_UNLESS LOOP_ONE>
    This will output if the loop is empty.
  </TMPL_UNLESS>
  
  <TMPL_LOOP LOOP_ONE>
    ....
  </TMPL_LOOP>

NOTES

(注意)

HTML::Template のタグが HTML のように見えます。 しかし、"ルール破り"が認められています。以下のように:

   <img src="<TMPL_VAR IMAGE_SRC>">

これは本当は適切な HTML ではなりません。 しかしこれは完璧に正しい使い方ですし、予定通りに機能します。

タグでの "NAME=" はオプションですが、 拡張性の点から私はそれを使う事を推奨します。 例えば - "<TMPL_LOOP LOOP_NAME>" は受け入れられます。

適切な HTML へに熱心で、テンプレートが HTML 文法に適切であるように 従わせたいのであれば、HTML コメントの形式のなかにテンプレートを 入力することが出来ます。 これは、HTML::Template 処理の前にテンプレートの HTML 文法が 正しいかどうかをチェックしたい HTML 作者や DTD-savvy 編集ツールを使っている人には便利でしょう。

  <!-- TMPL_VAR NAME=PARAM1 -->

劇的な帯域の節約を実現するために、 このドキュメントの全てで標準(コメントでない)タグが使われます。

METHODS

(メソッド)

new()

新しい Template オブジェクトを作るには new() を呼び出します：

  my $template = HTML::Template->new( filename => 'file.tmpl', 
                                      option => 'value' 
                                    );

テンプレート・テキストにどのようにアクセスするかを指定する、 少なくとも 1 つの名前 => 値の組を指定して new() を 呼び出さなければなりません。 "filename=>'file.tmpl'" を使って、 テンプレートとしてオープンされるファイル名を指定することができます。 代りに以下のようにすることもできます：

  my $t = HTML::Template->new( scalarref => $ref_to_template_text, 
                               option => 'value' 
                             );

と

  my $t = HTML::Template->new( arrayref => $ref_to_array_of_lines , 
                               option => 'value' 
                             );

これらはメモリ上の資源からテンプレートを初期化します。 ほとんどの場合、filename パラメータを使いたいでしょう。 もしテンプレート・ファイルからの読み込みの すべてのディスク・アクセスについて心配であれば、 mod_perl と以下に説明する cache オプションを使ってください。

テンプレートを既にオープンしているファイルハンドルから 読み込むこともできます。伝統的なグロブとファイルハンドルの 両方が使えます。

  my $t = HTML::Template->new( filehandle => *FH, option => 'value');

お好みであれば、4 つの new() 呼び出しメソッドは 以下のようにもアクセスされます:

  my $t = HTML::Template->new_file('file.tmpl', option => 'value');
  my $t = HTML::Template->new_scalar_ref($ref_to_template_text, 
                                        option => 'value');
  my $t = HTML::Template->new_array_ref($ref_to_array_of_lines, 
                                       option => 'value');
  my $t = HTML::Template->new_filehandle($fh, 
                                       option => 'value');

そして最後のオプションとして、以下のようにも呼び出すことが出来ます:

  my $t = HTML::Template->new(type => 'filename', 
                              source => 'file.tmpl');

これはソースタイプの 3 つ全てに機能します。

環境変数 HTML_TEMPLATE_ROOT が設定され、filename が / で始まらなければ、 パスは $HTML_TEMPLATE_ROOT からの相対パスでしょう。 例えば - 環境変数 HTML_TEMPLATE_ROOT が "/home/sam" に設定され、 HTML::Template->new() をファイル名を "sam.tmpl" に設定して呼び出すと、 HTML::Template はテンプレート・ファイルにアクセスするために "/home/sam/sam.tmpl" をオープンしようとします。 また new() への "path" オプションで検索パスに影響を与えることも出来ます - 詳細な情報については以下をご覧下さい。

Templarte オブジェクトの動きを new で変更することが出来ます。 以下のオプションが利用できます:

param()

param() はいくつかの方法で呼び出されます。

1) テンプレートでのパラメータのリストを返す:

   my @parameter_names = $self->param();

2) パラメータに設定された値を返す:

   my $value = $self->param('PARAM');

3) パラメータに値を設定する:

      # For simple TMPL_VARs:
      $self->param(PARAM => 'value');
      # with a subroutine reference that gets called to get the value
      # of the scalar.  The sub will recieve the template object as a
      # parameter.
      $self->param(PARAM => sub { return 'value' });   
      # And TMPL_LOOPs:
      $self->param(LOOP_PARAM => 
                   [ 
                    { PARAM => VALUE_FOR_FIRST_PASS, ... }, 
                    { PARAM => VALUE_FOR_SECOND_PASS, ... } 
                    ...
                   ]
                  );

4) 複数のパラメータを設定する:

     # For simple TMPL_VARs:
     $self->param(PARAM => 'value', 
                  PARAM2 => 'value'
                 );
      # And with some TMPL_LOOPs:
      $self->param(PARAM => 'value', 
                   PARAM2 => 'value',
                   LOOP_PARAM => 
                   [ 
                    { PARAM => VALUE_FOR_FIRST_PASS, ... }, 
                    { PARAM => VALUE_FOR_SECOND_PASS, ... } 
                    ...
                   ],
                   ANOTHER_LOOP_PARAM => 
                   [ 
                    { PARAM => VALUE_FOR_FIRST_PASS, ... }, 
                    { PARAM => VALUE_FOR_SECOND_PASS, ... } 
                    ...
                   ]
                  );

5) ハッシュ・リファレンスを使って複数のパラメータを設定:

      $self->param(
                   { 
                      PARAM => 'value', 
                      PARAM2 => 'value',
                      LOOP_PARAM => 
                      [ 
                        { PARAM => VALUE_FOR_FIRST_PASS, ... }, 
                        { PARAM => VALUE_FOR_SECOND_PASS, ... } 
                        ...
                      ],
                      ANOTHER_LOOP_PARAM => 
                      [ 
                        { PARAM => VALUE_FOR_FIRST_PASS, ... }, 
                        { PARAM => VALUE_FOR_SECOND_PASS, ... } 
                        ...
                      ]
                    }
                   );

clear_params()

すべてのパラメータをundefに設定します。 他では使えなくても、内部的には便利です!

output()

output() はテンプレートの最終結果を返します。 ほとんどの場合、以下のようにこれを出力したいでしょう:

   print $template->output();

output が呼ばれると、<TMPL_VAR NAME=name> のそれぞれは param() を通して "name" に代入された値で置き換えられます。 もし名前付きのパラメータの設定をはずされたら、 単に''で置きかえられます。 <TMPL_LOOPS> はパラメータセット毎に 1 度評価され、 それぞれの出力を蓄積します。

気にしているかもしれないので言っておきますが、 output() を呼ぶことは Template オブジェクトの状態を変更しないことを 保証されています。この属性はループの内部での実装にとってとても重要です。

オプションとして、テンプレートが生成されたときに自動的に出力する ファイルハンドルを指定することもできます。 これによりパフォーマンスが向上し、メモリ消費が減ります。例:

   $template->output(print_to => *STDOUT);

"print_to" オプションが使われた場合には、返り値は未定義値です。

query()

このメソッドはテンプレート構造についての情報を取得することを可能にします。 いくつかの方法で呼ぶことができます。 query の最も簡単な使い方は、name オプションを使って、 テンプレートにパラメータ名があるかをチェックすることです:

  if ($template->query(name => 'foo')) {
    # do something if a varaible of any type 
    # named FOO is in the template
  }

これと同じ使い方はパラメータのタイプを返します。 タイプはタグから頭の 'TMPL_' を引いたものと同じです。 例えば、TMPL_VAR パラメータは query() からは 'VAR' を返します。

  if ($template->query(name => 'foo') eq 'VAR') {
    # do something if FOO exists and is a TMPL_VAR
  }

TMPL_IF と TMPL_UNLESS に結び付けられている変数は TMPL_LOOP で使われていない限り、'VAR' で示されます。 TMPL_LOOP で使われていれば、'LOOP' を返します。

query() はループの内側(さらにループの内側のループの内側)の パラメータのリストを取得することも可能にします。例えば:

   <TMPL_LOOP NAME="EXAMPLE_LOOP">
     <TMPL_VAR NAME="BEE">
     <TMPL_VAR NAME="BOP">
     <TMPL_LOOP NAME="EXAMPLE_INNER_LOOP">
       <TMPL_VAR NAME="INNER_BEE">
       <TMPL_VAR NAME="INNER_BOP">
     </TMPL_LOOP>
   </TMPL_LOOP>

そしていくつかの query の呼び出し:

  # returns 'LOOP'
  $type = $template->query(name => 'EXAMPLE_LOOP');
    
  # returns ('bop', 'bee', 'example_inner_loop')
  @param_names = $template->query(loop => 'EXAMPLE_LOOP');
  # both return 'VAR'
  $type = $template->query(name => ['EXAMPLE_LOOP', 'BEE']);
  $type = $template->query(name => ['EXAMPLE_LOOP', 'BOP']);
  # and this one returns 'LOOP'
  $type = $template->query(name => ['EXAMPLE_LOOP', 
                                    'EXAMPLE_INNER_LOOP']);
  
  # and finally, this returns ('inner_bee', 'inner_bop')
  @inner_param_names = $template->query(loop => ['EXAMPLE_LOOP',
                                                 'EXAMPLE_INNER_LOOP']);
  # for non existent parameter names you get undef
  # this returns undef.
  $type = $template->query(name => 'DWEAZLE_ZAPPA');
  # calling loop on a non-loop parameter name will cause an error.
  # this dies:
  $type = $template->query(loop => 'DWEAZLE_ZAPPA');

上記のように、loop オプションはパラメータ名のリストを返し、 name も loop もループの内側のパラメータを参照するために 配列リファレンスを取ります。 loop でないパラメータで loop を使うとエラーになります。

返されるすべての名前は小文字で、タイプは大文字であることに注意してください。

param()、query()と同じように、引数を指定しないと、 テンプレートでのトップ・レベルのすべてのパラメータ名を返します。

FREQUENTLY ASKED QUESTIONS

よりよく理解されるために perldoc の FAQ セクションを始めました。 私に email を送る前に、どうかここをご覧下さい。

  1. Q: HTML::Template について議論したり、助けを得るための場所はありますか？

    HTML::Template について議論するためのメーリングリストが html-template-users@lists.sourceforge.net にあります。 参加するためには、以下のページを参照して下さい:

       http://lists.sourceforge.net/lists/listinfo/html-template-users

    新しいリリースが出たのを知りたいだけなら、アナウンス用の メーリングリストもあります:

       http://lists.sourceforge.net/lists/listinfo/html-template-announce

  2. Q; 検索可能なメーリングリストのアーカイブはありますか?

    はい、SourceForge メーリングリストのアーカイブが以下の場所にあります:

      http://www.geocrawler.com/lists/3/SourceForge/23294/0/

    古い vm.com 時代のメーリングリストのアーカイブは、 Sean P. Scanlon が設定したものが以下の場所にあります:

       http://bluedot.net/mail/archive/

  3. Q: <TMPL_XXX> に対応してほしいんです!どうすればいいんでしょう?

    たぶん。私はメーリング・リストで HTML::Template のためのアイデアについて 議論することを皆さんに勧めます。新しいタグが、HTML テンプレートを 使用するための高速で、軽量なシステムを提供するという HTML::Template の使命にどのようにフィットするのかを 説明する準備をしておいてください。

    注意: その機能をプログラムして、最新バージョンの HTML::Template への パッチの形で提供すれば、間違い無く潜在的な反対者を弱くさせるでしょう!

  4. Q: バグを見つけました。修正してもらえますか?

    場合によります。HTML::Templateの バージョン、テスト・スクリプトと テスト・テンプレートを送りましたか?そうであれば、たぶん間違い無いでしょう。

    もしあなたが本当に大胆であれば、HTML::Template はパブリックに利用可能な CVS サーバを持っています。詳細についてはパブリックな CVS サーバ・セクションを ご覧下さい。

  5. Q: メイン・テンプレートからの <TMPL_VAR> が <TMPL_LOOP> の内側で機能しません! なぜ?

    これは予定されている動きです。<TMPL_LOOP> は、Perl でのサブルーチン呼び出しが "my" 変数のために別のスコープを導入するのと同じように、 <TMPL_VAR> のために別のスコープを導入します。

    <TMPL_VAR> をグローバルにしたければ、new() を呼び出すときに 'global_vars' を設定することが出来ます。 new() の 'global_vars' オプションのドキュメントについては上記をご覧下さい。

  6. Q: なぜ /t/i ではなく /[Tt]/ を使うのですか?醜いです!

    A: 簡単です- 大文字小文字を無視したマッチのスイッチは効率的ではありません。 "Mastering Regular Expressions"（詳説　正規表現）O'Reilly Press によると、 /[Tt]/ は /t/i にくらべてより速く、よりスペースを有効に使います - 文字列の長さの倍程度。 //i は基本的に文字列に lc() をおこない、 一時的なコピーをメモリに保持します。

    これが変更されたら、そしてそれが 5.6 開発シリーズに入ったら、 私は喜んで //i を使います。信じてください、[Tt] がぞっとするほど 醜いことは私もわかっています。

  7. Q: cache モードと mod_perl を使ってテンプレートを予め ロードするにはどのようにすればできますか?

    A: startup.plに以下のようなものを追加します：

       use HTML::Template;
   use File::Find;
       print STDERR "Pre-loading HTML Templates...\n";
   find(
        sub {
          return unless /\.tmpl$/;
          HTML::Template->new(
                              filename => "$File::Find::dir/$_",
                              cache => 1,
                             );
        },
        '/path/to/templates',
        '/another/path/to/templates/'
      );

    あなたがあなたのテンプレートに使用している拡張子を指定するように "return unless" 行を変更する必要があることに注意してください。 ご存知でしょうが、私は '.tmpl' を使っています。 また、あなたのテンプレートファイルへのパスも設定する必要があるでしょう。

    1つの潜在的な問題: "/path/to/templates"は、HTML::Template->new() を 呼ぶときに使うのとまったく同じパスでなければいけません。 そうでなければ、cache は同じファイルであることがわからず、 新しいコピーをロードします。 スピードはあがらずに、代りに、2 倍メモリを使用します。 これが起こっているかどうかを調べるには、 アプリケーションのなかで cache_debug =>1 を設定し、 ログに "CACHE MISS" メッセージが無いかを調べます。

  8. A: TMPL_* NAMEにはどんな文字が許されますか?

    A: 数字、英字、 '.', '/', '+', '-', '_' です。

  9. Q: どうすればテンプレートの中からプログラムを実行できますか?

    A: 短く言えば: それはできません。 長く答えると、HTML::Templateの背後にある基本的な概念 - デザインとプログラムは分けるべき - に反するのでするべきではありません。

    しかし避けられないことに、人によってはまだそれをすることを欲します。 これがあなたのことなら、HTML::Template::Expr を 見るべきでしょう。 HTML::Template::Expr を使うと、run_program() 関数を簡単に書くことができるでしょう。 これで以下のようなおぞましいことができるようになります:

      <tmpl_var expr="run_program('foo.pl')">

    Just, please, don't tell me about it. I'm feeling guilty enough just for writing HTML::Template::Expr in the first place.

  10. Q: Can I get a copy of these docs in Japanese?

    A: Yes you can. See Kawai Takanori's translation at:

       http://member.nifty.ne.jp/hippo2000/perltips/html/template.htm

  11. Q: What's the best way to create a <select> form element using HTML::Template?

    A: There is much disagreement on this issue. My personal preference is to use CGI.pm's excellent popup_menu() and scrolling_list() functions to fill in a single <tmpl_var select_foo> variable.

    To some people this smacks of mixing HTML and code in a way that they hoped HTML::Template would help them avoid. To them I'd say that HTML is a violation of the principle of separating design from programming. There's no clear separation between the programmatic elements of the <form> tags and the layout of the <form> tags. You'll have to draw the line somewhere - clearly the designer can't be entirely in charge of form creation.

    It's a balancing act and you have to weigh the pros and cons on each side. It is certainly possible to produce a <select> element entirely inside the template. What you end up with is a rat's nest of loops and conditionals. Alternately you can give up a certain amount of flexibility in return for vastly simplifying your templates. I generally choose the latter.

    Another option is to investigate HTML::FillInForm which some have reported success using to solve this problem.

BUGS

私はバグについて何も気がついていません - もし見つけたら メーリング・リストに参加して、それを伝えてください。 HTML::Template メーリング・リストには以下のページから参加できます:

  http://lists.sourceforge.net/lists/listinfo/html-template-users

もちろんバグについて私に直接メールする(sam@tregar.com)こともできます。 しかし私は言われたバグレポートを転送する権利を保持しています。

バグ・レポートを送信するときには問題を証明する、モジュールの VERSION、 テスト・スクリプト、そしてテスト・テンプレートを間違い無く入れてください!

もしあなたが本当に大胆であれば、HTML::Template は パブリックに利用可能な CVS サーバを持っています。 詳細についてはパブリックな CVS サーバ・セクションをご覧下さい。

CREDITS

このモジュールは Vanguard Media での私の上司 Jesse Erlbaum (jesse@vm.com) の 頭脳の産物です。 このモジュールでの最大のオリジナルのアイデア - <TMPL_LOOP> - は 完全に彼のものです。

以下の方々からは修正、バグ・レポート、最適化そしてアイデアを 惜しみなくいただきました:

   Richard Chen
   Mike Blazer
   Adriano Nagelschmidt Rodrigues
   Andrej Mikus
   Ilya Obshadko
   Kevin Puetz
   Steve Reppucci
   Richard Dice
   Tom Hukins
   Eric Zylberstejn
   David Glasser
   Peter Marelas
   James William Carlson
   Frank D. Cringle
   Winfried Koenig
   Matthew Wickline
   Doug Steinwand
   Drew Taylor
   Tobias Brox
   Michael Lloyd
   Simran Gambhir
   Chris Houser <chouser@bluweb.com>
   Larry Moore
   Todd Larason
   Jody Biggs
   T.J. Mather
   Martin Schroth
   Dave Wolfe
   uchum
   Kawai Takanori
   Peter Guelich
   Chris Nokleberg
   Ralph Corderoy
   William Ward
   Ade Olonoh
   Mark Stosberg
   Lance Thomas
   Roland Giersig
   Jere Julian
   Peter Leonard
   Kenny Smith
   Sean P. Scanlon
   Martin Pfeffer
   David Ferrance
   Gyepi Sam  
   Darren Chamberlain

どうもありがとう!

WEBSITE

You can find information about HTML::Template and other related modules at:

   http://html-template.sourceforge.net

PUBLIC CVS SERVER

HTML::Template は SourceForge (www.sourceforge.net)によって提供される パブリックにアクセスすることができる CVS サーバを持っています。 それには http://sourceforge.net/cvs/?group_id=1075 にいくことにより アクセスできます。トライしてみてください!

AUTHOR

Sam Tregar, sam@tregar.com

LICENSE

  HTML::Template : A module for using HTML Templates with Perl
  Copyright (C) 2000-2002 Sam Tregar (sam@tregar.com)
  This module is free software; you can redistribute it and/or modify it
  under the terms of either:
  a) the GNU General Public License as published by the Free Software
  Foundation; either version 1, or (at your option) any later version,
  
  or
  b) the "Artistic License" which comes with this module.
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either
  the GNU General Public License or the Artistic License for more details.
  You should have received a copy of the Artistic License with this
  module, in the file ARTISTIC.  If not, I'll be glad to provide one.
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  USA