HtmlTemplateクラス

■概要
PerlのHTML::Templateのような機能をJavaで実現したクラスです。
独自のタグにより置換、分岐、ループを行うのでデザインとプログラムの分離を
比較的簡単に実現できます。

テンプレートはPerlのHTML::Templateと互換性があります。
(互換性は100%ではありません。一部制限があります)

Perlで作成された機能とServletで作成された機能が混在する環境で
HTMLの管理を容易にしデザイナーの負担を軽減することができます。

既にテンプレートの仕組みは数多く存在しますがシンプルで解りやすい
HTML::Templateとテンプレートの互換性を持つこのクラスを活用して頂けたら幸いです。


■動作環境
Java 2 SDK, Standard Edition


■使用上の注意と免責事項等
著作権
・本ソフトウエアはフリーソフトウエアです、無償でご利用いただけます。
・本ソフトウエアの著作権は株式会社ネクステージにあります。

配布条件
・非営利目的の再配布は自由です。
 営利目的での再配布については、ご相談ください。
・再配布はオリジナルのファイルのままでお願いします。

使用上の注意、免責事項
・本ソフトウエアを使用した事によるいかなる損害も補償いたしません。
 使用者の責任においてご使用ください。

改良、不具合の報告
・問い合わせフォームにて報告を受け付けております。
 可能な限り改善に努めますが、不具合の修正は保証致しません。


■ダウンロード
HtmlTemplate (ver1.1)


■テンプレートの記述
まずは簡単なテンプレートの例を見てください。

テンプレートの例(sample.html)
---------------------------------------------------------------
検索結果<BR>
<tmpl_if name="HIT">
 <tmpl_var name="HIT_COUNT">件<BR>
 <tmpl_loop name="HIT">
 <tmpl_var name="SITE"> <tmpl_var name="URL"><BR>
</tmpl_loop>
<tmpl_else>
 見つかりませんでした。<BR>
</tmpl_if>
----------------------------------------------------------------
これは検索サイトの検索結果を出力するテンプレートの例です。
検索結果がある場合には該当データの件数とサイトのリストを
繰り返し出力し、検索結果が無い場合には「見つかりませんでした」を
出力します。

(出力例1)
--------------------------------------------------------------- 検索結果  3件  g00gle http://www.g00gle.co.jp/  yah00 http://www.yah00.co.jp/  g00 http://www.g00.ne.jp/ (出力例2) ---------------------------------------------------------------- 検索結果  見つかりませんでした。


■プログラムでの使用例
上記のテンプレートで検索結果有りの出力をする場合の例です。
    //テンプレートの作成
    HtmlTemplate tmpl = new Htmltemplate(new File("sample.html"));

    //結果配列
    //(実際にはDB等から取得したデータになると思います。サンプルなので・・・)
    String data[][]={
        {"g00gle","http://www.g00gle.co.jp/"},
        {"yah00","http://www.yah00.co.jp/"},
        {"g00","http://www.g00.ne.jp/"}
    };

    //検索結果の件数をセット
    tmpl.param("HIT_COUNT",Integer.toString(data.length));

    //繰り返し出力のリスト作成
    List hit = new ArrayList();
    for(int i=0;i<data.length;i++){
        Map record = new HashMap();
        record.put("SITE",data[i][0]);  //サイト名セット
        record.put("URL",data[i][1]);   //URLセット
        hit.add(record);                //リストに追加
    }
    tmpl.param("HIT",hit);//リストをテンプレートにセット

    //HTMLの生成
    String htmlSource = tmpl.output();


