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" を使用しない場合は、コピー元のブロックより手前にあっても問題ありません。

利用上の注意

テンプレートクラスには、単純に展開処理を行う系統のメソッドと、 HTMLの内容を解釈して処理を行う系統のメソッドがあります。

展開タグやブロックを扱う expand/add メソッドはどのようなテキストデータに対しても処理を行うことができますので、これらのメソッドを呼び出すときに正しいHTML形式ではなくても動作します。

たとえば、以下のようなHTMLに対し、expand/addメソッドは正常に利用できます。

 <select name="type">
   <!begin:item>
     <option value="<&ID>" <&SELECTED>><&NAME></option>
   <!end:item>
 </select>

expand/addメソッドを使って、上記のHTMLを正常な形に加工した後であれば、 HTMLの内容を解釈して処理を行う系統のメソッド（setFormやaddHiddenFormなど）を利用できます。

たとえば、以下のようなHTMLに加工後に、setFormやaddHiddenFormを呼ぶことは問題がありません。

 <select name="type">
     <option value="1" SELECTED>いちご</option>
     <option value="2" >もも</option>
     <option value="3" >なし</option>
 </select>

しかし、expand/addメソッドによる加工を行う前のHTMLに対して、 setFormやaddHiddenFormなどを利用すると、正しいHTML形式ではないため、内容の解釈が正しく行えず、意図しない結果となることがあります。

METHODS

$TL->newTemplate

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

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

loadTemplate

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

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

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

デフォルトは文字コード自動判別となるが、テンプレートファイルに日本語がごく少量しか含まれない場合は、正しく判定できないことがある。

自動判別はUTF-8よりShift_JISを優先するので、テンプレートファイルは Shift_JISコードで作成することを推奨する。

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要素が取り出される。

対象となるノードの HTML タグの内部に未置換のタグがあった場合はエラーとなる。

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要素が対象となる。

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

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

対象となるノードの HTML タグの内部に未置換のタグがあった場合はエラーとなる。

extForm

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

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

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

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

対象となるノードの HTML タグの内部に未置換のタグがあった場合はエラーとなる。

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として追加される。既存の値に上書きはされず、単純に追加される。

対象となるノードの HTML タグの内部に未置換のタグがあった場合はエラーとなる。

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 のどちらであるかによって選択される。

対象となるノードの HTML タグの内部に未置換のタグがあった場合はエラーとなる。

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/

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

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

allow_unexpanded_tags

  allow_unexpanded_tags = true

非推奨オプション。tureを指定した場合、 getForm, setForm, extForm, addHiddenForm, addSessionCheckを実行する場合に、テンプレートに未置換の <&タグ> が、 <foo <&tag>> のように HTML タグの内部に存在していても、エラーにならないようになる。

このオプションを有効にした場合、<foo <&tag>> のようなタグがテンプレート中に存在していた場合、タグが正常に展開されず、破壊される恐れがある為、使用する際は注意して下さい。

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)

NAME

SYNOPSIS

DESCRIPTION

テンプレート書式

利用上の注意

METHODS

Ini パラメータ

flush サンプル

ソースコード

実行結果

SEE ALSO

AUTHOR INFORMATION

Module Install Instructions