Template - HTML/XML template library

Jamritas.TemplateはHTML/XMLテンプレートライブラリです。テンプレートとモデルデータから、新たなDOMオブジェクトを生成します。

var tmpl = new Jamritas.Template(elem);
var data = {title: "Jamritas",
            body: "Jamritas is a Ajax application library."};
var result = tmpl.expand(data);

Jamritas.Template

スタティックプロパティ

スタティックプロパティによってテンプレートのデフォルト設定を管理します。

identifier: モデルデータの埋め込み位置を指定するための識別子属性名。デフォルト値は'tid'。
document: テンプレート展開時にDOMオブジェクトを作成するためのDOM Documentインターフェイスを実装しているオブジェクト。デフォルト値はグローバル変数document。
placeholder: 要素名の配列。placeholderとして指定されたテンプレート内の非ルート要素は、もし属性としてidentifierのみを持つならば、展開後にその要素のタグが削除されます。デフォルト値は['div', 'span']。
ignoreWhitespace: テンプレート内の空白文字のみから成るテキストノードを無視するかどうかを示す真偽値。デフォルト値はtrue。
ignoreComment: テンプレート内のコメントノードを無視するかどうかを示す真偽値。デフォルト値はtrue。
recursiveExpantionElement: 再帰展開のためのテンプレート識別子の対応関係を表すオブジェクト(連想配列)。デフォルト値は{}(空オブジェクト)。
viewEmptyArrayAsFalse: モデルデータとして空配列が表れたとき、それをfalseとみなすかを示す真偽値。デフォルト値はfalse。
callGetterMethod: モデルデータのゲッターメソッドを呼ぶかどうかを示す真偽値。デフォルト値はfalse。

これらのプロパティはいずれもコンストラクタの第二引数によって個別に変更することもできます。

コンストラクタ

Jamritas.Template(elem [, config])

テンプレートを作成します。elemにはテンプレートの元となるXML DOM ElementまたはHTML DOM Elementを与えます。

省略可能な第二引数によりオブジェクトごとに設定を変更できます。

var tmpl = new Jamritas.Template(elem, {identifier: 'id', ignoreWhitespace: false});

メソッド

expand(data): テンプレートの展開を行い新たなDOMオブジェクトを作成して返します。 dataにはテンプレートへ埋め込まれるモデルデータを与えます。

展開規則

基本ルール

展開は、テンプレート中の識別子となる属性(identifier)をもつ要素の内容を、モデルデータ内の対応する値に置き換えることにより行われます。識別子となる属性は展開時に取り除かれます。

テンプレート:

<div>
  <h1 tid="title">title</h1>
  <p tid="body">body</p>
</div>

モデルデータ:

{title: "Jamritas",
 body: "Jamritas is a Ajax application library"}

展開後:

<div>
  <h1>Jamritas</h1>
  <p>Jamritas is a Ajax application library</p>
</div>

モデルデータには任意のオブジェクトを与えることができます。展開はオブジェクトのプロパティだけでなくプロトタイプに属するメソッドも対象になります。メソッドは引数無しで呼び出され、その戻り値が使用されます。

テンプレート:

<p tid="time">It's <em tid="getHours">hour</em> :
                   <em tid="getMinutes">minute/em> :
                   <em tid="getSeconds">second</em> now.</p>

モデルデータ:

{time: new Date}

展開後:

<p>It's <em>11</em> :
        <em>26</em> :
        <em>38</em> now.</p>

もしcallGetterMethodがtrueであれば、テンプレート識別子に対応するゲッターメソッドを呼び出し、その戻り値をモデルデータとして使用します。

テンプレート:

<p tid="time">It's <em tid="hours">hour</em> :
                   <em tid="minutes">minute/em> :
                   <em tid="seconds">second</em> now.</p>

モデルデータ:

{time: new Date}

展開後:

<p>It's <em>11</em> :
        <em>26</em> :
        <em>38</em> now.</p>

この例ではテンプレート識別子hours、minutes、seconds に対してDateオブジェクトのメソッドgetHours()、 getMinutes()、getSeconds()が呼ばれます。

ゲッターメソッド名は、テンプレート識別子の最初の一文字を大文字にし、先頭にgetをつけたものとなります。

繰り返し

モデルデータが配列の場合、展開は子要素に対して繰り返されます。

テンプレート:

<dl tid="deflist">
   <dt tid="term">term</dt>
   <dd tid="definition">definition</dd>
</dl>

モデルデータ:

{deflist: [
    {term: "WWW", definition: "World Wide Web"},
    {term: "HTML", definition: "HyperText Markup Language"},
    {term: "CSS", definition: "Cascading Style Sheet"}]}