■テンプレートタグの説明
<TMPL_VAR>
 これは一番メインとなるタグで指定した値に置き換えます。

 <TMPL_VAR NAME="HIT_COUNT">

 値が設定されていないテンプレートは""に置き換えられます。
 オプションで出力をエスケープ(エンコード)することが可能です。
 もし「Sam"ple」のような値を下記のようにFORMのVALUE等に
 セットすると期待する結果が得られないです(^^;
 <INPUT NAME=param TYPE=TEXT VALUE="<TMPL_VAR NAME="HIT_COUNT">">
 このような場合は ESCAPE=HTML を指定します。
 <INPUT NAME=param TYPE=TEXT VALUE="<TMPL_VAR ESCAPE=HTML NAME="HIT_COUNT">">
 URLエンコードを行うESCAPE=URL オプションもあります。

 全てのテンプレートタグで共通ですが
 テンプレート名を指定する NAME="" のダブルクオーテーションは省略できます。
 PERLでは""の代わりに''も使用できますが現時点ではサポートしていません。

 int hit_count = 3;
 tmpl.param("HIT_COUNT",new String(hit_count));
 tmpl.param("HIT_COUNT",new Integer(hit_count));
 上記はどちらも正しい指定で HIT_COUNT は「3」に置換されます。

<TMPL_LOOP>
 タグで挟まれた部分を繰り返し出力します。
 <TMPL_LOOP NAME="HIT">ここが繰り返されます</TMPL_LOOP>

 <TMPL_LOOP>の内側に置かれた<TMPL_VAR>に値をセットする場合は
 Mapにテンプレート名をキーにして値をセットしてListにMapを追加していき
 テンプレートにはListをセットします。
 ループはListのサイズ分繰り返されMapにセットされた値を置き換えます。
    //繰り返し出力のリスト作成
    List hit = new ArrayList();
    for(int i=0;i<data.length;i++){
        Map record = new HashMap();
        record.put("SITE",data[i][0]);
        record.put("URL",data[i][1]);
        hit.add(record);
    }
    tmpl.param("HIT",hit);//リストをテンプレートにセット
 <TMPL_LOOP>の中に<TMPL_LOOP>を含めることも可能です。
 LOOPの中ではMapにセットされた値しか有効ではありません。
 → LOOPの外の<TMPL_VAR NAME=AAA>と
   LOOPの中の<TMPL_VAR NAME=AAA>は別の扱いとなるので
   同じ内容に置き換えたい場合はそれぞれに値を
   セットする必要があります。

<TMPL_INCLUDE>
 タグの場所を別ファイルの内容に置き換えます。

 <tmpl_include name="header.html">

 この処理はコンストラクタ又はsetTemplateメソッドを
 呼び出した時点で行われるため別ファイルに含まれる
 テンプレートタグも有効です。
 ※但し<TMPL_INCLUDE>の中の<TMPL_INCLUDE>は
  無限に再帰するINCLUDEを避けるため深度は10階層に制限しています。
 指定されたファイルが存在しない場合は""に置き換えられます。

<TMPL_IF>
 テンプレート名がparamメソッドで設定されている場合に
 タグで挟まれた部分を出力します。

 <TMPL_IF NAME="HIT">HITが未定義だとここは出力されません</TMPL_IF>

 <TMPL_IF>の中に<TMPL_IF><TMPL_UNLESS><TMPL_LOOP>を含めることが可能です。
 ※Perlでは<TMPL_LOOP>でセットしたテンプレート名を<TMPL_IF>で使用した場合
  リストのサイズが1以上の場合に条件が真になりますがこのクラスでは
  リストが空でもテンプレート名がセットされていれば「真」になります。
 ※TMPL_IF(後述のTMPL_UNLESSも含む)の多用は
  デザインとロジックの分離という目的に反する危険も含んでいます。

<TMPL_UNLESS>
 <TMPL_IF>の逆の動作をします。
 テンプレート名がparamメソッドで設定されていない場合に
 タグで挟まれた部分を出力します。

 <TMPL_UNLESS NAME="HIT">HITが未定義の場合ここが出力されます</TMPL_UNLESS>

 <TMPL_UNLESS>の中に<TMPL_IF><TMPL_UNLESS><TMPL_LOOP>を含めることが可能です。

<TMPL_ELSE>
 <TMPL_IF>、<TMPL_UNLESS>の中に入れることで
 条件が「偽」の場合の出力を指定できます。
  <TMPL_IF NAME="HIT">
      HITは定義されています
  <TMPL_ELSE>
      HITは未定義です
  </TMPL_IF>
 ※<TMPL_ELSE>には閉じタグ</TMPL_ELSE>は存在しません。


■メソッド
 クラスのメソッドについてはJavaDocのドキュメントを参照してください。


■拡張機能
 PerlのHTML::Templateには無い独自の機能

 ・タグ<TMPL_VAR>をタグのまま出力することができます。
  値に「#NOP#」をセットしたテンプレートは値への置き換えは
  行わず元のテンプレートタグをそのまま出力します。

  これは全テンプレートタグの処理を一度に行わずに
  一部のタグだけ置換して保存し残りを別のタイミングで置換したりというように
  複数回に分けて行いたい場合に使用します。