#macroスクリプト要素は、VTLテンプレートの繰り返された部分を定義するためにテンプレート・デザイナーを許します。
Velocimacrosは、両方とも単純で複雑な広範囲にわたるシナリオに、非常に役立ちます。
このVelocimacro（キーストロークを少なくして、印刷上のエラーを最小にする唯一の目的のためにつくられる）は、Velocimacrosの概念の紹介を提供します。
 |
|
|
|
#macro( d )
<tr><td></td></tr>
#end
|
|
|
|
|
この例では定義されているVelocimacroはdです、そして、それは指示的な他のどのVTLにも類似している方法において呼ばれることができます：
このテンプレートが呼ばれるとき、Velocityは#d()を一つの、空のデータ・セルを含んでいる列と置換します。
Velocimacroは引数（ゼロ引数さえ最初の例がオプションであることを中で証明したので）はどんな数でもとることができますが、Velocimacroが呼び出されるとき、それはそれが定義された同じ数の引数で呼ばれなければなりません。
ものが上記を定義したより、多くのVelocimacrosは、含みます。
2つの引数として、色と配列をとるVelocimacroがここにあります。
|
|
|
|
#macro( tablerows $color $somelist )
#foreach( $something in $somelist )
<tr><td bgcolor=$color>$something</td></tr>
#end
#end
|
|
|
|
|
この例（tablerows）で定義されているVelocimacroは、2つの引数をとります。
最初の引数は、$colorとなり、2番目の引数は、$somelistとなります。
VTLテンプレートに入れられることができる何でも、Velocimacroのbodyに入ることができます。
tablerows Velocimacroは、foreachステートメントです。
2つの#endステートメントが、#tablerows Velocimacroの定義にあります;
第一は、#foreachに属しています二番目の end はVelocimacro定義のものです。
|
|
|
|
#set( $greatlakes = ["Superior","Michigan","Huron","Erie","Ontario"] )
#set( $color = "blue" )
<table>
#tablerows( $color $greatlakes )
</table>
|
|
|
|
|
$greatlakesが$somelistに代わることに注意してください。
#tablerows Velocimacroがこの状況において呼ばれるとき、以下の出力が生成されます。
|
|
|
|
<table>
<tr><td bgcolor="blue">Superior</td></tr>
<tr><td bgcolor="blue">Michigan</td></tr>
<tr><td bgcolor="blue">Huron</td></tr>
<tr><td bgcolor="blue">Erie</td></tr>
<tr><td bgcolor="blue">Ontario</td></tr>
</table>
|
|
|
|
|
VelocimacrosはVelocityテンプレートでinlineでの定義ができますが、
同じWebサイトで他のVelocityテンプレートに利用できないことを意味します。
それが全てのテンプレートによって共有されることができるようなものは明らかにするVelocimacroを定義することは、利します：
それは、作業を保存して、エラーのチャンスを減らして、多数のテンプレートの上でVelocimacroを再定義する必要を減らして、複数のテンプレートが利用できるマクロに、それに一つの変更点を保証します。
Velocimacro Properties
velocity.propertiesファイルの中のいくつかの行は、Velocimacrosの柔軟な実装のために許します：
velocimacro.library
−
全てのVelocimacroテンプレート・ライブラリのコンマで区切られたリスト。
デフォルトで、Velocityは一つのライブラリを捜します：
VM_global_lib.vm
リストの中の全てのテンプレート・ライブラリは、テンプレートパスで見つけられなければならない。
velocimacro.permissions.allow.inline
−
このプロパティ（それは trueまたはfalseの値）は、
Velocimacrosが標準テンプレートで定義されることができるかどうか決定します。
デフォルト（true）は、テンプレートでVelocimacrosを定義するためにテンプレート・デザイナーを許します。
velocimacro.permissions.allow.inline
−
このプロパティ(trueまたはfalse)は、Velocimacrosが標準テンプレートで定義されることができるかどうか決定します。
デフォルト（true）は、テンプレートでVelocimacrosを定義するためにテンプレート・デザイナーを許します。
velocimacro.permissions.allow.inline.local.scope
−
このプロパティは、true もしはく false で、デフォルトは falseで、
Velocimacros定義されたinlineがテンプレートを定義することだけに『見えるか』どうか制御します。
言い換えると、正しく調整するこのプロパティ・セットで、テンプレートはテンプレートを定義することによってだけ有用であるinline VMsを定義することができます。
あなたは装飾的なVMトリックのためにこれを使うことができます−グローバルなVMがグローバルな別のVMを呼ぶならば、inline範囲で、テンプレートはそのテンプレートによって呼ばれるとき、最初のVMによって呼ばれることになる第二のVMのプライベート実装を定義することができます。
全ての他のテンプレートは、影響ありません。
velocimacro.context.localscope
−
このプロパティはは、true または false が設定可能で、デフォルトは falseです。
trueのとき、Velocimacroの範囲内の#set()を経たコンテキストへのどんな修正でもVelocimacroに『ローカルである』と思われて、永久にコンテキストに影響を及ぼしません。
ここで、#tablerows($color $list) Velocimacroが
Velocimacrosテンプレートライブラリで定義てあり、このマクロはどの
標準テンプレートも使うこともできます。
それは、いつでもどんな目的でも使うことが出来ます。
テンプレートのmushroom.vmが全てのもの菌類のテンプレートで
提供されているとき、#tablerows Velocimacroは、
典型的なキノコの一部をリストするために呼び出すことができます：
|
|
|
|
#set( $parts = ["volva","stipe","annulus","gills","pileus"] )
#set( $cellbgcol = "#CC00FF" )
<table>
#tablerows( $cellbgcol $parts )
</table>
|
|
|
|
|
mushroom.vmの要求を満たすとき、Velocityは#tablerows Velocimacroをテンプレートライブラリ（velocity.propertiesファイルにおいて定義される）で見つけて、以下の出力を生成します：
|
|
|
|
<table>
<tr><td bgcolor="#CC00FF">volva</td></tr>
<tr><td bgcolor="#CC00FF">stipe</td></tr>
<tr><td bgcolor="#CC00FF">annulus</td></tr>
<tr><td bgcolor="#CC00FF">gills</td></tr>
<tr><td bgcolor="#CC00FF">pileus</td></tr>
</table>
|
|
|
|
|
Velocimacro Arguments
Velocimacros は、以下のVTL要素はどれでも引数として取ることができます。
-
リファレンス : すべて '$'で開始する
-
文字列リテラル : "$foo" や 'hello'のようなもの
-
数値リテラル : 1, 2 など
-
整数範囲 : [ 1..2] や [$foo .. $bar]
-
オブジェクト配列 : [ "a", "b", "c"]
-
boolean 値 true
-
boolean 値 false
Velocimacrosに対する引数としてリファレンスを渡すとき、に注目してください、リファレンスは『名前が』渡されます。
これは、彼らの値がVelocimacroの中に各使用で『生成される』ことを意味します。
この機能は、メソッド呼び出しによるリファレンスを渡して、メソッドを各使用で呼んでおくためにあなたを許します。
例えば、以下に示すようにVelocimacroを呼び出すと
|
|
|
|
#macro( callme $a )
$a $a $a
#end
#callme( $foo.bar() )
|
|
|
|
|
結果として、リファレンス$fooのメソッドbar()は3回呼び出されます。
一見したところでは、この機能は驚くべきように見えます、
しかし、あなたがVelocimacrosの後に最初の動機づけを考慮に入れるとき ― 一般に使われたVTLの
カット&ペーストの重複を除去するために ― それは意味をなします。
それは、Velocimacroへのステートフルなオブジェクト（例えばテーブル列に色をつけるために繰り返しシーケンスで色を生成するオブジェクト）を渡すようなことをすることができます。
あなたがこの機能を回避する必要があるならば、あなたは常に新しいリファレンスとしてのメソッドからの値を得て、それを渡すことができます：
|
|
|
|
#set( $myval = $foo.bar() )
#callme( $myval )
|
|
|
|
|
Velocimacro Trivia
現在、それらがテンプレートで最初に使われる前に、Velocimacrosは定義されなければなりません。
これは、あなたの#macro()宣言がVelocimacrosを使う前にやって来るなければらならないことを意味します。
これは、インライン #macro() 指令を含んでいるテンプレートを #parse() するときに
覚えておくことは重要です。
というのも、実行時に #parse() が発生し、パーサーで起こるからはテンプレートでのVM-見ている要素がパース時のVMであるかどうか決めます。そして、VM宣言の集合が動くことにはならならない#parse()-ingが予期されます。
これに打ち勝つために、単にVelocityに起動時にあなたのVMをロードさせるためにvelocimacro.library機能を使ってください。
