Velocity ユーザー・ガイドは、ページ・デザイナーおよび、コンテンツ･プロパイダーが、 単純だけれども、強力なスクリプト言語である Velocity とその Velocity テンプレート言語 (VTL) の構文を知るために役立つガイドにするつもりです。 このガイドは、Web サイトにおいて動的に内容を埋め込むために Velocity を使う 多くの例を扱っていますが、全ての VTL の例は同様に他のページやテンプレートに適用できます。
Velocity を選択してくれてありがとう!
Velocity は、Java ベースのテンプレートエンジンです。 それは Java コードで定義されたメソッドを参照することを Web ページデザイナーに許します。 Model-View-Controller(MVC) モデルにより Web サイトを開発するので Java プログラマと Web デザイナーが平行に作業することができるため Web ページ・デザイナーはサイトの見栄えをつくることだけに集中し、 プログラマーが最高のコードを書くことだけに集中することができることを意味します。 Velocity は、Java コードを Web ページから切り離し、長い目で見れば、より保守しやすい Web サイトを作成し、 Java Server Pages(JSP) や PHP の実行可能な代案を提供します。
Velocity の可能性は、Web サイトの領域を越えて広がります; 例えば、テンプレートから SQL と PostScript と XML(XML変換の詳細は Anakia を参照のこと) を生成することができます。 また、独立したユーティリティとして、ソース・コードを生成したり、レポートを生成したり、 他のシステムとの統合をするためのコンポーネントとして使用することができます。 Velocityはまた、テンプレート・サービスをTurbine Web アプリケーション・フレームワークのために用意しています。 Velocity+Turbine は、本当の MVC モデルにより開発される Web アプリケーションを構築できるテンプレート・サービスを提供します。
あなたが泥を売ることを専門に扱うオンライン・ストアの ページ・デザイナーであるとしましょう。 それを「オンライン泥ストア」としましょう。 ビジネスは、成功しています。 顧客の立場では、いろいろな種類の泥や量を発注します。 彼らは、あなたのサイトに自分の名前とパスワードを使用してログインし 発注したものを確認して見たり、さらに泥を購入することが出来ます。 現在、テラコッタ泥は発売中で、それはとても人気があります。 あなたの顧客の少数派は、定期的に明るい赤泥（それはまた、発売中です）を買います人気があり、そして、通常あなたのWebページのマージンに任せられる。 各々の顧客に関する情報はある日、問題が起こるように、あなたのデータベースにおいてたどられてす、泥のそれらのタイプに最も興味を持っている顧客に、泥の上で特別な処置を目標とするために Velocity を使いませんか？
Velocity は、あなたのオンライン訪問者に対してカスタマイズした Web ページを簡単に作成することができます。 「The Mud Room」での Web サイト・デザイナーとして、あなたは顧客があなたのサイトに ログイン後に見る Web ページを作りたいのです。
あなたはあなたの会社でソフトウェア・エンジニアに会います、そして、 誰でも $customer が現在ログインしている顧客に関係する情報を 保持し、$mudsOnSpecial が現在発売中の全てのタイプの泥の 情報を保持することに同意しました。 $flogger オブジェクトは、宣伝を手伝うメソッドを含みます。 当面の作業のために、これらの3つのリファレンスだけに注目しましょう。 覚えていてください、あなたはソフトウェア・エンジニアが必要な情報を データベースから抜き取る方法について心配する必要がありません、 あなたはそれが働くということを知っている必要があるだけです。 これは、あなたは自分の仕事に取り掛かり、ソフトウェア・エンジニアには 彼らの仕事に取りかからせることになります。
あなたは、以下の VTL 文を Web ページに埋め込みます。
| $flogger.getPromo( $mud ) |
foreach文の正確な詳細は、簡素により素晴らしく深く記述されることになります; 重要なことは、この短いスクリプトをあなたの Web サイトに提供できるという衝撃です。 Bright Red Mud を好む顧客がログインして、Bright Red Mud がセール中であるときに、 この顧客は、特に目につくように表示されたものを見ることになります。 テラコッタ泥購入の長い歴史をもつ別の顧客がログインしたときには、 テラコッタ泥販売の通知は、正面の真中に表示されます。 Velocityの柔軟性は、たいへん強力なので、制限はあなたの創造力だけです。
集合的にあなたにあなたがあなたの Web サイトに Web presenceを作るために必要とするパワーと柔軟性を与える多くの他の Velocity 要素は、VTLリファレンスにおいて文書化されます。 あなたがこれらの要素により精通しているようになるので、あなたは Velocity のパワーを発揮し始めることになります。
Velocityテンプレート言語(VTL) は、動的に内容をWebページに取り入れるために最も簡単で、最も単純で最もきれいな方法を提供するはずです。 ほとんどプログラミング経験のないWebページ開発者さえ、すぐに動的な内容をWebサイトに取り入れるために VTL を使うことができるはずです。
VTL は Web サイトにおいて動的な内容を埋め込むためにリファレンスを使います、そして、変数はリファレンスの1つの型です。 変数は Java コードにおいて定義される何かを呼び出すことができるリファレンスの1つの型です、あるいは、それは 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 でのコメントの例です。
一行コメントは、## から始まり、行末まで続きます。 複数行のコメントを書くのには、たくさんの一行コメントは必要ありません。 複数行コメント（それは #* ではじまり、*# で終了します）は、 そのような場合に利用できます。
一行コメントと複数行コメントの有効範囲を明確にする2、3の例は、ここにあります：
コメント (VTLコメント・ブロック) の第3のタイプがあります。 それは文書著者とバージョン情報などを格納するために使われるかもしれません：
VTL には、3種類のリファレンスのタイプがあります： 変数とプロパティとメソッドです。 VTL を使っているデザイナーとして、あなたがあなたのテンプレートで正しくそれらを使うことができるように、あなたとあなたのエンジニアはリファレンスの特定の名前に関する合意をしなければなりません。
リファレンスへ／からやって来るものすべては、文字列オブジェクトとみなされます。
$foo（例えば整数オブジェクト）を表すオブジェクトがあるならば、Velocity はオブジェクトを文字列に分解するためにその.toString()メソッドを呼ぶことになります。
変数
変数の短縮形表記法は、「$」文字に続くVTL 識別子から構成されます。
VTL 識別子は、英字から始めなければなりません（a..zまたはA..Z）。
文字の残りは、以下の文字のタイプ限定されます：
ここに、いくつかの有効な VTL での変数リファレンスの例があります。
$fooのように、VTL が変数を参照するとき、テンプレートまたは Java から指示的な set がコード化するどちらからでも、変数はその値を得ることができます。 例えば、テンプレートが要求される時、Java 変数 $foo が値 bar を持つならば、bar は Web ページ上で $foo の全てのインスタンスと置き換えられます。 代わりに、私はステートメントを含ます
出力は、この指令以降の $foo の全てのインスタンスは同じになります。
Properties
VTL リファレンスの第二の特色は、プロパティと特徴的なフォーマットを持つプロパティです。
短縮形表記法は、$文字に続く VTL 識別子と、ドット「.」によってつづく別の VTL 識別子
があります。
これらは、VTL での有効なプロパティ・リファレンスの例です：
最初の例（$customer.Address）をみてください。 それは、2つの意味を持つことができます。 それは意味することができます ― customer と確認される hashtable で見てください、そして、キー Address と関連される値を返してください。 しかし、$customer.Address は、また、メソッド（メソッドを呼ぶリファレンスは、次のセクションにおいて検討されることになります）を呼ぶことができます; $customer.Address は、$customer.getAddress() を書くことの略記された方法でもあります。 あなたのページが要求されるとき、Velocity はこれらの2つの可能性のうちどちらが意味をなすかについて決定して、それから適切な値を返します
Methods
メソッドは Java コードにおいて定義されて、役に立つ何かをすることができます、計算を実行するか、決定で到着するのが好きにしてください。
メソッドは「$」文字で始まり、それに続く VTL 識別子と、それに続く
VTL Method Body から構成されるリファレンスです。
VTL Method Body は、VTL 識別子と左括弧文字（"("と、それに続くオプションのパラメータ・リスト、それに続く右括弧(")")から構成されます。
これらは、VTL での有効なメソッド・リファレンスの例です：
最初の2つの例（$customer.getAddress()と$purchase.getTotal()）は、上のプロパティ・セクション（$customer.Addressと$purchase.Total）において使われるそれらに類似したように見えるかもしれません。 あなたがこれらの例が関係がなければならないと思うならば、若干の流儀の中のいくつか、あなたは正しいです！
VTL プロパティが、VTL メソッドのために短縮形表記法として使われることができます。 プロパティ $customer.Address は、 メソッド$customer.getAddress() を使いながら正確な同じ効果を持ちます。 利用できるとき、一般にプロパティを使うことが、好ましいです。 プロパティとメソッドの主な違いは、あなたがメソッドにパラメータ・リストを指定することができるということです。
短縮形表記法は、以下のメソッドで使うことができます
我々は、これらのメソッドが太陽に属している惑星の名前を返すか、 我々のミミズに餌をやるか、アルバムから写真を得るのを期待するかもしれません。 以下のメソッドは、長い表記法だけが動作します。
Formal Reference Notation
リファレンスのための短縮形表記法が上でリストされる例のために使われました、しかし、形式的な表記法がまた、リファレンスのためにあります。そして、それはデモをされます：
ほとんどすべての場合には、あなたはリファレンスのために短縮形表記法を使用することになります、しかし、若干の場合には、形式的な表記法は正しい処理のために必要です。
$viceが文の名詞でベース語として使われることになっていた所で、 あなたが飛んで文を構成していたと思ってください。 目的は、ベース語を選ぶ誰かを許して、以下の2つの結果のうちの1つを生じることです： 「Jack is pyromaniac.」、あるいは、「Jack is kleptomaniac.」となります。 短縮形表記法を使用することは、この作業に不適当です。 以下の例を考えてみてください：
ここに曖昧さがあり、そして、Velocity は$viceではなく、 $vicemaniac があなたが使うつもりである識別子であると仮定します。 $vicemaniac のために値が見つからず、 それは $vicemaniac を返すことになります。 形式的な表記法を使用することで、この問題を解決することができます。
これで、Velocity は$vicemaniacではなく、$viceがリファレンスであるということが認識できます。 リファレンスがテンプレート中でテキストと直近のとき、形式的な表記法は多くの場合役に立ちます。
Quiet Reference Notation
Velocity が未定義リファレンスに遭遇したとき、その標準的な挙動はリファレンスのイメージを出力します。
例えば、以下のリファレンスは VTL テンプレートの一部として現れると思ってください。
最初にフォームがロードされるとき、変数のリファレンス $email には値がありません、 しかし、あなたは「$email」という値より空白のテキスト・フィールドを好みます。 Silentリファレンス表記法を使用することで、Velocity の標準的な挙動を回避します; VTL で $email を使う代わりに、あなたは $!email を使います。 それで、上記の例は、以下のように見えます：
これで、フォームの初期読み込みで、$email がまだ値を持たないとき、 「$email」の替わりに空の文字列が出力されます。
形式的なリファレンスと Silent リファレンス表記法を一緒に使うことができます。 それは以下でデモされます。
VTL は、$ と # というよな特別な文字を使用するので、 あなたのテンプレートでこれらの文字を使用する場合には注意が必要です。 このセクションでは、$ 文字をエスケープする方法を説明します。
通貨
「私は、たった$2.50ドルで農夫の市場で、4ポンド入りのジャガイモの袋を買いました！」
と書くことについては問題はありません。
VTL識別子は常に大文字または小文字の英字から始まるので、$2.50はリファレンスと間違えることはありません。
Escaping Valid VTL References
Velocity が混乱する可能性がある所で、発生するかもしれません。
エスケープ特別な文字、あなたのテンプレートとこれでの VTL の特別な文字が
バックスラッシュ（\）を使って、正当に扱われることができるハンドルに最高の方法は、
文字です。
Velocity があなたの VTL テンプレートで$emailリファレンスを検出すると、 それは対応する値を求めてコンテキストを捜すことになります。 ここでは、$email が定義されるので、出力は foo になります。 $email が定義されないならば、出力は $email になります。
$email が定義される（例では値 foo を持ちます）、 そして、あなたが $email を出力したいと仮定します。 これを行なう2、3の方法があります、しかし、最も単純なものはエスケープ文字を使うことです。
このようにレンダリングされます
\ 文字が左から $ まで縛ることに注意してください。 bind-from-left 規則は、\\\$email として提出する \\$email を引き起こします。 これらの例を $email が定義されないそれらと比較してください。
renders as
Velocity は、定義されなかったものと定義されものとでリファレンスの扱いが異なる ことに注意してください。 $foo に値 gibbous を与えるセットされた指令は、ここにあります。
出力が、次のようになります。 $moon = gibbous -- ここで $moon は、リテラルとして出力されます。 というのは、それは未定義で、$foo の場所には gibbous が出力されるからです。
VTL 指令をエスケープすることも、可能です; これは、指令セクションにおいて更に詳細に記述されます。
あなたがリファレンスに精通している今、あなたはあなたのテンプレートで効果的にそれらを適用し始めることができます。 Velocity リファレンスは、テンプレート・デザイナーが使いやすいと見つけることになる若干の Java 原則を利用します。 例：
これらの例は、同じリファレンスの他の用途を図示します。 Velocity は、コンテキストで両方のオブジェクトにオブジェクト・メソッドと同様にリファレンス名を分解するために Java の introspection と bean 機能を利用します。 あなたのテンプレートに埋め込んで、ほとんどどこにでもリファレンスを評価することは、可能です。
Velocity（それはサン・マイクロシステムズによって定義される bean 仕様書にならって作られます）は、大文字と小文字の区別がされます;
しかし、開発者はユーザー・エラーを捕えて、訂正するために努力するようにすることが可能です。
メソッドgetFoo()が$bar.fooによってテンプレートで呼ばれるとき、Velocityは最初に$getfooを試みることになります。
これが失敗するならば、それはそれから$getFooを試みることになります。
同じように、テンプレートが$bar.Fooを呼ぶとき、Velocityは最初に$getFoo()を試みることになって、それからgetfoo()を試みることになります。
注意: テンプレートのインスタンス変更への参照は、解決されません。
JavaBean と同様な属性への参照のみの getter/setter メソッドが解決されます。
(つまり、$foo.Nameは、クラス Foo の getName()
インスタンスメソッドの解決されますが、Foo のインスタンス変更である
public Name ではありません。)
リファレンスは、Web サイトに動的に内容を生成するためにテンプレート・デザイナーを許します。directives− 創造的に Java コードの出力を操作するために使われることができる使いやすいスクリプト要素−は、 Web デザイナーが本当に Web サイトの内容と見栄えを引き受けることができるようにします。
#set#set 指示子は、リファレンスの値をセットするために使われます。 値はリファレンス変数かプロパティ・リファレンスに割り当てられることができます、そして、これは括弧内で起こります。そして、そのことはデモをしました：
左辺（LHS）は、可変のリファレンスまたはプロパティ・リファレンスでなければなりません。 右辺（RHS）は、以下のタイプのうちの1つでありえます：
これらの例は、前記のタイプの各々を示します：
注意: 要素が定義した最後の例で [..] ArrayList クラスで定義されるメソッドを使用してアクセスできるオペレーターは、います。 それで、例えば、あなたは $monkey.Say.get(0) を使うことより上に最初の要素にアクセスすることができます。
RHSは、また、単純な算術式でありえます：
他の Velocity 指令の一部と違って、#set 指示には、 #end ステートメントがありません。
String Literals#set 指示を使うとき、文字列リテラルは、 ダブルクオート文字で囲む場合には、以下に示すようにレンダリングされます。
出力はこうなります
しかし、文字列リテラルがシングルクオートで囲まれている場合には、 解析されません。
デフォルトで、テキストを解析されないようにするシングルクオートを使ったこの機能は、
Velocity で利用できます。
このデフォルトは、velocity.properties を編集して
stringliterals.interpolate=false
とすることによって変更することができます
Velocity の #if 指示子は、Web ページの生成時に if 文の条件が真でのときに、テキストが生成されます。 例：
変数 $foo はそれが true かどうか決定するために評価されます。 そして、それは2つの状況のうちの1つの下で起こることになります： (i) $foo は true の値を持つ boolean（true/false）です、 あるいは、(ii) 値は null ではありません。 この場合、$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 の数の比較は整数まで切り上げされます -- そうでない場合には false と評価することになります。 これに対する唯一の例外は等号「==」です、Velocity は、「==」の両辺に存在する 各々のオブジェクトは、同じクラスを要求します。
Relational and Logical Operators
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 になるように評価をする必要があるリファレンス のひとつを除き同じように作用します。 以下の例を考えてみてください。
$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 オブジェクトであって、 このように変数からリファレンスをつけられることができます。 たとえば、もし $product が本当に Java の Product クラスならば、 その名前は、$product.Name メソッドで参照して取り出すことができます。 (すなわち $Product.getName()）。
$allProduct が Hashtable だとしましょう。もし Hashtable からキーの値を 取り出し、Hashtable 内のオブジェクトを取り出したい場合には、次のように コードを使用します。
Velocity provides an easy way to get the loop counter so that you can do something like the following:
ループカウンタ変数参照のためのデフォルト名は、velocity.properties ファイル
に指定されている、$velocityCount です。カウンタのデフォルト値は
1 から開始しますが、0 や 1 に設定することが、velocity.properties
ファイルで可能です。これは、velocity.properties ファイルの
ループカウンタプロパティセクションにあります。
#include スクリプト要素はローカル・ファイルをインポートするためにテンプレート・デザイナーを許します。そして、それはそれから #include 指示が定義される位置に挿入されます。 ファイルの中身は、テンプレートエンジンによってレンダリングされません。 セキュリティ上の理由のために、インクルードされるファイルは、 TEMPLATE_ROOT の下にあるだけかもしれません。
#include 指示子が呼ぶファイルは、引用符において囲まれます。 複数のファイルをインクルードする場合には、それらをコンマで区切ります。
インクルードされるファイルは、名前でリファレンスをつけられる必要はありません; 実際、多くの場合ファイル名でなく変数を使うことが、好ましいです。 ページ要求が提出されるとき、これは決定される基準によって出力を決定するのに役立ちます。 ここに、ファイル名と変数を示している例があります。
#parse スクリプト要素は、VTL を含むローカル・ファイルをインポートするためにテンプレート・デザイナーを許します。 Velocity は、VTL を解析することになって、指定されるテンプレートをレンダリングします。
#include 指示子のように、#parse は、テンプレートよりむしろ変数をとることができます。 #parse が呼ぶどんなテンプレートでも、TEMPLATE_ROOT の下で含まれなければなりません。 #include 指示子と違って、#parse は、ひとつの引数をとることになるだけです。
VTL テンプレートは、#parse ステートメントを持つ
テンプレートの中からさらに #parse を呼ぶことができます。
デフォルトで10にセットされて、velocity.properties の
parse_directive.maxdepth 行は、一つのテンプレートから起こることができる最大数の#parse 参照数をカスタマイズするためにユーザーを許します。
（注：
parse_directive.maxdepth プロパティが velocity.properties
ファイルになければ、Velocity がこのデフォルトを 10 にセットします。）、
テンプレート dofoo.vm が以下の行を含むならば、
例えば、再帰は許されます：
それは、以下の VTL の内容のテンプレート parsefoo.vm を参照します。
「Count down.」が表示された後、8 からカウントダウンして、
Velocity は parsefoo.vm を通してパスします。
カウントが 0 に達するとき、それは「All done with parsefoo.vm!」メッセージを表示します。
この時点で、Velocity はdofoo.vm に戻って、
「All done with dofoo.vm!」メッセージを出力します。
#stop スクリプト要素は、テンプレート・エンジンの実行を止めて、 戻るためにテンプレート・デザイナーを許します。 これは、デバックするときに役立ちます。
#macro スクリプト要素は、VTL テンプレートの繰り返された部分を定義するためにテンプレート・デザイナーを許します。 Velocimacros は、両方とも単純で複雑な広範囲にわたるシナリオに、非常に役立ちます。 この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 テンプレートで inline で定義ができますが、 同じ Web サイトで他の Velocity テンプレートには利用できません。 それが全てのテンプレートによって共有されることができるようなものは明らかにする Velocimacro を定義することは、利します： それは、作業を保存して、エラーの可能性を減らし、多数のテンプレートの上で Velocimacro を再定義する必要を減らして、複数のテンプレートが利用できるマクロに、それに一つの変更点を保証します。
Velocimacro Properties
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 が標準テンプレートで定義されることができるかどうか決定します。
デフォルト（true）は、テンプレートで Velocimacro を定義するためにテンプレート・デザイナーを許します。
velocimacro.permissions.allow.inline.local.scope
−
このプロパティは、true もしはく false で、デフォルトは false で、
Velocimacro 定義された inline がテンプレートを定義することだけに「見えるか」どうか制御します。
言い換えると、正しく調整するこのプロパティ・セットで、テンプレートはテンプレートを定義することによってだけ有用である inline VM を定義することができます。
あなたは装飾的な VM トリックのためにこれを使うことができます−グローバルな VM がグローバルな別の VM を呼ぶならば、inline 範囲で、テンプレートはそのテンプレートによって呼ばれるとき、最初の 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 へのステートフルなオブジェクト（例えばテーブル列に色をつけるために繰り返しシーケンスで色を生成するオブジェクト）を渡すようなことをすることができます。
あなたがこの機能を回避する必要があるならば、あなたは常に新しいリファレンスとしてのメソッドからの値を得て、それを渡すことができます：
現在、それらがテンプレートで最初に使われる前に、Velocimacro は定義されていなければなりません。 これは、あなたの #macro() 宣言を Velocimacros を使う前に行なう必要があることを意味します。
これは、インライン #macro() 指令を含んでいるテンプレートを #parse()
するときに覚えておくことは重要です。
というのも、実行時に #parse() が発生し、パーサーで起こるからはテンプレートでの VM -見ている要素がパース時の VM であるかどうか決めます。そして、VM 宣言の集合が動くことにはならならない #parse() が予期されます。
これに打ち勝つために、単に Velocity に起動時にあなたの VM をロードさせるために
velocimacro.library 機能を使ってください。
VTL 指令は、ある意味で有効な VTL リファレンスに類似したバックスラッシュ文字（「\」）でエスケープすることができます。
一つの指令（ステートメントのような if-else-end で）において、 複数のスクリプト要素を含む VTL 指令をエスケープするとき、特別な心配はとられるはずです。 典型的な VTL if 文は、ここにあります：
$jazzが true ならば、出力は
$jazzが false ならば、出力はありません。 スクリプト要素をエスケープすると、出力を変えます。 以下の場合を考えてください：
$jazzが ture か false かどうかに関係なく、 出力は、
となるでしょう。 実際、全てのスクリプト要素がエスケープされるので、$jazz の真偽は決してチェックされません。 バックスラッシュは合法的にエスケープするスクリプト要素に先行すると思ってください：
この場合、$jazzが true ならば、出力は
です。 $jazzが false ならば、出力はありません。
これを理解するためには、#if( arg ) が
改行(return) で終了しているときに、出力からの改行が除外されることに注意してください。
そのため、#if() ブロックのボディに続く最初の '\'は、
その前の #if() を '\\' からレンダリングされます。
最後の \ は、異なる行にあるので、テキストは、
'Ganelin' の後に改行がきて、そして
#end の前にある最後の \\ は、ブロックのボディの一部となります。
スクリプト要素が適切にエスケープされていなけば、分岐が開始することに注意すること。
ここでは、#if はエスケープされますが、#end が残っています。 end が多すぎるので、解析エラーを引き起こすことになります。
このユーザー・ガイドの中の VTL が改行と空白（下で示されるVTL）で多くの場合表示されるけれども
改行や空白が無関係というのを完全に図示するために、以下の断片は有効で等しいというのが、 Geir Magnusson Jr. によって Velocity のユーザー・メーリングリストに送られました：
Velocity の振る舞いは、余分な空白を飲み尽くすことです。 前の指令は、このように書くことができます：
または
どちらの場合も出力は同じです。
Velocity は、set 指示子でテンプレートで使うことができる少数の 組み込み演算機能を持ちます。 以下の式は、それぞれ加算、減算、乗算、除算の例です：
除算が実行されるとき、結果は整数となります。 どんな余りも、余り（%）オペランドを使うことによって得ることができます。
整数だけ（...-2、-1、0、1、2...）許されます Velocity でいつの実行している数学的な式; 非整数が使われるとき、それはログに記録されます、そして、null は出力として返されることになります。
Velocity は、ゼロ除算を扱うことの組み込まれた方法を持ちます。 下記の例では：
リファレンス $uhoh は、ゼロによって割られる5の値を割り当てられます。 Velocity がこのテンプレートを提出するとき、出力があることになります：
デザイナーは set が生成する文字列に注意すべきです。 そして、それは範囲演算子によって使われる整数に変換されなければなりません。 この例は、そのような変換を示します：
この結果 17 なります。
範囲演算子は、#set と #foreach ステートメントと一緒に使うことができます。 範囲演算子は以下に説明する整数を含んでいるオブジェクト配列を生成に役立ちます：
n と m には、生成する整数が必要です。 m が、n より大きいか、より小さいかは重要ではありません; より小さい場合には、範囲は単にカウントダウンします。 下記に範囲オペレーターの利用を示している例があります：
以下の出力を生成します:
#set と #foreach 指令とともに使われるとき、 4番目の例で示されるように範囲オペレーターが配列を生成するだけである ことに注意。
Web ページ・デザイナーは、標準サイズのテーブルを作成することに関心がありますが、 テーブルを埋めるほどの充分なデータを用意できない場合には、範囲オペレータが 役に立ちます。
リファレンスは! 文字と、\ エスケープ文字によって封じられた ! 文字でリファレンスが取り扱われる特別な方法。
レンダリング結果はこうなります
これを通常エスケープと比較してください、 ここで、\ は $ に先行します：
これは次のようにレンダリングされます
このセクションでは、Velocimacro に関連するミニ-FAQ のトピックスです。 このセクションでは、つねに変更されるでしょう、そのために最新の情報は 常に確認してください。
注意: この章では、「Velocimacro」は、「VM」と省略します。
他の VM の引数として VM を直接渡したり指示できますか?
例 : #center( #bold("hello") )
いいえ。指示は、指示の有効な引数ではありません。 一般的な目的としてVMは、指示です。
しかし...、それを行ないたいです。ひとつの簡単な解決策は、 ダブルクォート(")でその内容をレンダリングするという利点です。 そのためには、このようにします。
省略して...
注意: 例の文字は、VM では内部は引数として評価され呼び出し時ではありません。 言い換えれば、この VM に渡される引数は、 言い換えると、VM への引数は、その全部でにおいてパスされて、 それがパスされた VM の範囲内で評価されます。 これは、このようにすることができます。
ここで出力は
なぜならば、"#inner($bar)" の評価は、#outer() の内部で発生するためで、 そのため $bar 変数は #outer() 内部でセットされてその値が使われます。
これは、意図的にガードされている機能です−引数は VM に「名前」がパスされます、 あなたが VM ものを手渡すことができるように、 例えばステートフルなリファレンスが好きにしてください
そして rowColor() が繰り返し呼ばれ、1回行なわれます。これを禁止するには、 VM の外側のメソッドを呼び出し、VM に値を渡してください。
現在、Velocimacro は、テンプレートで使うのに先立って定義しなければなりません。 この意味は、#macro() 指示は、Velocimacro を使う前に来る必要があります。
もし #parse() をテンプレートに含まれるインライン #macro() 指示で
行なうとするときには、これは、とくに覚えておく必要がある重要事項です。
なぜならば、#parse() が実行時に起こるのは、パーサーが
テンプレートにある VM が探す要素が VM がパース時にに決定するので
#parse() 実行は、VM 宣言の組が仮定されないのです。
これを回避するために、単に velocimacro.library
機能を使用して、あなたの VM の開始時に Velocity をロードします。
開発時に使用するためのプロパティで、製品用ではありません。
velocimacro.library.autoreload
デフォルトは、 false です。 true にセットするには、下記のプロパティと一緒に使います。
<type>.resource.loader.cache = false
(ここで、 <type> は、'file' のようなあなたが使用するリソースローダーの名前です) そうすると Velocity エンジンは、自動的にあなたの Velocimacro ライブラリファイルが生成されたときに変更をリロードしようとします。 つまり、サーブレットエンジン(またはアプリケーション)を dump したり なにか Velocimacro リソロードするための特別なトリックは必要ありません。
簡単なプロパティ設定はこのようになります。
製品では使わないでください。
あなたがこのマニュアルにおけるミスを見つけたり、Velocity ユーザー・ガイドと関係する他のフィードバックは Velocity ユーザメーリングリスト に電子メールを送ってください。 ありがとう！