NAME

TL::Template - テンプレート

SYNOPSIS

  my $t = $TL->newTemplate
    ->setTemplate(qq{
	<html>
	  <title><&TITLE></title>
	  
	  <!begin:LOOP>
	    <&LINE><br>
	  <!end:LOOP>
	</html>
      });

  $t->expandAny(TITLE => 'Title');
  
  $t->node('LOOP')->add(LINE => 'line 1');
  $t->node('LOOP')->add(LINE => 'line 2');
  
  my $str = $t->toStr;
  
  # $str:
  # <html>
  #   <title>Title</title>
  #
  #
  #     line 1<br>
  #
  #     line 2<br>
  #
  # </html>

DESCRIPTION

コードとデザインを分離するためのテンプレートを扱うクラスです。

HTMLやメールの原稿をテンプレートとしてプログラム外部に用意し、コードとデザインを分離するようにします。

テンプレート書式

ブロックタグ

<!begin:????> .... <!end:????>

beginとendで囲まれた部分をノードとします。 ???? 部分は、同じ階層のノードでユニークでなければなりません。また、begin/end が交差したり、対応が取れていないことが無いように注意しなければなりません。

ノードとして指定されたブロックに対しては、node メソッドを使用してアクセスすることが出来ます。また、Template::Node クラスの add メソッドを呼ぶことで、ノードを繰り返して展開することが可能です。

展開タグ

<&????>

expand/add メソッドで、文字列を展開する場所を指定します。

Includeタグ

<!include:????>

タグのある場所に、指定されたファイルを読み込み、展開します。ファイルは、最後に loadTemplate したファイル名のディレクトリからの相対パスとして扱われます。 loadTemplate が呼ばれていない場合は、カレントディレクトリからの相対パスとして扱われます。

Includeタグはネストして使用可能ですが、自分自身を読み込むと永久ループすることになるので使用には注意が必要です。

コピータグ

<!copy:????>

????は既存のノード名を指します。 <!begin:????> .... <!end:????> で囲まれた部分のコピーを別の場所に展開します。 <!copy:????> タグは、<!begin:????> .... <!end:????> と同じ階層に存在し、かつコピー元のブロックより後ろに位置しなければなりません。

ただし、"flush" を使用しない場合は、コピー元のブロックより手前にあっても問題ありません。

METHODS

$TL->newTemplate

$t = $TL->newTemplate
$t = $TL->newTemplate($filepath)
$t = $TL->newTemplate($filepath, $icode)
$t = $TL->newTemplate($filepath, $icode, $prefer_encode)

TL::Template オブジェクトを作成。引数があれば、その引数で loadTemplate が実行される。

loadTemplate

$t->loadTemplate($filepath)
$t->loadTemplate($filepath, $icode)
$t->loadTemplate($filepath, $icode, $prefer_encode)

指定されたファイルをテンプレートとして読み込む。

$icode が省略された場合は 'auto' 文字コード自動判別となる。指定できる文字コードは、UTF-8，Shift_JIS，EUC-JP，ISO-2022-JP。

$prefer_encode を真にすると Encode が利用可能な場合は Encode で変換する。

setTemplate

$t->setTemplate($str)

指定された文字列をテンプレートとしてセットする。

node

$child = $t->node($nodename)

指定されたノード名のノードオブジェクトを返す。存在しないノード名が要求されたらエラー。

通常のTL::Templateオブジェクトとノードオブジェクトの違いは次の通り。

loadTemplateメソッド利用不可能
addメソッド利用可能

exists

$t->exists($nodename)

指定された名前を持つノードが存在するなら1を、しないならundefを返す。

setAttr

$t->setAttr(\%hash)
$t->setAttr(%hash)

expand/addメソッドで渡すデータの展開方法を指定する。指定がないものは plain 指定とみなす。

plain または指定無し: $TL->escapeTag を適用後、出力する
br: $TL->escapeTag を適用後、改行の前に <br> もしくは <br /> を挿入し、出力する。
raw: そのまま出力する
js: $TL->escapeJs を適用後、出力する

expand

$t->expand(\%hash)
$t->expand(%hash)

指定されたハッシュのデータを元に、展開タグを展開する。

渡されたハッシュのキーの中に、展開タグが存在しないものがあってもエラーにはならない。一回のexpandの呼び出しで未展開のタグが残った場合はエラーとなる。

expandAny

$t->expandAny(\%hash)
$t->expandAny(%hash)

expandと同様だが、テンプレートに未展開のタグがあってもエラーとしない。但し、toStrを行うまでには全てのタグを展開する必要性がある。

add

$t->node('foo')->add
$t->node('foo')->add(\%hash)
$t->node('foo')->add(%hash)

このメソッドはノードオブジェクトでのみ利用可能。

子ノードを親ノードに挿入する。このメソッドが呼ばれた後は、子ノードは展開前の状態に戻る。

引数が指定された場合は親ノードへの挿入前に expand される。

getForm

$form = $t->getForm($name)

HTMLテンプレート中のフォームを解析し、中にセットされているデータを TL::Form オブジェクトの形式で取り出す。

引数はフォームの name="..." で指定される名前。省略された場合は、name属性の存在しないform要素が取り出される。

setForm

$t->setForm($form)
$t->setForm($form, $name)

渡された TL::Form オブジェクトを、HTMLテンプレート中のフォームに展開する。

第2引数はフォームの name="..." で指定される名前。省略された場合は、name属性の存在しないform要素が対象となる。

テンプレートに存在し、フォームオブジェクトに存在しないキーがあったり、その逆の状態のキーが存在しても、エラー等は発生しない。

テンプレートに存在して、フォームオブジェクトに存在しないキーの関しては、テンプレートの元のデータが保存される。

extForm

