Tripletail::Template - テンプレート

# 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.

# SEE ALSO

Tripletail

# AUTHOR INFORMATION

Copyright 2006 YMIRLINK Inc. All Rights Reserved.

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/

Tripletail::Template - テンプレート

# INDEX

- $TL->newTemplate
- AUTHOR INFORMATION
- DESCRIPTION
- Includeタグ
- Ini パラメータ
- METHODS
- NAME
- SEE ALSO
- SYNOPSIS
- add
- addHiddenForm
- addSessionCheck
- addメソッド利用可能
- basepath
- br
- exists
- expand
- expandAny
- extForm
- flush
- flush サンプル
- getForm
- getHtml
- isRoot
- isXHTML
- js
- loadTemplate
- loadTemplateメソッド利用不可能
- node
- plain または指定無し
- raw
- rootpath
- setAttr
- setForm
- setHtml
- setTemplate
- toStr
- コピータグ
- ソースコード
- テンプレート書式
- ブロックタグ
- 実行結果
- 展開タグ

Tripletail::Template - テンプレート