Velocity ユーザガイドは、ページデザイナやコンテンツプロパイダに Velocity と、 Velocity の単純ながらも強力なスクリプト言語である Velocity テンプレート言語 (VTL:Velocity Template Language) の構文を理解していただくことを目的としています。 このガイドで出てくる例の多くは、Web サイトで動的に内容を埋め込むための Velocity の使い方を扱っていますが、VTL の例はすべて、 その他のページやテンプレートにも同様に適用できます。
Velocity を選んでいただきありがとうございます。
Velocity は、Java ベースのテンプレートエンジンです。 Velocityを使うと、Web ページデザイナが Java コードで定義されたメソッドを参照できます。Model-View-Controller(MVC) モデルに基づく Web サイト開発で、 Java プログラマと Web デザイナが並行して作業できます。つまり、 Web ページデザイナは素晴らしいデザインのサイトをつくることだけに集中し、 プログラマは最高のコードを書くことだけに集中することができるということです。 Velocity は、Java コードを Web ページから切り離し、長い目で見ればより保守しやすい Web サイトを実現し、 Java Server Pages(JSP) や PHP の実現可能な代替案を提供します。
Velocity は Web ページや SQL、PostScript といった出力をテンプレートから生成するのに 使えます。ソースコードや帳票を生成する単体のユーティリティとしても使えますし、 他のシステムに統合されるコンポーネントとしても使えます。 Velocityは、Turbine Web アプリケーションフレームワークでテンプレートサービスを提供します。 Velocity と Turbine の組み合わせで、真の MVC モデルにしたがって Web アプリケーションを開発できるテンプレートサービスを提供します。
あなたが陶土を専門に扱うオンラインストアのページデザイナであるとしましょう。 オンラインストアの名前は「Online Mud Store」としましょう。 商売は繁盛しています。顧客はいろいろな種類や量の商品を発注します。 サイトには名前とパスワードを使用してログインし、 発注したものを確認したり、さらに商品を購入したりできます。 現在、テラコッタ土 [訳注：素焼き用の陶土] はセール中で、とても人気があります。 赤土もセール中ですが、あまり人気が無く、少数の顧客が定期的に買うぐらいで、 いつもは Web ページの片隅に追いやられています。 各顧客に関する情報 [購買履歴など] はデータベースに記録されます。 そんなある日、こんな疑問が湧きます。「特別セールを行う時に、 セール対象の商品に最も興味を持っている顧客をターゲットとするのに Velocity を使うのはどうだろう？」
Velocity なら、オンライン訪問者ごとに Web ページを簡単にカスタマイズできます。 「The Mud Room」の Web サイトデザイナであるあなたは、顧客がサイトログイン後に見る Web ページを作ろうと思っています。
会社でソフトウェアエンジニアと打ち合わせをした結果、 $customer に現在ログインしている顧客に関する情報を保持し、 $mudsOnSpecial で現在セール中の全ての種類の商品の情報を保持することに なりました。 $flogger オブジェクトには、宣伝に役立つメソッドが入っています。 当面の作業では、これらの3つのリファレンスにだけ注目しましょう。 ソフトウェアエンジニアがどのように必要な情報をデータベースから抽出するかについては 気にしなくてよくて、 その情報が使えることだけ知っていればよいということ注目してください。 つまり、あなたもソフトウェアエンジニアも、自分の仕事にだけ注力できるということです。
以下の VTL 文を Web ページに埋め込みます。
| $flogger.getPromo( $mud ) |
foreach 文の詳細は後段で記述します; ここで重要なのは、この短いスクリプトがあなたの Web サイトにあたえるインパクトです。 赤土を好む顧客がログインしたとき、赤土がセール中であれば、 この顧客向けに、赤土がセール中であることを特に目につくように表示します。 テラコッタ土購入歴の長い顧客がログインしたときには、 テラコッタ土のセールのお知らせを一番目立つ場所に表示します。 Velocityの柔軟性は極めて高く、あとはあなたの創造力次第です。
VTLリファレンスには、その他たくさんの Velocity 要素が記述されており、 これらを組み合わせることで、 Web サイトの存在感 を高めるのに必要なパワーと柔軟性が得られます。 これらの要素に詳しくなれば、Velocity のパワーをさらに発揮できるでしょう。
Velocity テンプレート言語(VTL:Velocity Template Language) は、 Web ページに動的な内容を取り込むのに最も簡単で、最も単純で、 最も無駄のない方法となることを目標としています。 ほとんどプログラミング経験のない Web ページ開発者でも、 VTL を使えばすぐに、動的な内容を Web サイトに取り込めるようになるはずです。
VTL では Web サイトにおいて動的な内容を埋め込むのにリファレンス を使いますが、 変数はその一種です。変数とは Java コードで定義された何かを参照するリファレンスの一種で、 Web ページ内の VTL 文 から変数の値を取得できます。 HTML 文書に埋め込むことができる VTL 文の例を次に示します：
全ての VTL 文がそうであるように、この VTL 文は 「#」 から始まって、set という指示子を含みます。 Webページが要求されたとき、Velocity テンプレートエンジンは Web ページを走査して全ての 「#」を見つけ、 それぞれについて、どれが VTL 文の始まりでどれが VTL と無関係かを判定します。
「#」の後に指示子(set)が続いています。 set 指示子は、(括弧で囲まれた)式 -- 変数 に値 を割り当てる 等式 -- を使います。変数は左側で値は右側になります。この2つは、「=」で区切られます。
上の例では、変数は $a で値は Velocity です。 全てのリファレンスがそうであるように、この変数は 「$」で始まります。 値は常に引用符で囲まれます。Velocity では、文字列 (テキストに基づく情報) だけが変数に渡されるので、データ型に対する混乱は発生しません。
以下の簡単なルールが、Velocity がどのように動作するかをさらに理解するのに役立つでしょう。 リファレンスは、「$」 から始まって、何かを取得するのに使います。 指示子は、「#」 から始まって、何かを行うのに使います。
上の例では、#set は、値を変数に割り当てるのに使われます。 変数 ($a) は、「Velocity」を出力するのにテンプレートで使うことができます。
一旦変数に値が割り当てられたら、HTML 文書のどこででも変数を参照できます。。 下記の例では、値は $foo に割り当てられて後で参照されます。
結果として Web ページは、"Hello Velocity World!"を表示します。
VTL 指示子を含んだ文をより読みやすくするために、個々の VTL 文は、 新しい行から始めることを推奨しますが、これはもちろん強制ではありません。 set 指示子については、後ほど更に詳しく説明します。
コメントによって説明用のテキストを埋め込むことができます。 コメントはテンプレートエンジンの出力に含まれません。 コメントは、VTL 文がしていることを他人 (や未来の自分自身) に説明するのに役立つほか、 何か便利と思う目的に使うことができます。 下記は、VTL でのコメントの例です。
一行コメントは、## で始まり行末で終わります。 コメントを複数行書くのに、一行コメントをたくさん並べる必要ありません。 複数行コメント (#* で始まり *# で終わります) が、 そういった場合に利用できます。
一行コメントと複数行コメントの有効範囲を明確にするいくつかの例を示します：
コメントには第3の形式 (VTLコメントブロック) があります。 文書の作者やバージョン情報などを格納するために使われるかもしれません。
VTL には、リファレンスのタイプとして、変数、プロパティ、メソッドの3種類があります。 VTL を使うデザイナがテンプレートでリファレンスを正しく使えるように、 デザイナとエンジニアとの間で、 個々のリファレンスの名前について同意しておかなければなりません。
リファレンスに出入りするものはすべて、文字列オブジェクトとみなされます。
$fooという名前のオブジェクト (例えばIntegerオブジェクト) があるならば、
Velocity はオブジェクトを文字列にするために.toString()メソッドを呼びます。
変数
変数の簡略表記は、「$」とそれに続く VTL 識別子 から構成されます。
VTL 識別子は、英字から始めなければなりません (a..zまたはA..Z)。
先頭以外の文字についても、以下の種類に限定されます：
VTL で有効な変数リファレンスの例をいくつか示します。
VTL が ($foo のような) 変数を参照する場合、 変数の値を、テンプレートの set 指示子、 または Java のコードから取得できます。 例えば、テンプレートが要求された時に Java 変数 $foo が値 bar を持っていれば、Web ページ上で $foo の全てのインスタンスが bar で置換されます。言い換えると、以下の文を入れると、
この指示子以降の $foo の全てのインスタンスについて出力は同じになります。
プロパティ
VTL リファレンスの第二の形式はプロパティで、特徴的なフォーマットを持っています。
簡略表記は、「$」とそれに続く VTL 識別子、それにドット「.」を挟んで続く別の
VTL 識別子から成ります。
VTL での有効なプロパティリファレンスの例を示します：
最初の例 ($customer.Address) の場合は、2つの意味が考えられます。 一つは、customer で識別される hashtable を見て、 キー Address と関連づけられる値を返すという意味です。 しかし、$customer.Address はメソッドを参照しているのかも知れません (メソッドを参照するリファレンスは、次のセクションで説明します)。 $customer.Address は、$customer.getAddress() の省略表記でもあるのです。 ページが要求されたとき、Velocity はこれらの2つの可能性のうち どちらが意味をなすかを判定して、適切な値を返します
メソッド
メソッドは Java コードにおいて定義されるもので、何か役に立つこと
(計算や判定の実行など) を行うことができます。
メソッドは「$」と、それに続く VTL 識別子と、それに続く
VTL メソッドボディ (Method Body) から構成されるリファレンスです。
VTL メソッドボディは、VTL 識別子と、それに続く左括弧("(")、
パラメータリスト (オプション)、それに右括弧(")")から構成されます。
VTL で有効なメソッドリファレンスの例を示します。
最初の2つの例 ($customer.getAddress() と $purchase.getTotal()) は、 上のプロパティのセクションで使われた例 ($customer.Addressと$purchase.Total) に類似しているように見えるかもしれません。 これらの例は何か関係があるはずだと思ったら、それは正解です！
VTL プロパティは、VTL メソッドの簡略表記として使えます。 プロパティ $customer.Address は、 メソッド $customer.getAddress() を使うのと完全に同じ効果があります。 一般に、利用可能ならプロパティを使う方が望ましいです。 プロパティとメソッドの主な違いは、 メソッドにはパラメータリストを指定できるということです。
簡略表記は、以下のメソッドで使うことができます。
こうしたメソッドは、太陽系の惑星の名前を返すとか ミミズに餌をやるとか、アルバムから写真を取り出すといったことが想定されるでしょう。 以下のメソッドは、長い表記だけが動作します。
正式リファレンス表記
上で一覧として挙げた例では、リファレンスの簡略表記が使われました。
しかし、リファレンスのための正式表記もあります。以下に例を示します。
ほとんどすべての場合、リファレンスには簡略表記を使用することになりますが、 正しく処理するために正式表記が必要となる場合があります。
例えば、動的に文を構築するのに、文で使われる名詞のベースとなる単語として$vice を使うとしましょう。誰かにベースとなる単語を選択させて、 「Jack is pyromaniac.」あるいは「Jack is kleptomaniac.」という結果を生成します。 こういう場合、簡略表記を使用するとまずいのです。 以下の例を考えてみてください。
この表現は曖昧で、Velocity は識別子として、あなたが使いたい$viceではなく $vicemaniac を認識します。$vicemaniac の値は見つからないので $vicemaniac をそのまま返すことになります。 正式表記を使用することで、この問題を解決できます。
こうすれば Velocity は、$vicemaniac ではなく $vice がリファレンスであると認識します。 正式表記が役に立つことが多いのは、 このようにリファレンスがテンプレート中でテキストと隣接している時です。
沈黙リファレンス表記
Velocity が未定義のリファレンスに遭遇したとき、
通常の挙動として、リファレンスの記述をそのまま出力します。
例えば、以下のリファレンスが VTL テンプレートの一部に出てきたとしましょう。
最初にフォームがロードされるとき、変数のリファレンス $email には値がありませんが、 テキストフィールドに「$email」という値が入っているより ブランクになっている方がよいでしょう。 リファレンスの沈黙表記を使用することで、Velocity の通常の挙動を回避します。 具体的には VTL で $email を使う代わりに、 $!email を使います。 したがって、上記の例は以下のようになります：
これで、最初にフォームがロードされて $email がまだ値を持たないとき、 「$email」の代わりに空の文字列が出力されます。
リファレンスを正式表記かつ沈黙表記として使うことも出来ます。 具体的には以下のようにします。
VTL は、「$」 や 「#」のように特殊文字を使用するので、 テンプレート内でこれらの文字を使用する場合には注意が必要です。 このセクションでは、「$」をエスケープする方法を説明します。
通貨
「私は市場で 4ポンドの袋入りのジャガイモをたった $2.50 で買いました！」
と書くことについては問題はありません。
VTL 識別子は常に大文字または小文字の英字から始まるので、$2.50をリファレンスと間違えることはありません。
VTLリファレンスをエスケープする
Velocity が混乱する可能性がある場合もあります。
特殊文字のエスケープは、テンプレート内で VTL の特殊文字を扱う最適な方法であり、
バックスラッシュ(\)を使って行えます。
Velocity が VTL テンプレートで $email リファレンスを検出すると、 対応する値を求めてコンテキストを検索します。 ここでは、$email が定義されているので、出力は foo になります。 $email が定義されていなければ、出力は $email になります。
(例えば値が foo である) $email が定義されていて、 $email と出力したい場合を考えてください。 解決方法はいくつかありますが、最も単純なのはエスケープ文字を使うことです。
これは以下のように処理されます。
「$」の左隣に「\」があることに注意してください。 bind-from-left [左から演算を行う] 規則の結果、\\\$email は \\$email として処理されます。上記の例を、下記の$email が定義されない例と比較してみてください。
これは以下のように処理されます。
Velocity は、定義されていない場合と定義されていない場合とで、 リファレンスの扱いが異なることに注意してください。 以下の例では、set 指示子で $foo に値 gibbous をセットします。
出力は次のようになります。 $moon = gibbous -- $moon は未定義なのでリテラルとして出力され、 $foo の代わりに gibbous が出力されます。
VTL 指示子をエスケープすることも可能です。 この詳細については、 指示子 セクションで説明します。
リファレンスに慣れると、テンプレートで効果的にリファレンスを使えるようになります。 Velocity リファレンスでは Java のやり方を活用していますが、 テンプレートデザイナでも使うのは難しくないと思います。例を挙げましょう。
これらは、同じリファレンスのいろんな使い方の具体例です。 Velocity は、Java のイントロスペクション機能と Bean 機能を利用して、 コンテキスト内のオブジェクトと、オブジェクトメソッドの両方のリファレンス名を解決します。 テンプレート中のほぼどこにでもリファレンスを埋め込んで、評価することが可能です。
Velocity では、サンマイクロシステムズが策定した Bean 仕様書に元にモデルを作ったので、
大文字と小文字を区別します。しかし、Velocity の開発者は、
ユーザエラーを出来る限り検出して訂正するよう努力しました。
getFoo() メソッドが、テンプレート内で$bar.foo によって
参照されるとき、Velocityはまず $getfoo を試み、それに失敗すると、
$getFoo を試みます。
同じように、テンプレートが $bar.Foo を参照するとき、
Velocity は最初に $getFoo() を試みて、
それから getfoo() を試みます。
注意: テンプレート中のインスタンス変数への参照は解決されません。
JavaBean の getter/setter メソッドに対応する属性だけが解決されます。
(つまり、$foo.Name は、
Foo クラスのインスタンスメソッドである getName() としては解決されますが、
Foo のパブリックのインスタンス変数である Name としては解決されません。)
リファレンスを使うと、 テンプレートのデザイナが Web サイト向けに動的に内容を生成できるのに対して、 指示子 (使いやすいスクリプト要素で、Java コードの出力を思い通りに操作するのに使えます) を使うと、 Web デザイナは真の意味で Web サイトの内容と見栄えを管理できるようになります。
#set#set 指示子は、リファレンスの値をセットするのに使います。 値は、リファレンス変数かプロパティリファレンスにセットされ、 その際、以下に示すように丸括弧でくくります。
左辺(LHS:Left Hand Side)は、変数リファレンスまたはプロパティリファレンスでなければなりません。 右辺(RHS:Right Hand Side)は、以下のタイプのいずれかです：
以下は、上記タイプの各々の例です：
注意: 最後の例で [..] オペレータで定義された要素は ArrayList クラスで定義されているメソッドを使用してアクセスできます。したがって、 例えば、$monkey.Say.get(0) を使って上記の最初の要素 ("Not") にアクセスできます。
RHSには単純な計算式も入ります。
他の Velocity 指示子のいくつかとは異なり、#set 指示子には #end 文がありません。
文字列リテラル#set 指示子を使うとき、二重引用符(「"」)で囲まれた文字列リテラルは、 以下に示すようにパース／処理されます。
出力はこうなります
しかし、文字列リテラルが単一引用符 (「'」) で囲まれている場合には パースされません。
単一引用符を使ってテキストをパースせずに処理するという機能は、
Velocity ではデフォルトで利用できます。
このデフォルトは、velocity.properties を編集して
stringliterals.interpolate=false
とすることによって変更できます
Velocity の #if 指示子は、if 文の条件が真のとき、 Web ページの生成時にテキストを含むようにします。 例を挙げましょう。
変数 $foo が評価されて true かどうか判定されます。
true であるとは以下の2つの状況を指します。
(i) $foo が true の値を持つ boolean (true/false) の場合
(ii) $foo の値が null ではない場合
#if と #end の間の内容は、評価値が true の場合に出力されます。
この場合、$foo が true ならば、出力は「Velocity!」となります。
逆に、$foo が null または、boolean で false ならば、
文の評価は false となり、出力はありません。
#elseifまたは#else要素は #if要素と組で使用できます。 Velocity テンプレートエンジンは、最初に式が true になったところで評価を止めることに注意してください。 下記の例で、$foo が 15 の値を持ち、$bar は 6 の値を持つとします。
この例では、$foo は、10 より大きいので最初の 2 つの比較は失敗します。 次に、$bar が、6 と比較され、それが true なので、 出力は Go South となります。
注意: 現在、Velocity の数値の比較は Integer のみ行えます -- それ以外の場合には false と評価します。 これに対する唯一の例外は等号「==」です。その場合、「==」の両辺のオブジェクトは、 同じクラスである必要があります。
Velocity は、変数の関係を決定するために等価演算子を使います。 等価演算子の使い方の単純な例を示します。
Velocity には、さらに論理 AND と論理 OR 演算子があります。 以下は、if 文で論理 AND を使用した例です。
if 文は、$foo と $bar が共に true かどうか、 評価します。 $foo が false ならば、式全体は false に評価され $bar は、評価されません。 $foo が true ならば、Velocity テンプレートエンジンは、 次に $bar の値をチェックします。 $bar が true ならば、式全体が、true となって Velocity Rocks! が出力されます。 $bar が false ならば、式全体が false となって 出力されません。
論理 OR 演算子も同様ですが、式全体が true になるには true と評価されるリファレンス が1つだけあればよいというところだけが違います。 以下の例を考えてみてください。
$foo が true ならば、Velocity テンプレートエンジンは $bar を調べる必要はありません; $bar が true であるか false であるかどうかに関係なく、 式は true となり、 Velocity Rocks Again! が出力されます。 $foo が false ならば、今度は $bar をチェックしなければなりません。 この場合、$bar も false ならば、式は false と評価して、出力はありません。 一方、$bar が true ならば、式全体が true になり、 出力は Velocity Rocks Again! となります。
#foreach 要素を使うとループ処理ができます。例えば
この #foreach ループによって、$allProducts リスト (オブジェクト) で製品 (ターゲット) の全てについてループが行われます。 ループの一回一回で $allProducts からの値が $product 変数にセットされます。
$allProducts 変数の内容は、Vector、Hashtable、配列のいずれかです。 $product 変数に割り当てられる値は、Java オブジェクトで、 Java オブジェクトのように変数から参照できます。 たとえば、もし $product が本当に Java の Product クラスならば、 その名前は、$product.Name メソッド (= $Product.getName()) で参照して取り出すことができます。
$allProduct が Hashtable だとしましょう。もし Hashtable から、 キーの値と Hashtable 内のオブジェクトを取り出したい場合には、次のように コードを使用します。
Velocity ではループカウンタを簡単に取得できるので、 次のようなことができます。
ループカウンタ変数リファレンスのデフォルト名は、velocity.properties ファイル
に指定されている通り、$velocityCount です。カウンタはデフォルトでは
1 から開始しますが、velocity.properties ファイルで 0 か 1
のどちらかに設定できます。velocity.properties ファイルの
ループカウンタプロパティセクションの内容を以下に示します。
#include スクリプト要素でローカルファイルをインポートできます。 ファイルは #include 指示子が定義される位置に挿入されます。 ファイルの中身は、テンプレートエンジンによって処理されません。 セキュリティ上の理由から、インクルードされるファイルは、 TEMPLATE_ROOT 以下にあるものだけが許されます。
#include 指示子が参照するファイルは、引用符で囲まれます。 複数のファイルをインクルードする場合には、それらをコンマで区切ります。
インクルードされるファイルを名前で参照する必要はありません; 実際、多くの場合ファイル名の代わりに変数を使うことが望ましいです。 これは、ページ要求があったときに、事前に決めた基準にしたがって 出力を切り替えるのに役立ちます。 これは、ファイル名と変数両方を使用した例です。
#parse スクリプト要素で VTL を含むローカルファイルをインポートできます。 Velocity は、VTL を解析し、指定されたテンプレートを処理します。
#include 指示子と同じく、#parse はテンプレートの代わりに変数をとることができます。 #parse が参照するテンプレートはすべて、TEMPLATE_ROOT 以下になければなりません。 #include 指示子と違って、#parse の引数は一つだけです。
VTL テンプレートは、#parse 文で参照する
テンプレート内でさらに #parse 文で [別のテンプレートを]
参照できます。
あるテンプレートで入れ子にできる #parse
リファレンス数の最大値はデフォルトで10にセットされていて、
velocity.properties の
parse_directive.maxdepth 行で、カスタマイズできます。
(注：
parse_directive.maxdepth プロパティが velocity.properties
ファイルになければ、Velocity がこのデフォルトを 10 にセットします。)
再帰も可能です。例えば
テンプレート dofoo.vm が以下の行を含む場合、
以下の VTL の内容のテンプレート parsefoo.vm を参照します。
「カウントダウン。」が表示された後、
Velocity は parsefoo.vm を走査し、8 からカウントダウンします。
カウントが 0 に達すると、「parsefoo.vm の処理完了!」メッセージを表示します。
この時点で、Velocity はdofoo.vm に戻って、
「dofoo.vm の処理完了!」メッセージを出力します。
#stop スクリプト要素でテンプレートエンジンの実行を止めることができます。 これは、デバッグするときに役立ちます。
#macro スクリプト要素で、VTL テンプレートで繰り返し出てくる部分を定義できます。 Velocimacro は、単純なものから複雑なものまで広範囲にわたるシナリオで非常に役立ちます。 次の Velocimacro は、 キーストロークを少なくして入力ミスを少なくするためだけに作られたものですが、 Velocimacro の概念を紹介するのに役立つでしょう。
この例で定義されている Velocimacro は d です。そして、 それは他の VTL 指示子 と同じような方法で呼び出すことができます：
このテンプレートが呼ばれると、Velocity は #d() を一つの、 空のデータセルを含んでいる列と置換します。
Velocimacro は任意の数の引数を取ることが出来ます (最初の例で示したとおり引数なしでもかまいません)。 ただし、Velocimacro が呼び出されるとき、 定義されたのと同じ数の引数で呼ばれなければなりません。 多くの Velocimacro は、上記で定義したものより多くの引数を含みます。 これは、色と配列という2つの引数をとる Velocimacro です。
この例(tablerows)で定義されている Velocimacro は、2つの引数をとります。 最初の引数は、$color となり、2番目の引数は、$somelist となります。
VTL テンプレートに入れられるものは何でも、Velocimacro の本体に入れることができます。 tablerows Velocimacro は、foreach 文です。 2つの #end 文が、#tablerows Velocimacro の定義にありますが、 最初の end で #foreach が終了し、二番目の end で Velocimacro 定義が終了します。
$greatlakes が $somelist に代わることに注意してください。 #tablerows Velocimacro が上記のように呼ばれるとき、以下の出力が生成されます。
Velocimacro は Velocity テンプレート内で インライン で定義できますが、 その場合は同じ Web サイトの他の Velocity テンプレートには利用できません。 全てのテンプレートで共有できるような Velocimacro を定義することは、 明らかにいくつかの利点があります。例えば、多数のテンプレートで Velocimacro をいちいち定義する必要が少なくなり、 それにより作業量が少なくなり、エラーの可能性が減り、 一つのマクロに対する一箇所の変更が複数のテンプレートに反映されることを保証します。
Velocimacro プロパティ
velocity.propertiesファイル内の何行かを使えば、Velocimacro を柔軟に実装できます。注意: 開発者ガイドも参照してください。
velocimacro.library
-
全ての Velocimacro テンプレートライブラリのコンマ区切りリスト。
デフォルトでは、Velocity は VM_global_lib.vm
というライブラリのみを探します。
設定されたテンプレートパスは Velomacro ライブラリを見つけるのに使用されます。
velocimacro.permissions.allow.inline
-
このプロパティは true または false の値を取ることができ、
Velocimacro を通常のテンプレートで定義できるかどうか判定します。
デフォルト (true) では、テンプレートで Velocimacro を定義できます。
velocimacro.permissions.allow.inline.to.replace.global
-
このプロパティは true または false の値を取ることができ、
テンプレート内でインラインで定義された Velocimacro が
グローバルで定義されたテンプレート
(スタートアップ時にvelocimacro.library
プロパティ経由でロードされたもの)
を置換できるかどうかを指定します。
デフォルトでは false なので、
スタートアップでロードされたテンプレートライブラリで定義されたものは
インラインの Velocimacro では置換できません。
velocimacro.permissions.allow.inline.local.scope
-
このプロパティは true または false の値を取ることができ、
デフォルトは false です。
インラインで定義された Velocimacro が、
定義したテンプレートでだけ「見える」かどうかを制御します。
つまり、このプロパティを true にすると、定義されたテンプレート内でのみ有効な
インライン VM を定義することが出来ます。
これを使った、手の込んだ VM のテクニックがあります。
グローバルな VM が別のグローバルな VM を呼ぶ場合、
テンプレートはインラインスコープで、前者の VM から呼ばれる後者の
VM のプライベート実装を定義できます。
他のどのテンプレートにも影響ありません。
velocimacro.context.localscope
-
このプロパティは true または false の値を取ることができ、
デフォルトは false です。
true のときは、Velocimacro 内の #set() によるコンテキストへの変更はすべて、
Velocimacro に「ローカル」であると扱われて、
コンテキストに永続的な影響を及ぼしません。
#tablerows($color $list) Velocimacro が Velocimacro
テンプレートライブラリで定義されている場合、
このマクロはどの通常のテンプレートでも使うこともできます。
それは、何度でも使えますし、どんな用途でも使うことが出来ます。
菌類百科専門の mushroom.vm テンプレートの中で、
#tablerows Velocimacro は、
典型的なキノコの各部分をリストするために呼び出すことができます：
mushroom.vm の要求を満たすとき、Velocity は
#tablerows Velocimacro をテンプレートライブラリ
(velocity.properties ファイルにおいて定義されています) で見つけて、
以下の出力を生成します。
Velocimacro は、以下の VTL 要素のどれでも引数として取ることができます。
Velocimacro の引数としてリファレンスを渡す際、 リファレンスは「名前渡し」されることに注意してください。 つまり、Velocimacro 内で使われるたびにその値が「生成される」ことを意味します。 この機能を使って、リファレンスにメソッド呼び出しを渡して、 使うたびにそのメソッドを呼ぶようにできます。 例えば、以下に示すように Velocimacro を呼び出すと、
結果として、リファレンス $foo のメソッド bar() が3回呼び出されます。
一見、この機能は驚くべきことのように見えます、 しかし、あなたが Velocimacro の背景にある最初の動機 -- よく使われる VTL をカット&ペーストすることによる重複を除去する -- を考慮すれば、納得できるかと思います。 この機能により、 Velocimacro に「状態を保持する」(Stateful) オブジェクト (例えばテーブル列に色をつけるために繰り返しシーケンスで色を生成するオブジェクト) を渡すようなことができます。
この機能を回避する必要があるならば、常にメソッドから値をリファレンスとして取得し、 それを渡せばよいのです。
現在、Velocimacro はテンプレートで最初に使われる前に定義されていなければなりません。 つまり、 #macro() 宣言が Velocimacro を使う前に出てくる必要があります。
インライン #macro() 指示子を含んでいるテンプレートを #parse()
しようとするときには、このことに気をつける必要があります。
というのも、 #parse() は実行時に発生し、
パーサはテンプレート中の VM のように見える要素が VM かどうかをパース時に判定するため、
VM 宣言を #parse() しても期待したようには動かないのです。
これを回避するには、単に velocimacro.library 機能を使ってください。
Velocity はあなたの VM を起動時にロードします。
VTL 指示子は、VTL リファレンスと同様に、バックスラッシュ (「\」) でエスケープできます。
一つの指示子に複数のスクリプト要素が含まれている VTL 指示子 (if-else-end 文など)をエスケープする時は、 特に注意が必要です。 典型的な VTL の if 文は以下のようなものです：
$jazz が true ならば、出力は
です。
$jazzが false ならば、出力はありません。 スクリプト要素をエスケープすると、出力が変わります。 以下の場合を考えてみましょう。
$jazz が true か false かどうかに関係なく、 出力は、
となるでしょう。 実際、全てのスクリプト要素がエスケープされるので、$jazz の真偽は決してチェックされません。 バックスラッシュが正当にエスケープされたスクリプト要素の前にあるとしましょう。
この場合、$jazzが true ならば、出力は
です。
これを理解するためには、#if( arg ) が
改行(return) で終了しているときに、その改行は出力から除外されることに着目してください。
そのため、#if() ブロックのボディが最初の「\」 (#if() とその前の 「\\」 の処理結果)に続きます。
最後の「\」は別の行になっています。それは、「Ganelin」の後に改行があり、
#end の前にある最後の \\ は、ブロックのボディの一部であるためです。
$jazzが false ならば、出力はありません。
[訳注：実際には、#if( arg ) とその前の「\\」の処理結果である「\」
だけが出力されます。]
スクリプト要素が適切にエスケープされていなけば、おかしくなることに注意してください。
ここでは、#if はエスケープされますが、#end が残っています。 end が余分なので、解析エラーを引き起こすことになります。
このユーザガイドの中の VTL は多くの場合、下記のように改行と空白を含んで表示されています。
Geir Magnusson Jr. は、改行や空白が全く無関係というのを示すために Velocity ユーザのメーリングリストに次のようなコードを投稿しました。
Velocity は、余分な空白を吸収するように振舞います。 上の指示子は以下のように書くことができます。
または
どちらの場合も出力は同じです。
Velocity には一握りですが組み込みの計算機能があり、 テンプレートのset 指示子で使うことができます。 以下の式は、それぞれ加算、減算、乗算、除算の例です：
除算が実行される場合も結果は整数となります。 余りについては剰余 (「%」) 演算子を使って取得できます。
Velocity で数式演算を実行する時は、整数だけ(... -2, -1, 0, 1, 2 ...)が許可されており、 非整数が使われるとログに記録され、null が出力として返されます。
Velocity でのゼロ除算の扱い方を説明します。 下記の例では、
リファレンス $uhoh には 5 / 0 の結果の値がセットされます。 Velocity がこのテンプレートを処理するとき、出力は次のようになります。
デザイナは set が文字列を生成することに注意すべきです。 そして、その文字列を範囲演算子で使うためには整数に変換しなければなりません。 この例は、そのような変換を示します。
この結果は 17 になります。
範囲演算子は、#set や #foreach 文と一緒に使うことができます。 要素に整数を持つオブジェクト配列を生成するのに役立つ範囲演算子は、 次のように生成できます。
n と m は両方とも整数であるか、整数を生成しなければなりません。 m が、n より大きいか、小さいかは重要ではありません; より小さい場合には、範囲は単にカウントダウンします。 下記は範囲オペレーターの利用を示している例です：
以下の出力を生成します:
4番目の例が示しているとおり、範囲演算子は #set と #foreach 指示子とともに使われた時だけ配列を生成することに注意してください。
HTMLの表を決まったサイズにしたいのに、 表を埋めるにはデータが足りないこともあります。 そんな時、範囲演算子は特に便利です。
リファレンスを「!」で沈黙させていて、 「!」の前に「\」エスケープ文字があるときは、 リファレンスは特別扱いされます。 通常のエスケープと、 「\」に「!」が続く特別な場合の違いに注意してください。
これは以下のように処理されます。 [訳注: 2行目は実際には「\$!{」となります。]
これを、「\」が「$」に先行する、通常のエスケープと比較してください、
これは以下のように処理されます。
このセクションは、Velocimacro に関するミニ FAQ です。 このセクションは、時とともに変更されるでしょう、 ですから新しい情報を時々確認するのは有用です。 [訳注：このバージョンでは変更されませんが、 次のバージョンでは変更されているかもしれません]
注意: このセクションでは、「Velocimacro」は通常「VM」と省略します。
VM の引数として指示子や他の VM を使用できますか?
例 : #center( #bold("hello") )
いいえ。指示子は指示子の有効な引数にはなりません。 また、一般的に、 VM は指示子です。
それでも…、解決策はあります。簡単なものとして、 ダブルクォート (") がその内容を処理することを利用する方法があります。 なので、このようにできます。
以下のように省略も可能です…
注意: 後者の例では、引数は VM 内部で評価されます。呼び出し時ではありません。 言い換えると、VM への引数は、そっくりそのまま渡されて、 渡された VM の中で評価されます。その結果、次のようなことが可能です。
ここで出力は以下のようになります。
"#inner($bar)" の評価は、#outer() の内部で発生するため、 $bar の値としては #outer() 内部でセットされたその値が使われます。
この機能は意図的なものであり、十分に保護されています - 引数は VM に「名前渡し」されるので、以下のように、 「状態を保持する」(Stateful) リファレンスなどを VM に渡すことが出来ます。
また、rowColor() は1回ではなく、[#foo() の呼び出しごとに] 何度も呼ばれます。 これを禁止するには、 VM の外側でメソッドを呼び出し、 VM には値を渡してください。
現在、Velocimacro はテンプレートで最初に使われる前に定義されていなければなりません。 つまり、 #macro() 宣言が Velocimacro を使う前に出てくる必要があります。
インラインの #macro() 指示子を含んでいるテンプレートを #parse()
しようとするときには、このことに気をつける必要があります。
というのも、 #parse() は実行時に行われ、
パーサは、テンプレート内の VM のように見える要素が VM かどうかをパース時に決定するため、
VM の宣言を #parse() しても期待したようには動かないのです。
これを回避するには、単に velocimacro.library 機能を使ってください。
Velocity はあなたの VM を起動時にロードします。
そのためのプロパティがあります。これは開発時に使用するためのもので、 本番環境用ではありません。
velocimacro.library.autoreload
デフォルトは、 false です。 true にセットする時は、下記の指定と一緒に使います。
<type>.resource.loader.cache = false
(ここで、 <type> は、'file' など使用するリソースローダの名前です) そうすると Velocity エンジンは、自動的にあなたの Velocimacro ライブラリファイルが変更されたときに変更をリロードしようとします。 そのため、サーブレットエンジン (あるいはアプリケーション) を再起動したり Velocimacro をリロードするために小細工をする必要はありません。
簡単なプロパティ設定はこのようになります。
本番環境ではこの状態のままにしておかないでください。
このマニュアルの誤りなど、Velocity ユーザガイドに関するフィードバックを行う時は、 Velocity ユーザメーリングリスト に電子メールを送ってください。 よろしくお願いします。