$t->extForm
$t->extForm($name)

HTMLテンプレート中のフォームが外部アプリケーションに対するものであることを指定する。

第1引数はフォームの name="..." で指定される名前。省略された場合は、name属性の存在しないform要素が対象となる。

通常のフォームはTLフレームワークに対するものとして、いくつかの操作が行われるが、 extForm を行った場合はそれらの操作を行わない。

addHiddenForm

$t->addHiddenForm($form)
$t->addHiddenForm($form, $name)

渡された TL::Form オブジェクトを、HTMLテンプレート中のフォームに <input type="hidden"> 要素として追加する。

第2引数はフォームの name="..." で指定される名前。省略された場合は、name属性の存在しないform要素が対象となる。

渡されたフォームデータの全てのキーがhiddenとして追加される。既存の値に上書きはされず、単純に追加される。

addSessionCheck

$t->addSessionCheck($sessiongroup)
$t->addSessionCheck($sessiongroup, $name)
$t->addSessionCheck($sessiongroup, $name, $issecure)

指定したセッショングループのセッションIDを利用したキーをフォームに埋め込む。埋め込むフォームはPOSTメソッドでなければエラーとなる。また、事前にセッションIDを発行（SessionクラスのsetValue）してなければエラーとなる。 $CGI->haveSessionCheck とペアで使用する。

指定したセッショングループのIniで設定するcsrfkeyを必要とする。未設定の場合エラーとなる。 csrfkeyとセッションIDを利用してキーを作成する為、csrfkeyはサイト毎に違う値を用い、外部に漏れないようにする事。

第2引数はフォームの name="..." で指定される名前。省略もしくはundefが指定された場合は、name属性の存在しないform要素が対象となる。

使用中のセッションの mode が 'double' の場合は、第3引数に 0 または 1 を指定すると、http側、https側を指定できる。省略した場合は、そのときの通信が http/https のどちらであるかによって選択される。

getHtml

$html = $t->getHtml

特定のノードの現在の内容を返す。置換済みのタグは置換されており、未置換のタグは未置換のまま残っている。

setHtml

$t->setHtml($html)

特定のノードの現在の内容を変更する。"getHtml" と逆の働きをする。

flush

$t->flush

ノードの場合、そのノードの終端までを出力する。 Templateの場合、全体を出力する。

テンプレートの最初から順にflushしていかないと、テンプレートの一部分が重複出力されるので注意が必要。

toStr

$str = $t->toStr

テンプレート(展開結果)を文字列として返す。

isRoot

$is_root = $t->isRoot

ノードの場合は undef を返し、Template の場合は 1 を返す。

isXHTML

$is_xhtml = $t->isXHTML

テンプレートが XHTML のように見える場合は 1 を、そうでない場合は undef を返す。厳密なチェックは行わない。

Ini パラメータ

グループ名は "Template" でなければならない。

例:

[Template]
basepath = /home/www/template/

basepath

basepath = /home/www/template/

相対パス指定時に基準となるパス。省略可能。

デフォルトは "." 。すなわちカレントディレクトリ。

rootpath

rootpath = /home/www/

特定のディレクトリ階層よりも下位にあるファイルのみ、アクセスを許可する場合に指定する。省略可能。

デフォルトは "/"。すなわち全ファイルをテンプレートとして使用許可。

flush サンプル

ソースコード

$TL->setContentFilter('TL::Filter::Binary');

my $t = $TL->newTemplate->setTemplate(
qq{This is a header.

<!begin:AAA>
  node AAA begins...

  <!begin:BBB>
    node BBB begins...

      <!begin:CCC>
      value of node CCC: <&val>
      <!end:CCC>

    node BBB ends...
  <!end:BBB>
<!end:AAA>

This is a footer.
});

print "\n#--- node('CCC')->add; (twice)\n";
$t->node('AAA')->node('BBB')->node('CCC')->add(
    val => 100,
   );
$t->node('AAA')->node('BBB')->node('CCC')->add(
    val => 200,
   );

print "\n#--- node('CCC')->flush;\n";
$t->node('AAA')->node('BBB')->node('CCC')->flush;

print "\n#--- node('BBB')->add;\n";
$t->node('AAA')->node('BBB')->add;

print "\n#--- node('CCC')->add;\n";
$t->node('AAA')->node('BBB')->node('CCC')->add(
    val => 200,
   );

print "\n#--- node('CCC')->flush;\n";
$t->node('AAA')->node('BBB')->node('CCC')->flush;

print "\n#--- node('BBB')->add;\n";
$t->node('AAA')->node('BBB')->add;

print "\n#--- node('AAA')->add;\n";
$t->node('AAA')->add;

print "\n#--- root->flush;\n";
$t->flush;

実行結果

#--- node('CCC')->add; (twice)

#--- node('CCC')->flush;
Content-Type: application/octet-stream

This is a header.


  node AAA begins...

  
    node BBB begins...

      
      value of node CCC: 100
      
      value of node CCC: 200
      
#--- node('BBB')->add;

#--- node('CCC')->add;

#--- node('CCC')->flush;


    node BBB ends...
  
    node BBB begins...

      
      value of node CCC: 200
      
#--- node('BBB')->add;

#--- node('AAA')->add;

#--- root->flush;


    node BBB ends...
  


This is a footer.

AUTHOR INFORMATION

This framework is free software; you can redistribute it and/or modify it under the same terms as Perl itself

このフレームワークはフリーソフトウェアです。あなたは Perl と同じライセンスの元で再配布及び変更を行うことが出来ます。

Address bug reports and comments to: tl@tripletail.jp

HP : http://tripletail.jp/

To install TL, copy and paste the appropriate command in to your terminal.

cpanm

cpanm TL

CPAN shell

perl -MCPAN -e shell
install TL

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)