Temritaの使い方

0. はじめに

 require 'temrita'
 include Temrita

 t = Template.parse('<span id="hoge">Test</span>')
 t.expand( {:hoge => "Hoge"} )
=> <span>Hoge</span>

以降の説明では上記を以下のように記述します。

テンプレート :
<span id="hoge">Test</span>
モデルデータ :
{:hoge => "Hoge"}
出力 :
<span>Hoge</span>

1. 基本編

1.1 単純置換

展開データに文字列を指定した場合、要素の中身がその文字列に置き換えられます。

テンプレート :
<span id="hoge">この中身が置換えられます。</span>
モデルデータ :
{ :hoge => "置き換える文字列" }
出力 :
<span>置き換える文字列</span>

1.2 階層構造

展開データにHashを指定した場合、要素内の要素がそのHashをモデルデータとして展開されます。これによって、データの構造を表現できます。例えば以下の例だと、nameとageは、personの要素の中になければ展開されません。

テンプレート :
 <ul id="person">
  <li id="name">見本 太郎</li>
  <li id="age">18</li>
 </ul>
モデルデータ :
{ :person => { :name => "鈴木 一郎",
               :age  => 28 }}
出力 :
 <ul>
  <li>鈴木 一郎</li>
  <li>28</li>
 </ul>

1.3 繰返し

展開データに配列を指定した場合、配列の中身をそれぞれモデルデータとして、対象となる要素が繰り返し展開されます。

テンプレート :
<ul>
 <li id="list">データ</li>
</ul>
モデルデータ :
{ :list => ["海","山","川"] }
出力 :
<ul>
 <li>海</li><li>山</li><li>川</li>
</ul>

1.4 条件展開

id属性の頭に ? や ! をつけると、モデルデータに該当データが存在するかどうかを基準に、中身はそのままで展開します。なお、展開データが空の配列であった場合、該当データ無しとみなします。

テンプレート :
hogeが<span id="?hoge">ある。</span><span id="!hoge">ない。</span>
fooは<span id="?foo">ある。</span><span id="!foo">ない。</span>
モデルデータ :
{ :hoge => "値は無視される。", :foo => [] }
出力 :
hogeが<span>ある。</span>
fooは<span>ない。</span>

1.5 テキスト展開

テキスト中または属性値内に@{hoge}と書くと、モデルデータの:hogeの値に展開されます。

テンプレート :
<p title="@{hoge}">好きなところで@{hoge}できます。</p>
モデルデータ :
{ :hoge => "展開" }
出力 :
<p title="展開">好きなところで展開できます。</p>

1.6 テキスト展開のデフォルト値

@{hoge:デフォルト値}のように : で区切って、該当データが存在しなかった場合に使うデフォルト値を指定できます。

テンプレート :
<p>彼の名前は@{name:不明}で、性別は@{sex:不明}です。</p>
モデルデータ :
{ :sex => "男" }
出力 :
<p>彼の名前は不明で、性別は男です。</p>

1.7 条件テキスト展開

テキスト展開でも、? や ! で該当データが存在するかどうかを基準に展開させることができます。この場合、条件を満たすとデフォルト値に展開され、条件を満たさなければ、空文字列に展開されます。

テンプレート :
<p>hogeは@{?hoge:ある}@{!hoge:ない}がfooは@{?foo:ある}@{!foo:ない}。</p>
モデルデータ :
{ :foo => "ふ〜" }
出力 :
<p>hogeはないがfooはある。</p>

2. 特殊な展開

2.1 トップレベルのデータ

階層構造を持ったテンプレートでは、その階層に属さないモデルデータは展開されませんが、例外としてトップレベルのモデルデータだけは、どこでも展開されます。

テンプレート :
<div id="level1">
 <span id="level2_1">
  <b id="level3_1"></b>
  <b id="level3_2"></b>
  <b id="toplevel"></b>
 </span>
</div>
モデルデータ :
{ :level1 => { :level2_1 => { :level3_1 => "Level3_1" },
	       :level2_2 => { :level3_2 => "Level3_2" }},
  :toplevel => "TopLevel" }
出力 :
<div>
 <span>
  <b>Level3_1</b>
  
  <b>TopLevel</b>
 </span>
</div>

2.2 属性付データ

