VTL には、変数/プロパティ/メソッドという3種類のリファレンスがあります。
VTL を使うデザイナがテンプレートでリファレンスを正しく使えるように、
デザイナとエンジニアとの間で、
個々のリファレンスの名前について同意しておかなければなりません。
リファレンスに出入りするものはすべて、文字列オブジェクトとみなされます。
$fooという名前のオブジェクト (例えばIntegerオブジェクト) があるならば、
Velocity はオブジェクトを文字列にするために.toString()メソッドを呼びます。
変数
変数の簡略表記は、「$」とそれに続く VTL 識別子 から構成されます。
VTL 識別子は、英字から始めなければなりません (a・・・zまたはA・・・Z)。
先頭以外の文字についても、以下の種類に限定されます：
- アルファベット (a・・・z, A・・・Z)
- 数字 (0・・・9)
- ハイフン ("-")
- アンダースコア ("_")
VTL で有効な変数リファレンスの例をいくつか示します。
 |
|
|
|
$foo
$mudSlinger
$mud-slinger
$mud_slinger
$mudSlinger1
|
|
|
|
|
VTL が ($foo のような) 変数を参照する場合、
変数の値を、テンプレートの set 指示子、
または Java のコードから取得できます。
例えば、テンプレートが要求された時に Java 変数 $foo が値 bar
を持っていれば、Web ページ上で $foo の全てのインスタンスが
bar で置換できます。言い換えると、以下の文を入れると、
この指示子以降の $foo の全てのインスタンスについて出力は同じになります。
プロパティ
VTL リファレンスの第二の形式はプロパティで、特徴的なフォーマットを持っています。
簡略表記は、「$」とそれに続く VTL 識別子、それにドット「.」を挟んで続く別の
VTL 識別子から成ります。
VTL での有効なプロパティリファレンスの例を示します：
|
|
|
|
$customer.Address
$purchase.Total
|
|
|
|
|
最初の例 ($customer.Address) の場合は、2つの意味が考えられます。
一つは、customer で識別される hashtable を見て、
キー Address と関連づけられる値を返すという意味です。
しかし、$customer.Address はメソッドを参照しているのかも知れないのです。
(メソッドを参照するリファレンスは、次のセクションで説明します)。
$customer.Address は、$customer.getAddress()
の省略表記でもあるのです。
ページが要求されたとき、Velocity はこれらの2つの可能性のうち
どちらが意味をなすかを判定して、適切な値を返します
メソッド
メソッドは Java コードにおいて定義されるもので、何か役に立つこと
(計算や判定の実行など) を行うことができます。
メソッドは「$」と、それに続く VTL 識別子と、それに続く
VTL メソッドボディ (Method Body) から構成されるリファレンスです。
VTL メソッドボディは、VTL 識別子と、それに続く左括弧("(")、
パラメータリスト (オプション)、それに右括弧(")")から構成されます。
VTL で有効なメソッドリファレンスの例を示します。
|
|
|
|
$customer.getAddress()
$purchase.getTotal()
$page.setTitle( "My Home Page" )
$person.setAttributes( ["Strange", "Weird", "Excited"] )
|
|
|
|
|
最初の2つの例 ($customer.getAddress() と $purchase.getTotal()) は、
上のプロパティのセクションで使われた例
($customer.Addressと$purchase.Total)
に類似しているように見えるかもしれません。
これらの例は何か関係があるはずだと思ったら、それは正解です！
VTL プロパティは、VTL メソッドの簡略表記として使えます。
プロパティ $customer.Address は、
メソッド $customer.getAddress() を使うのと完全に同じ効果があります。
一般に、利用可能ならプロパティを使う方が望ましいです。
プロパティとメソッドの主な違いは、
メソッドにはパラメータリストを指定できるということです。
簡略表記は、以下のメソッドで使うことができます。
|
|
|
|
$sun.getPlanets()
$annelid.getDirt()
$album.getPhoto()
|
|
|
|
|
こうしたメソッドは、太陽系の惑星の名前を返すとか
ミミズに餌をやるとか、アルバムから写真を取り出すといったことが想定されるでしょう。
以下のメソッドは、長い表記だけが動作します。
|
|
|
|
$sun.getPlanet( ["Earth", "Mars", "Neptune"] )
## $sun.Planets にはパラメータリストを渡せません。
$sisyphus.pushRock()
## ($sisyphus.Rockだと) Velocity は $sisyphus.getRock() だと思ってしまいます。
$book.setTitle( "Homage to Catalonia" )
## パラメータリストは渡せません。
|
|
|
|
|
正式リファレンス表記
上で一覧として挙げた例では、リファレンスの簡略表記が使われました。
しかし、リファレンスのための正式表記もあります。以下に例を示します。
|
|
|
|
${mudSlinger}
${customer.Address}
${purchase.getTotal()}
|
|
|
|
|
ほとんどすべての場合、リファレンスには簡略表記を使用することになりますが、
正しく処理するために正式表記が必要となる場合があります。
例えば、動的に文を構築するのに、文で使われる名詞のベースとなる単語として$vice
を使うとしましょう。誰かにベースとなる単語を選択させて、
「Jack is pyromaniac.」あるいは「Jack is kleptomaniac.」という結果を生成します。
こういう場合、簡略表記を使用するとまずいのです。
以下の例を考えてみてください。
この表現は曖昧で、Velocity は識別子として、あなたが使いたい$viceではなく
$vicemaniac を認識します。$vicemaniac の値は見つからないので
$vicemaniac をそのまま返すことになります。
正式表記を使用することで、この問題を解決できます。
こうすれば Velocity は、$vicemaniac ではなく
$vice がリファレンスであると認識します。
正式表記が役に立つことが多いのは、
このようにリファレンスがテンプレート中でテキストと隣接している時です。
沈黙リファレンス表記
Velocity が未定義のリファレンスに遭遇したとき、
通常の挙動として、リファレンスの記述をそのまま出力します。
例えば、以下のリファレンスが VTL テンプレートの一部に出てきたとしましょう。
|
|
|
|
<input type="text" name="email" value="$email"/>
|
|
|
|
|
最初にフォームがロードされるとき、変数のリファレンス
$email には値がありませんが、
テキストフィールドに「$email」という値が入っているより
ブランクになっている方がよいでしょう。
リファレンスの沈黙表記を使用することで、Velocity の通常の挙動を回避します。
具体的には VTL で $email を使う代わりに、 $!email を使います。
したがって、上記の例は以下のようになります：
|
|
|
|
<input type="text" name="email" value="$!email"/>
|
|
|
|
|
これで、最初にフォームがロードされて $email がまだ値を持たないとき、
「$email」の代わりに空の文字列が出力されます。
リファレンスを正式表記かつ沈黙表記として使うことも出来ます。
具体的には以下のようにします。
|
|
|
|
<input type="text" name="email" value="$!{email}"/>
|
|
|
|
|