展開後:

<dl>
  <dt>WWW</dt>
  <dd>World Wide Web</dd>
  <dt>HTML</dt>
  <dd>HyperText Markup Language</dd>
  <dt>CSS</dt>
  <dd>Cascading Style Sheet</dd>
</dl>

選択

モデルデータがtrueであればその要素はそのまま保持されます。 false、null、もしくは対応するモデルデータがない場合にはその要素自体が削除されます。

テンプレート:

<p>
  <em tid="c">C, </em>
  <em tid="cpp">C++, </em>
  <em tid="perl">Perl, </em>
  <em tid="java">Java, </em>
  <em tid="python">Python, </em>
  <em tid="ruby">Ruby, </em>
  and JavaScript are script language.</p>

モデルデータ:

{c: false, perl: true, java: null, python: true, ruby: true}

展開後:

<p>
  <em>Perl, </em>
  <em>Python, </em>
  <em>Ruby, </em>
  and JavaScript are script language.</p>

要素の埋め込み

モデルデータがDOMオブジェクトである場合には、その要素自身がモデルデータで置き換えられます。

要素のカスタマイズ

モデルデータが関数である場合には、対応する要素を第一引数として関数が呼び出されます。

属性値の展開

テンプレート内に属性値が $ で始まる属性が存在した場合、その属性値はモデルデータで置き換えられます。対応するモデルデータが存在しない場合には、その属性は削除されます。

テンプレート:

<a title="$attr">Jamritas</a>

モデルデータ:

{attr: "Ajax application library"}

展開後:

<a title="Ajax application library">Jamritas</a>

モデルデータがObjectのインスタンスである場合には、属性名、属性値のマップと見なされ、属性として追加、上書きされます。

テンプレート:

<a accesskey="a" title="$attr">Jamritas</a>

モデルデータ:

{attr: {href: "http://jamritas.sourceforge.net/", accesskey: "b"}}

展開後:

<a href="http://jamritas.sourceforge.net/" accesskey="b">Jamritas</a>

展開後に属性値がnullとなった場合には、その属性は削除されます。

テンプレート:

<a accesskey="a" title="$attr">Jamritas</a>

モデルデータ:

{attr: {accesskey: null}}

展開後:

<a>Jamritas</a>

属性名がonで始まる属性の属性値としてモデルデータに関数が与えられた場合には、その関数はイベントハンドラと見なされJamritas.Event.add()を用いてノードに追加されます。

サニタイジングの無効化

モデルデータとしてHTML文字列を与えても、HTMLとして解釈されずそのまま画面に表示されます。HTMLとして解釈させたい場合には、 Jamritas.Template.markup()を使用します。

テンプレート:

<p tid="html">html string</p>

モデルデータ:

{html: Jamritas.Template.markup('<strong>Jamritas</strong>')}

展開後:

<p><strong>Jamritas</strong></p>

再帰展開

再帰展開とは、再帰的な構造を持つモデルデータをテンプレートへと埋め込むための機能です。再帰展開を使うにはrecursiveExpantionElementプロパティを使用します。recursiveExpantionElementにObjectのインスタンスを与え、キーと値にテンプレート識別子を指定してexpand() を呼び出します。

展開中に、ソーステンプレート内にキーにマッチするテンプレート識別子をもつ要素が表れた場合、その要素の内容はその要素の先祖要素で値にマッチするテンプレート識別子を持つ要素の内容と同一であるように処理されます。

function BinTree(label, left, right) {
    this.label = label;
    this.left = left;
    this.right = right;
}

var xml = Jamritas.DOM.text2dom('<div tid="bintree"><p tid="label"/><div tid="left"/><div tid="right"/></div>');

var tmpl = new Jamritas.Template(xml, 
                                 {placeholder: [],
                                  recursiveExpantionElement: {'left': 'bintree', 'right': 'bintree'}});

var d = new BinTree('d');
var e = new BinTree('e');
var c = new BinTree('c', d, e);
var b = new BinTree('b');
var a = new BinTree('a', b, c);

var result = tmpl.expand(a);

この例では、recursiveExpantionElement: {'left': 'bintree', 'right': 'bintree'}と指定しています。、展開途中にtid="left"であるdiv要素が表れると、その要素の内容がtid="bintree"をもつdiv要素の内容と同じであるとして処理されます。tid="right"の要素に対しても同様に処理されます。結果、作成されるDOMツリーは以下のものになります。

<div>
  <p>a</p>
  <div>
    <p>b</p>
  </div>
  <div>
    <p>c</p>
    <div>
      <p>d</p>
    </div>
    <div>
      <p>e</p>
    </div>
  </div>
</div>