要素の中身だけでなく属性値も一緒に指定したい場合には、Temrita::a()メソッドを使います。ただし、これを使うとテンプレート側の自由度が低下しますので、あまりおすすめしません。大抵の場合は、属性値のテキスト展開を使えば解決します。

テンプレート :
<a id="site">サイト名</a>
モデルデータ :
{ :site => a({:href => "http://www.ruby-lang.org/ja/"}) { "Ruby" } }
出力 :
<a href="http://www.ruby-lang.org/ja/">Ruby</a>

2.3 部分テンプレート

モデルデータとして別のテンプレートを含むことができます。その場合、該当する要素の中身ではなく要素自身がそのテンプレートに置き換わります。また、モデルデータ中のテンプレートは、独立してそれ自身のモデルデータを持ちます。

テンプレート :
<div><span id="template">部分テンプレート</span></div>
モデルデータ :
part = Template.parse("<b>まるごと@{hoge}</b>")
{ :template => part[ {:hoge => "置換"} ] }
出力 :
<div><b>まるごと置換</b></div>

2.4 要素展開

モデルデータに部分テンプレートではなく単体の要素だけを含むこともできます。この場合は、部分テンプレートと違って、該当要素の中身だけが置き換わります。また、普通は文字列を展開する際に、&や<>など特殊な文字は自動的にエスケープされますが、Text要素をモデルデータに使うことで任意の文字列をエスケープせずに出力することができます。

テンプレート :
<div><span id="hoge">この中に展開されます。</span></div>
モデルデータ :
text = Temrita::Text.new(nil, "<b>Bold</b>")
elem = Temrita::Element.new(nil, "i") { "Italic" }
{ :hoge => [ text, elem ] }
出力 :
<div><span><b>Bold</b></span><span><i>Italic</i></span></div>

3. 展開オプション

3.1 テキスト展開指定

@{hoge}といった文字列をテンプレート内でそのまま使いたい場合、テキスト展開を無効にすることができます。ただし、テキスト展開を無効にしても属性値中での展開は有効です。

テンプレート :
<!-- Temrita::text_expand = "No" -->
<span>テキスト展開が@{hoge}になります。</span>
モデルデータ :
{ :hoge => "無効" }
出力 :
<span>テキスト展開が@{hoge}になります。</span>

3.2 エスケープ指定

展開文字列中に含まれる&や<>などの特殊文字は、自動的にエスケープされますが、エスケープしないようにもできます。この場合、モデルデータ中に危険な文字列を含まないように自力で管理する必要があります。通常は、前述の要素展開を使ってエスケープされたくない部分だけをText要素とした方がいいでしょう。

テンプレート :
<!-- Temrita::text_escape = "No" -->
<span id="hoge"></span>
モデルデータ :
{ :hoge => "<b>Bold</b>" }
出力 :
<span><b>Bold</b></span>

3.3 展開ID指定

id属性を本来の用途で使いたい場合、Temritaが使う属性名を変更することができます。

テンプレート :
<!-- Temrita::ID = "tid" -->
<span tid="hoge" id="foo">展開にid属性ではなくtid属性が使用される</span>
モデルデータ :
{ :hoge => "モデルデータ側では何の変更も必要ない" } 
出力 :
<span id="foo">モデルデータ側では何の変更も必要ない</span>

3.4 テキスト展開マーク指定

テキスト展開を無効にはしたくないが、@{hoge}という文字列を使いたい場合、テキスト展開用の記号を変更することができます。この場合、属性値内での展開にも変更後の記号が使用されます。

テンプレート :
<!-- Temrita::Mark = "$"
     Temrita::Bracket = "[]" -->
<span>@{hoge}の代りに$[hoge]が使える</span>
モデルデータ :
{ :hoge => "変更したマーク" }
出力 :
<span>@{hoge}の代わりに変更したマークが使える</span>

3.5 タグ除去指定

指定された名前の要素に展開用ID以外の属性値が存在しなかった場合、タグを出力しないようにできます。なお、複数のタグ名を指定することはできません。

テンプレート :
<!-- Temrita::Remove_tag = "span" -->
<div><span id="hoge">属性値のないspan要素のタグは消したい</span></div>
モデルデータ :
{ :hoge => "タグが消えてすっきり" }
出力 :
<div>タグが消えてすっきり</div>