NAME

Tripletail::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)

Tripletail::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)

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

通常のTripletail::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テンプレート中のフォームを解析し、中にセットされているデータを Tripletail::Form オブジェクトの形式で取り出す。

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

setForm

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

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

Tripletail::Formオブジェクトの代わりにハッシュのリファレンスを渡すことも出来る。ハッシュのリファレンスを渡した場合は、$TL->newForm($hashref) した結果のフォームオブジェクトをセットする。

第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)
$t->addHiddenForm($hashref)
$t->addHiddenForm($hashref, $name)

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

Tripletail::Formオブジェクトの代わりにハッシュのリファレンスを渡すことも出来る。ハッシュのリファレンスを渡した場合は、$TL->newForm($hashref) した結果のフォームオブジェクトを追加する。

第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('Tripletail::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 Tripletail, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Tripletail

CPAN shell

perl -MCPAN -e shell
install Tripletail

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)