The Velocity User Guide is intended to help page designers and content providers get acquainted with Velocity and the syntax of its simple yet powerful scripting language, the Velocity Template Language (VTL). Many of the examples in this guide deal with using Velocity to embed dynamic content in web sites, but all VTL examples are equally applicable to other pages and templates.
Velocity ユーザガイドは、ページデザイナやコンテンツ・プロパイダに Velocity と、 Velocity の単純ながらも強力なスクリプト言語である Velocity テンプレート言語 (VTL:Velocity Template Language) の構文を理解していただくことを目的としています。 このガイドで出てくる例の多くは、Web サイトで動的に内容を埋め込むための Velocity の使い方を扱っていますが、VTL の例はすべて、 その他のページやテンプレートにも同様に適用できます。
Thanks for choosing Velocity!
Velocity を選んでいただきありがとうございます。
Velocity is a Java-based template engine. It permits web page designers to reference methods defined in Java code. Web designers can work in parallel with Java programmers to develop web sites according to the Model-View-Controller (MVC) model, meaning that web page designers can focus solely on creating a well-designed site, and programmers can focus solely on writing top-notch code. Velocity separates Java code from the web pages, making the web site more maintainable over the long run and providing a viable alternative to Java Server Pages (JSPs) or PHP.
Velocity は、Java ベースのテンプレートエンジンです。 Velocityを使うと、Web ページデザイナが Java コードで定義されたメソッドを参照できます。Model-View-Controller(MVC) モデルに基づく Web サイト開発で、 Java プログラマと Web デザイナが並行して作業できます。つまり、 Web ページデザイナは素晴らしいデザインのサイトをつくることだけに集中し、 プログラマは最高のコードを書くことだけに集中できるということです。 Velocity は、Java コードを Web ページから切り離し、長い目で見ればより保守しやすい Web サイトを実現し、 Java Server Pages(JSP) や PHP の実現可能な代替案を提供します。
Velocity can be used to generate web pages, SQL, PostScript and other output from templates. It can be used either as a standalone utility for generating source code and reports, or as an integrated component of other systems. When complete, Velocity will provide template services for the Turbine web application framework. Velocity+Turbine will provide a template service that will allow web applications to be developed according to a true MVC model.
Velocity は Web ページや SQL、PostScript といった出力をテンプレートから生成するのに 使えます。ソースコードや帳票を生成する単体のユーティリティとしても使えますし、 他のシステムに統合されるコンポーネントとしても使えます。 Velocityは、Turbine Web アプリケーションフレームワークでテンプレートサービスを提供します。 Velocity と Turbine の組み合わせで、真の MVC モデルにしたがって Web アプリケーションを開発できるテンプレートサービスを提供します。
Suppose you are a page designer for an online store that specializes in selling mud. Let's call it "The Online Mud Store". Business is thriving. Customers place orders for various types and quantities of mud. They login to your site using their username and password, which allows them to view their orders and buy more mud. Right now, Terracotta Mud is on sale, which is very popular. A minority of your customers regularly buys Bright Red Mud, which is also on sale, though not as popular and usually relegated to the margin of your web page. Information about each customer is tracked in your database, so one day the question arises, Why not use Velocity to target special deals on mud to the customers who are most interested in those types of mud?
あなたが陶土を専門に扱うオンラインストアのページデザイナであるとしましょう。 オンラインストアの名前は「Online Mud Store」としましょう。 商売は繁盛しています。顧客はいろいろな種類や量の商品を発注します。 サイトにはユーザー名とパスワードを使用してログインし、 注文内容を確認したり、さらに商品を購入したりできます。 現在、テラコッタ土 [訳注：素焼き用の陶土] はセール中で、とても人気があります。 赤土もセール中ですが、あまり人気が無く、少数の顧客が定期的に買うぐらいで、 いつもは Web ページの片隅に追いやられています。 各顧客に関する情報 [購買履歴など] はデータベースに記録されます。 そんなある日、こんな疑問が湧きます。「特別セールを行う時に、 セール対象の商品に最も興味を持っている顧客をターゲットとするのに Velocity を使うのはどうだろう？」
Velocity makes it easy to customize web pages to your online visitors. As a web site designer at The Mud Room, you want to make the web page that the customer will see after logging into your site.
Velocity なら、オンライン訪問者ごとに Web ページを簡単にカスタマイズできます。 「The Mud Room」の Web サイトデザイナであるあなたは、顧客がサイトログイン後に見る Web ページを作ろうと思っています。
You meet with software engineers at your company, and everyone has agreed that $customer will hold information pertaining to the customer currently logged in, that $mudsOnSpecial will be all the types mud on sale at present. The $flogger object contains methods that help with promotion. For the task at hand, let's concern ourselves only with these three references. Remember, you don't need to worry about how the software engineers extract the necessary information from the database, you just need to know that it works. This lets you get on with your job, and lets the software engineers get on with theirs.
会社でソフトウェアエンジニアと打ち合わせをした結果、 $customer に現在ログインしている顧客に関する情報を保持し、 $mudsOnSpecial で現在セール中の全ての種類の商品の情報を保持することに なりました。 $flogger オブジェクトには、宣伝に役立つメソッドが入っています。 当面の作業では、これらの3つのリファレンスにだけ注目しましょう。 ソフトウェアエンジニアがどのように必要な情報をデータベースから抽出するかについては 気にしなくてよく、 その情報が使えることだけ知っていればよいということ注目してください。 つまり、あなたもソフトウェアエンジニアも、自分の仕事にだけ注力できるということです。
You could embed the following VTL statement in the web page:
以下の VTL 文を Web ページに埋め込みます。
| $flogger.getPromo( $mud ) |
The exact details of the foreach statement will be described in greater depth shortly; what's important is the impact this short script can have on your web site. When a customer with a penchant for Bright Red Mud logs in, and Bright Red Mud is on sale, that is what this customer will see, prominently displayed. If another customer with a long history of Terracotta Mud purchases logs in, the notice of a Terracotta Mud sale will be front and center. The flexibility of Velocity is enormous and limited only by your creativity.
foreach 文の詳細は後段で説明しますが、 ここで重要なのは、この短いスクリプトがあなたの Web サイトにあたえるインパクトです。 赤土を好む顧客がログインしたとき、赤土がセール中であれば、 この顧客向けに、赤土がセール中であることを特に目につくように表示します。 テラコッタ土購入歴の長い顧客がログインしたときには、 テラコッタ土のセールのお知らせを一番目立つ場所に表示します。 Velocityの柔軟性は極めて高く、あとはあなたの創造力次第です。
Documented in the VTL Reference are the many other Velocity elements, which collectively give you the power and flexibility you need to make your web site a web presence. As you get more familiar with these elements, you will begin to unleash the power of Velocity.
VTLリファレンスでは、その他にもたくさんの Velocity 要素が記述されており、 これらを組み合わせることで、 Web サイトの存在感 を高めるのに必要なパワーと柔軟性が得られます。 これらの要素に詳しくなれば、Velocity のパワーをさらに発揮できるでしょう。
The Velocity Template Language (VTL) is meant to provide the easiest, simplest, and cleanest way to incorporate dynamic content in a web page. Even a web page developer with little or no programming experience should soon be capable of using VTL to incorporate dynamic content in a web site.
Velocity テンプレート言語(VTL:Velocity Template Language) は、 Web ページに動的な内容を取り込むのに最も簡単、単純で、 無駄のない方法となることを目標としています。 ほとんどプログラミング経験のない Web ページ開発者でも、 VTL を使えばすぐに、動的な内容を Web サイトに取り込めるようになるはずです。
VTL uses references to embed dynamic content in a web site, and a variable is one type of reference. Variables are one type of reference that can refer to something defined in the Java code, or it can get its value from a VTL statement in the web page itself. Here is an example of a VTL statement that could be embedded in an HTML document:
VTL では Web サイトにおいて動的な内容を埋め込むのにリファレンス を使いますが、 変数はその一種です。変数とは Java コードで定義したものを参照するリファレンスの一種で、 Web ページ内の VTL 文 から変数の値を取得できます。 HTML 文書に埋め込むことができる VTL 文の例を次に示します：
This VTL statement, like all VTL statements, begins with the # character and contains a directive: set. When an online visitor requests your web page, the Velocity Templating Engine will search through your web page to find all # characters, then determine which mark the beginning of VTL statements, and which of the # characters that have nothing to do with VTL.
全ての VTL 文がそうであるように、この VTL 文は 「#」 から始まって、set という指示子を含みます。 Webページが要求されたとき、Velocity テンプレートエンジンは Web ページを走査して全ての 「#」を見つけ、 それぞれについて、どれが VTL 文の始まりでどれが VTL と無関係かを判定します。
The # character is followed by a directive, set. The set directive uses an expression (enclosed in brackets) -- an equation that assigns a value to a variable. The variable is listed on the left hand side and its value on the right hand side; the two are separated by an = character.
「#」の後に指示子(set)が続いています。 set 指示子は、(括弧で囲まれた)式 ─ 変数 に値 を割り当てる 等式 ─ を使います。変数は左側で値は右側になります。この2つは、「=」で区切られます。
In the example above, the variable is $a and the value is Velocity. This variable, like all references, begins with the $ character. Values are always enclosed in quotes; with Velocity there is no confusion about data types, as only strings (text-based information) may be passed to variables.
上の例では、変数は $a で値は Velocity です。 全てのリファレンスがそうであるように、この変数は 「$」で始まります。 値は常に引用符で囲まれます。Velocity では、文字列 (テキストに基づく情報) だけが変数に渡されるので、データ型に対する混乱は発生しません。
The following rule of thumb may be useful to better understand how Velocity works: References begin with $ and are used to get something. Directives begin with # and are used to do something.
以下の簡単なルールが、Velocity がどのように動作するかをさらに理解するのに役立つでしょう。 リファレンスは、「$」 から始まって、何かを取得するのに使います。 指示子は、「#」 から始まって、何かを行うのに使います。
In the example above, #set is used to assign a value to a variable. The variable, $a, can then be used in the template to output "Velocity".
上の例では、#set は、値を変数に割り当てるのに使われます。 変数 ($a) は、「Velocity」を出力するのにテンプレートで使うことができます。
Once a value has been assigned to a variable, you can reference the variable anywhere in your HTML document. In the following example, a value is assigned to $foo and later referenced.
一旦変数に値が割り当てられたら、HTML 文書のどこででも変数を参照できます。 下記の例では、値は $foo に割り当てられて後で参照されます。
The result is a web page that prints "Hello Velocity World!".
結果として Web ページは、"Hello Velocity World!"を表示します。
To make statements containing VTL directives more readable, we encourage you to start each VTL statement on a new line, although you are not required to do so. The set directive will be revisited in greater detail later on.
VTL 指示子を含んだ文をより読みやすくするために、個々の VTL 文は、 新しい行から始めることを推奨しますが、必須ではありません。 set 指示子については、後ほど更に詳しく説明します。
Comments allows descriptive text to be included that is not placed into the output of the template engine. Comments are a useful way of reminding yourself and explaining to others what your VTL statements are doing, or any other purpose you find useful. Below is an example of a comment in VTL.
コメントを使うと説明用のテキストを埋め込むことができます。 コメントはテンプレートエンジンの出力に含まれません。 コメントは、VTL 文が何を行なっているかを他人 (や未来の自分自身) に説明するなど、 便利と思われるどんな目的でも使うことができます。 下記は、VTL でのコメントの例です。
A single line comment begins with ## and finishes at the end of the line. If you're going to write a few lines of commentary, there's no need to have numerous single line comments. Multi-line comments, which begin with #* and end with *#, are available to handle this scenario.
一行コメントは、## で始まり行末で終わります。 コメントを複数行書こうとする場合、一行コメントをたくさん並べる必要ありません。こういう場合には、 複数行コメント (#* で始まり *# で終わります) が利用できます。
Here are a few examples to clarify how single line and multi-line comments work:
一行コメントと複数行コメントの動作を分かりやすく説明するいくつかの例を以下に示します。
There is a third type of comment, the VTL comment block, which may be used to store such information as the document author and versioning information:
コメントには第3の形式 (VTLコメントブロック) があります。 文書の作者やバージョン情報などを格納するために使われるかもしれません。
There are three types of references in the VTL: variables, properties and methods. As a designer using the VTL, you and your engineers must come to an agreement on the specific names of references so you can use them correctly in your templates.
VTL には、変数/プロパティ/メソッドという3種類のリファレンスがあります。 VTL を使うデザイナがテンプレートでリファレンスを正しく使えるように、 デザイナとエンジニアとの間で、 個々のリファレンスの名前について同意しておかなければなりません。
Everything coming to and from a reference is treated as a String
object. If there is an object that represents $foo (such as
an Integer object), then Velocity will call its
.toString() method to resolve the object into a String.
リファレンスに出入りするものはすべて、文字列オブジェクトとみなされます。
$fooという名前のオブジェクト (例えばIntegerオブジェクト) があるならば、
Velocity はオブジェクトを文字列にするために.toString()メソッドを呼びます。
Variables
The shorthand notation of a variable consists of a leading "$"
character followed by a VTL Identifier. A VTL Identifier
must start with an alphabetic character (a .. z or A .. Z). The rest
of the characters are limited to the following types of characters:
変数
変数の簡略表記は、「$」とそれに続く VTL 識別子 から構成されます。
VTL 識別子は、英字から始めなければなりません (a・・・zまたはA・・・Z)。
先頭以外の文字についても、以下の種類に限定されます：
Here are some examples of valid variable references in the VTL:
VTL で有効な変数リファレンスの例をいくつか示します。
When VTL references a variable, such as $foo, the variable can get its value from either a set directive in the template, or from the Java code. For example, if the Java variable $foo has the value bar at the time the template is requested, bar replaces all instances of $foo on the web page. Alternatively, if I include the statement
VTL が ($foo のような) 変数を参照する場合、 変数の値を、テンプレートの set 指示子、 または Java のコードから取得できます。 例えば、テンプレートが要求された時に Java 変数 $foo が値 bar を持っていれば、Web ページ上で $foo の全てのインスタンスが bar で置換できます。言い換えると、以下の文を入れると、
The output will be the same for all instances of $foo that follow this directive.
この指示子以降の $foo の全てのインスタンスについて出力は同じになります。
Properties
The second flavor of VTL references are properties, and properties
have a distinctive format. The shorthand notation consists of a
leading $ character followed a VTL Identifier, followed by
a dot character (".") and another VTL Identifier. These are examples
of valid property references in the VTL:
プロパティ
VTL リファレンスの第二の形式はプロパティで、特徴的なフォーマットを持っています。
簡略表記は、「$」とそれに続く VTL 識別子、それにドット「.」を挟んで続く別の
VTL 識別子から成ります。
VTL での有効なプロパティリファレンスの例を示します：
Take the first example, $customer.Address. It can have two meanings. It can mean, Look in the hashtable identified as customer and return the value associated with the key Address. But $customer.Address can also be referring to a method (references that refer to methods will be discussed in the next section); $customer.Address could be an abbreviated way of writing $customer.getAddress(). When your page is requested, Velocity will determine which of these two possibilities makes sense, and then return the appropriate value.
最初の例 ($customer.Address) の場合は、2つの意味が考えられます。 一つは、customer で識別される hashtable を見て、 キー Address と関連づけられる値を返すという意味です。 しかし、$customer.Address はメソッドを参照しているのかも知れないのです。 (メソッドを参照するリファレンスは、次のセクションで説明します)。 $customer.Address は、$customer.getAddress() の省略表記でもあるのです。 ページが要求されたとき、Velocity はこれらの2つの可能性のうち どちらが意味をなすかを判定して、適切な値を返します
Methods
A method is defined in the Java code and is capable of doing
something useful, like running a calculation or arriving at a
decision. Methods are references that consist of a leading "$"
character followed a VTL Identifier, followed by a VTL Method
Body. A VTL Method Body consists of a VTL Identifier followed
by an left parenthesis character ("("), followed by an optional
parameter list, followed by right parenthesis character (")"). These
are examples of valid method references in the VTL:
メソッド
メソッドは Java コードにおいて定義されるもので、何か役に立つこと
(計算や判定の実行など) を行うことができます。
メソッドは「$」と、それに続く VTL 識別子と、それに続く
VTL メソッドボディ (Method Body) から構成されるリファレンスです。
VTL メソッドボディは、VTL 識別子と、それに続く左括弧("(")、
パラメータリスト (オプション)、それに右括弧(")")から構成されます。
VTL で有効なメソッドリファレンスの例を示します。
The first two examples -- $customer.getAddress() and $purchase.getTotal() -- may look similar to those used in the Properties section above, $customer.Address and $purchase.Total. If you guessed that these examples must be related some in some fashion, you are correct!
最初の2つの例 ($customer.getAddress() と $purchase.getTotal()) は、 上のプロパティのセクションで使われた例 ($customer.Addressと$purchase.Total) に類似しているように見えるかもしれません。 これらの例は何か関係があるはずだと思ったら、それは正解です！
VTL Properties can be used as a shorthand notation for VTL Methods. The Property $customer.Address has the exact same effect as using the Method $customer.getAddress(). It is generally preferable to use a Property when available. The main difference between Properties and Methods is that you can specify a parameter list to a Method.
VTL プロパティは、VTL メソッドの簡略表記として使えます。 プロパティ $customer.Address は、 メソッド $customer.getAddress() を使うのと完全に同じ効果があります。 一般に、利用可能ならプロパティを使う方が望ましいです。 プロパティとメソッドの主な違いは、 メソッドにはパラメータリストを指定できるということです。
The shorthand notation can be used for the following Methods
簡略表記は、以下のメソッドで使うことができます。
We might expect these methods to return the names of planets belonging to the sun, feed our earthworm, or get a photograph from an album. Only the long notation works for the following Methods.
こうしたメソッドは、太陽系の惑星の名前を返すとか ミミズに餌をやるとか、アルバムから写真を取り出すといったことが想定されるでしょう。 以下のメソッドは、長い表記だけが動作します。
Formal Reference Notation
Shorthand notation for references was used for the examples listed
above, but there is also a formal notation for references, which is
demonstrated below:
正式リファレンス表記
上で一覧として挙げた例では、リファレンスの簡略表記が使われました。
しかし、リファレンスのための正式表記もあります。以下に例を示します。
In almost all cases you will use the shorthand notation for references, but in some cases the formal notation is required for correct processing.
ほとんどすべての場合、リファレンスには簡略表記を使用することになりますが、 正しく処理するために正式表記が必要となる場合があります。
Suppose you were constructing a sentence on the fly where $vice was to be used as the base word in the noun of a sentence. The goal is to allow someone to choose the base word and produce one of the two following results: "Jack is a pyromaniac." or "Jack is a kleptomaniac.". Using the shorthand notation would be inadequate for this task. Consider the following example:
例えば、動的に文を構築するのに、文で使われる名詞のベースとなる単語として$vice を使うとしましょう。誰かにベースとなる単語を選択させて、 「Jack is pyromaniac.」あるいは「Jack is kleptomaniac.」という結果を生成します。 こういう場合、簡略表記を使用するとまずいのです。 以下の例を考えてみてください。
There is ambiguity here, and Velocity assumes that $vicemaniac, not $vice, is the Identifier that you mean to use. Finding no value for $vicemaniac, it will return $vicemaniac. Using formal notation can resolve this problem.
この表現は曖昧で、Velocity は識別子として、あなたが使いたい$viceではなく $vicemaniac を認識します。$vicemaniac の値は見つからないので $vicemaniac をそのまま返すことになります。 正式表記を使用することで、この問題を解決できます。
Now Velocity knows that $vice, not $vicemaniac, is the reference. Formal notation is often useful when references are directly adjacent to text in a template.
こうすれば Velocity は、$vicemaniac ではなく $vice がリファレンスであると認識します。 正式表記が役に立つことが多いのは、 このようにリファレンスがテンプレート中でテキストと隣接している時です。
Quiet Reference Notation
When Velocity encounters an undefined reference, its normal behavior
is to output the image of the reference. For example, suppose the
following reference appears as part of a VTL template.
沈黙リファレンス表記
Velocity が未定義のリファレンスに遭遇したとき、
通常の挙動として、リファレンスの記述をそのまま出力します。
例えば、以下のリファレンスが VTL テンプレートの一部に出てきたとしましょう。
When the form initially loads, the variable reference $email has no value, but you prefer a blank text field to one with a value of "$email". Using the quiet reference notation circumvents Velocity's normal behavior; instead of using $email in the VTL you would use $!email. So the above example would look like the following:
最初にフォームがロードされるとき、変数のリファレンス $email には値がありませんが、 テキストフィールドに「$email」という値が入っているより ブランクになっている方がよいでしょう。 リファレンスの沈黙表記を使用することで、Velocity の通常の挙動を回避します。 具体的には VTL で $email を使う代わりに、 $!email を使います。 したがって、上記の例は以下のようになります：
Now when the form is initially loaded and $email still has no value, an empty string will be output instead of "$email".
これで、最初にフォームがロードされて $email がまだ値を持たないとき、 「$email」の代わりに空の文字列が出力されます。
Formal and quiet reference notation can be used together, as demonstrated below.
リファレンスを正式表記かつ沈黙表記として使うことも出来ます。 具体的には以下のようにします。
VTL uses special characters, such as $ and #, to do its work, so some added care should be taken where using these characters in your templates. This section deals with escaping the $ character.
VTL は、「$」 や 「#」のように特殊文字を使用するので、 テンプレート内でこれらの文字を使用する場合には注意が必要です。 このセクションでは、「$」をエスケープする方法を説明します。
Currency
There is no problem writing "I bought a 4 lb. sack of potatoes at
the farmer's market for only $2.50!" As mentioned, a VTL identifier
always begins with an upper- or lowercase letter, so $2.50 would not
be mistaken for a reference.
通貨
「私は市場で 4ポンドの袋入りのジャガイモをたった $2.50 で買いました！」
と書くことについては問題はありません。
VTL 識別子は常に大文字または小文字の英字から始まるので、$2.50をリファレンスと間違えることはありません。
Escaping Valid VTL References
Cases may arise where there is the potential for Velocity to get
confused. Escaping special characters is the best way to
handle VTL's special characters in your templates, and this can be
done using the backslash ( \ ) character.
有効なVTLリファレンスをエスケープする
Velocity が混乱する可能性がある場合もあります。
特殊文字のエスケープは、テンプレート内で VTL の特殊文字を扱う最適な方法であり、
バックスラッシュ(\)を使って行えます。
If Velocity encounters a reference in your VTL template to $email, it will search the Context for a corresponding value. Here the output will be foo, because $email is defined. If $email is not defined, the output will be $email.
Velocity が VTL テンプレートで $email リファレンスを検出すると、 対応する値を求めてコンテキストを検索します。 ここでは、$email が定義されているので、出力は foo になります。 $email が定義されていなければ、出力は $email になります。
Suppose that $email is defined (for example, if it has the value foo), and that you want to output $email. There are a few ways of doing this, but the simplest is to use the escape character.
(例えば値が foo である) $email が定義されていて、 $email と出力したい場合を考えてください。 解決方法はいくつかありますが、最も単純なのはエスケープ文字を使うことです。
renders as
これは以下のように処理されます。
Note that the \ character bind to the $ from the left. The bind-from-left rule causes \\\$email to render as \\$email. Compare these examples to those in which $email is not defined.
左から「\」が「$」に結合することに注意してください。 「左から結合する」規則の結果、 \\\$email を処理すると \\$email になります。 上記の例を、下記の$email が定義されない例と比較してみてください。
renders as
これは以下のように処理されます。
Notice Velocity handles references that are defined differently from those that have not been defined. Here is a set directive that gives $foo the value gibbous.
Velocity は、定義されていない場合と定義されていない場合とで、 リファレンスの扱いが異なることに注意してください。 以下の例では、set 指示子で $foo に値 gibbous をセットします。
The output will be: $moon = gibbous -- where $moon is output as a literal because it is undefined and gibbous is output in place of $foo.
出力は$moon = gibbousになります ─ $moon は未定義なのでリテラルとして出力され、 $foo のところには gibbous が出力されるのです。
It is also possible to escape VTL directives; this is described in more detail in the Directives section.
VTL 指示子をエスケープすることも可能です; この詳細については、 指示子 セクションで説明します。
Now that you are familiar with references, you can begin to apply them effectively in your templates. Velocity references take advantage of some Java principles that template designers will find easy to use. For example:
リファレンスに慣れると、テンプレートで効果的にリファレンスを使えるようになります。 Velocity リファレンスでは Java の利点を生かしていますが、 テンプレートデザイナでも使うのは難しくないと思います。例を挙げましょう。
These examples illustrate alternative uses for the same references. Velocity takes advantage of Java's introspection and bean features to resolve the reference names to both objects in the Context as well as the objects methods. It is possible to embed and evaluate references almost anywhere in your template.
これらは、同じリファレンスのいろんな使い方の具体例です。 Velocity は、Java のイントロスペクション機能と Bean 機能を利用して、 コンテキスト内のオブジェクトと、オブジェクトメソッドの両方のリファレンス名を解決します。 テンプレート中のほぼどこにでもリファレンスを埋め込んで、評価することが可能です。
Velocity, which is modelled on the Bean specifications defined by
Sun Microsystems, is case sensitive; however, its developers have
strove to catch and correct user errors wherever possible.
When the method getFoo() is referred to in a template
by $bar.foo, Velocity will first try $getfoo.
If this fails, it will then try $getFoo.
Similarly, when a template refers to $bar.Foo, Velocity
will try $getFoo() first and then try getfoo().
Velocity では、サンマイクロシステムズが策定した Bean 仕様書に元にモデルを作ったので、
大文字と小文字を区別します。しかし、Velocity の開発者は、
ユーザエラーを出来る限り検出して訂正するよう努力しました。
getFoo() メソッドが、テンプレート内で$bar.foo によって
参照されるとき、Velocityはまず $getfoo を試み、それに失敗すると、
$getFoo を試みます。
同じように、テンプレートが $bar.Foo を参照するとき、
Velocity は最初に $getFoo() を試みて、
それから getfoo() を試みます。
Note: References to instance variables in a template are not
resolved. Only references to the attribute equivalents of
JavaBean getter/setter methods are resolved
(i.e. $foo.Name does resolve to the class Foo's
getName() instance method, but not to a public
Name instance variable of Foo).
注意: テンプレート中のインスタンス変数への参照は解決されません。
JavaBean の getter/setter メソッドに対応する属性だけが解決されます。
(つまり、$foo.Name は、
Foo クラスのインスタンスメソッドである getName() としては解決されますが、
Foo のパブリックのインスタンス変数である Name としては解決されません。)
References allow template designers to generate dynamic content for web sites, while directives -- easy to use script elements that can be used to creatively manipulate the output of Java code -- permit web designers to truly take charge of the appearance and content of the web site.
リファレンスを使うと、 テンプレートのデザイナが Web サイト向けに動的に内容を生成できるのに対して、 指示子 (使いやすいスクリプト要素で、Java コードの出力を思い通りに操作するのに使えます) を使うと、 Web デザイナは真の意味で Web サイトの内容と見栄えを管理できるようになります。
The #set directive is used for setting the value of a reference. A value can be assigned to either a variable reference or a property reference, and this occurs in brackets, as demonstrated:
#set 指示子は、リファレンスの値をセットするのに使います。 値は、変数リファレンスかプロパティリファレンスにセットされ、 その際、以下に示すように丸括弧でくくります。
The left hand side (LHS) of the assignment must be a variable reference or a property reference. The right hand side (RHS) can be one of the following types:
左辺(LHS:Left Hand Side)は、変数リファレンスまたはプロパティリファレンスでなければなりません。 右辺(RHS:Right Hand Side)は、以下のタイプのいずれかです：
These examples demonstrate each of the aforementioned types:
以下は、上記タイプの各々の例です：
NOTE: In the last example the elements defined with the [..] operator are accessible using the methods defined in the ArrayList class. So, for example, you could access the first element above using $monkey.Say.get(0).
注意: 最後の例で [..] オペレータで定義された要素は ArrayList クラスで定義されているメソッドを使用してアクセスできます。したがって、 例えば、$monkey.Say.get(0) を使って上記の最初の要素 ("Not") にアクセスできます。
The RHS can also be a simple arithmetic expression:
右辺には単純な計算式を入れることもできます。
If the RHS is a property or method reference that evaluates to null, it will not be assigned to the LHS. It is not possible to remove an existing reference from the context via this mechanism. This can be confusing for newcomers to Velocity. For example:
右辺がnullとして評価されるプロパティやメソッドだった場合、 null値は左辺に代入されません。 null代入で既存のリファレンスをコンテキストから削除することはできません。 これはVelocity初心者には混乱の元となるかもしれません。 例えば、
If $query.criteria("name") returns the string "bill", and $query.criteria("address") returns null, the above VTL will render as the following:
$query.criteria("name") が "bill" という文字列を返し、 $query.criteria("address") は null を返す時、 上のVTLは次のように処理されます：
This tends to confuse newcomers who construct #foreach loops that attempt to #set a reference via a property or method reference, then immediately test that reference with an #if directive. For example:
このため、初心者が#foreach を使って、 プロパティやメソッドリファレンスを別のリファレンスに #set し、 直後にそのリファレンスを#if 指示子でテストする、 というループを構築すると混乱しやすいでしょう。 例えば、
In the above example, it would not be wise to rely on the evaluation of $result to determine if a query was successful. After $result has been #set (added to the context), it cannot be set back to null (removed from the context). The details of the #if and #foreach directives are covered later in this document.
上の例において、クエリが成功したかどうかを判定するのに $result の評価を信頼するのは賢明とはいえません。 $result が #set された(コンテキストに追加された)後、 これを null に戻す(コンテキストから削除される)ことはできないのです。 #if と #foreach の各指示子についてはこの文書で後述します。
One solution to this would be to pre-set $result to false. Then if the $query.criteria() call fails, you can check.
これに対する解決法の一つは、事前に $result を false にセットしておくことです。そうすれば、 $query.criteria() の呼び出しが失敗した場合、チェックすることができます。
Unlike some of the other Velocity directives, the #set directive does not have an #end statement.
他の Velocity 指示子のいくつかとは異なり、#set 指示子には #end 文がありません。
When using the #set directive, string literals that are enclosed in double quote characters will be parsed and rendered, as shown:
#set 指示子を使うとき、二重引用符(「"」)で囲まれた文字列リテラルは、 以下に示すようにパース／処理されます。
The output will be
出力はこうなります
However, when the string literal is enclosed in single quote characters, it will not be parsed:
しかし、文字列リテラルが単一引用符 (「'」) で囲まれている場合には パースされません。
この処理結果は、こうなります
By default, this feature of using single quotes to render unparsed
text is available in Velocity. This default can be changed by
editing velocity.properties such that
stringliterals.interpolate=false.
単一引用符を使ってテキストをパースせずに処理するという機能は、
Velocity ではデフォルトで利用できます。
このデフォルトは、velocity.properties を編集して
stringliterals.interpolate=false
とすることによって変更できます
The #if directive in Velocity allows for text to be included when the web page is generated, on the conditional that the if statement is true. For example:
Velocity の #if 指示子を使えば、if 文の条件が真という条件文で、 Web ページの生成時にテキストを含むようにできます。 例を挙げましょう。
The variable $foo is evaluated to determine whether it is
true, which will happen under one of two circumstances: (i)
$foo is a boolean (true/false) which has a true value, or
(ii) the value is not null. Remember that the Velocity context only
contains Objects, so when we say 'boolean', it will be represented
as a Boolean (the class). This is true even for methods that return
boolean - the introspection infrastructure will return
a Boolean of the same logical value.
変数 $foo が評価されて true かどうか判定されます。
true であるとは以下の2つの状況を指します。
(i) $foo が true の値を持つ boolean (true/false) の場合
(ii) $foo の値が null ではない場合
です。
Velocity のコンテキストはオブジェクトのみを保持することを思い出してください。
「boolean」という場合、それは(クラスである)Booleanを意味します。
これは boolean を返すメソッドに対しても当てはまり、
内部的には同じ論理値の Boolean を返します。
The content between the #if and the #end statements become the output if the evaluation is true. In this case, if $foo is true, the output will be: "Velocity!". Conversely, if $foo has a null value, or if it is a boolean false, the statement evaluates as false, and there is no output.
#if と #end の間の内容は、評価値が true の場合に出力されます。 この場合、$foo が true ならば、出力は「Velocity!」となります。 逆に、$foo が null または、boolean で false ならば、 文の評価は false となり、出力はありません。
An #elseif or #else element can be used with an #if element. Note that the Velocity Templating Engine will stop at the first expression that is found to be true. In the following example, suppose that $foo has a value of 15 and $bar has a value of 6.
#elseifまたは#else要素は #if要素と組で使用できます。 Velocity テンプレートエンジンは、最初に式が true になったところで評価を止めることに注意してください。 下記の例で、$foo が 15 という値を持ち、$bar は 6 という値を持つとします。
In this example, $foo is greater than 10, so the first two comparisons fail. Next $bar is compared to 6, which is true, so the output is Go South.
この例では、$foo は、10 より大きいので最初の 2 つの比較は失敗します。 次に、$bar が、6 と比較され、それが true なので、 出力は Go South となります。
Please note that currently, Velocity's numeric comparisons are constrained to Integers - anything else will evaluate to false. The only exception to this is equality '==', where Velocity requires that the objects on each side of the '==' is of the same class.
注意: 現在、Velocity の数値の比較は Integer のみ行えます ─ それ以外の場合には false と評価します。 これに対する唯一の例外は等号「==」です。その場合、「==」の両辺のオブジェクトは、 同じクラスである必要があります。
Velocity uses the equivalent operator to determine the relationships between variables. Here is a simple example to illustrate how the equivalent operator is used.
Velocity は、変数の関係を決定するために等価演算子を使います。 等価演算子の使い方の単純な例を示します。
Velocity has logical AND, OR and NOT operators as well. For further information, please see the VTL Reference Guide Below are examples demonstrating the use of the logical AND, OR and NOT operators.
Velocity には、この他に AND/OR/NOT という論理演算子があります。 詳細な情報については、 VTL Reference Guide をご覧下さい。 以下は、論理演算子 AND/OR/NOT を使用した例です。
The #if() directive will only evaluate to true if both $foo and $bar are true. If $foo is false, the expression will evaluate to false; $bar will not be evaluated. If $foo is true, the Velocity Templating Engine will then check the value of $bar; if $bar is true, then the entire expression is true and This AND that becomes the output. If $bar is false, then there will be no output as the entire expression is false.
#if() 指示子は、$foo と $bar が共に true かどうか、 評価します。 $foo が false ならば、式全体は false に評価され $bar は、評価されません。 $foo が true ならば、Velocity テンプレートエンジンは、 次に $bar の値をチェックします。 $bar が true ならば、式全体が、true となって これ AND あれ が出力されます。 $bar が false ならば、式全体が false となって 出力されません。
Logical OR operators work the same way, except only one of the references need evaluate to true in order for the entire expression to be considered true. Consider the following example.
論理演算子 OR も同様ですが、式全体が true になるには true と評価されるリファレンス が1つだけあればよいというところだけが違います。 以下の例を考えてみてください。
If $foo is true, the Velocity Templating Engine has no need to look at $bar; whether $bar is true or false, the expression will be true, and This OR That will be output. If $foo is false, however, $bar must be checked. In this case, if $bar is also false, the expression evaluates to false and there is no output. On the other hand, if $bar is true, then the entire expression is true, and the output is This OR That
$foo が true ならば、Velocity テンプレートエンジンは $bar を調べる必要はありません。 $bar が true であるか false であるかどうかに関係なく、 式は true となり、 これ OR あれ が出力されます。 $foo が false ならば、今度は $bar をチェックしなければなりません。 この場合、$bar も false ならば、式は false と評価して、出力はありません。 一方、$bar が true ならば、式全体が true になり、 出力は これ OR あれ となります。
With logical NOT operators, there is only one argument :
論理演算子 NOT では、引数は1つしかありません。
Here, the if $foo is true, then !$foo evaluates to false, and there is no output. If $foo is false, then !$foo evaluates to true and NOT that will be output. Be careful not to confuse this with the quiet reference $!foo which is something altogether different.
ここで、 $foo が true であれば、 !$foo は false と評価され、 出力はありません。 $foo が false であれば、 !$foo は true と評価されて、 NOT あれ が出力されます。 これを 沈黙リファレンスの $!foo と混同しないように注意してください。 全然違うものですから。
The #foreach element allows for looping. For example:
#foreach 要素を使うとループ処理ができます。例えば
This #foreach loop causes the $allProducts list (the object) to be looped over for all of the products (targets) in the list. Each time through the loop, the value from $allProducts is placed into the $product variable.
この #foreach ループによって、$allProducts リスト (オブジェクト) で製品(ターゲット)の全てについてループが行われます。 ループの一回一回で $allProducts からの値が $product 変数にセットされます。
The contents of the $allProducts variable is a Vector, a Hashtable or an Array. The value assigned to the $product variable is a Java Object and can be referenced from a variable as such. For example, if $product was really a Product class in Java, its name could be retrieved by referencing the $product.Name method (ie: $Product.getName()).
$allProducts 変数の内容は、Vector、Hashtable、配列のいずれかです。 $product 変数に割り当てられる値は、Java オブジェクトで、 Java オブジェクトのように変数から参照できます。 たとえば、もし $product が本当に Java の Product クラスならば、 その名前は、$product.Name メソッド (= $Product.getName()) で参照して取り出すことができます。
Lets say that $allProducts is a Hashtable. If you wanted to retrieve the key values for the Hashtable as well as the objects within the Hashtable, you can use code like this:
$allProduct が Hashtable だとしましょう。もし Hashtable から、 キーの値と Hashtable 内のオブジェクトを取り出したい場合には、次のように コードを使用します。
Velocity provides an easy way to get the loop counter so that you can do something like the following:
Velocity ではループカウンタを簡単に取得できるので、 次のようなことができます。
The default name for the loop counter variable reference, which is
specified in the velocity.properties file, is $velocityCount. By
default the counter starts at 1, but this can be set to either 0 or
1 in the velocity.properties file. Here's what the loop
counter properties section of the velocity.properties
file appears:
ループカウンタ変数リファレンスのデフォルト名は、velocity.properties ファイル
に指定されている通り、$velocityCount です。カウンタはデフォルトでは
1 から開始しますが、velocity.properties ファイルで 0 か 1
のどちらかに設定できます。velocity.properties ファイルの
ループカウンタプロパティセクションの内容を以下に示します。
The #include script element allows the template designer to import a local file, which is then inserted into the location where the #include directive is defined. The contents of the file are not rendered through the template engine. For security reasons, the file to be included may only be under TEMPLATE_ROOT.
#include スクリプト要素でローカルファイルをインポートできます。 ファイルは #include 指示子が定義される位置に挿入されます。 ファイルの中身は、テンプレートエンジンによって処理されません。 セキュリティ上の理由から、インクルードされるファイルは、 TEMPLATE_ROOT 以下にあるものだけが許されます。
The file to which the #include directive refers is enclosed in quotes. If more than one file will be included, they should be separated by commas.
#include 指示子が参照するファイルは、引用符で囲まれます。 複数のファイルをインクルードする場合には、それらをコンマで区切ります。
The file being included need not be referenced by name; in fact, it is often preferable to use a variable instead of a filename. This could be useful for targeting output according to criteria determined when the page request is submitted. Here is an example showing both a filename and a variable.
インクルードされるファイルを名前で参照する必要はありません。 実際、多くの場合ファイル名の代わりに変数を使うことが望ましいです。 これは、ページ要求があったときに、事前に決めた基準にしたがって 出力を切り替えるのに役立ちます。 これは、ファイル名と変数両方を使用した例です。
The #parse script element allows the template designer to import a local file that contains VTL. Velocity will parse the VTL and render the template specified.
#parse スクリプト要素で VTL を含むローカルファイルをインポートできます。 Velocity は、VTL を解析し、指定されたテンプレートを処理します。
Like the #include directive, #parse can take a variable rather than a template. Any templates to which #parse refers must be included under TEMPLATE_ROOT. Unlike the #include directive, #parse will only take a single argument.
#include 指示子と同じく、#parse はテンプレートの代わりに変数をとることができます。 #parse が参照するテンプレートはすべて、TEMPLATE_ROOT 以下になければなりません。 #include 指示子と違って、#parse の引数は一つだけです。
VTL templates can have #parse statements referring to
templates that in turn have #parse statements. By default
set to 10, the parse_directive.maxdepth line of the
velocity.properties allows users to customize maximum
number of #parse referrals that can occur from a single
template. (Note: If the parse_directive.maxdepth property
is absent from the velocity.properties file, Velocity
will set this default to 10.) Recursion is permitted, for example,
if the template dofoo.vm contains the following lines:
VTL テンプレートは、#parse 文で参照する
テンプレート内でさらに #parse 文で [別のテンプレートを]
参照できます。
単独のテンプレートでの #parse
参照による入れ子の回数の最大値はデフォルトで10にセットされていて、
velocity.properties の
parse_directive.maxdepth 行で、カスタマイズできます。
(注：
parse_directive.maxdepth プロパティが velocity.properties
ファイルになければ、Velocity がこのデフォルトを 10 にセットします。)
再帰も可能です。例えば
テンプレート dofoo.vm が以下の行を含む場合、
It would reference the template parsefoo.vm, which
might contain the following VTL:
このコードは以下の VTL の内容のテンプレート parsefoo.vm を参照します。
After "Count down." is displayed, Velocity passes through
parsefoo.vm, counting down from 8. When the count
reaches 0, it will display the "All done with parsefoo.vm!" message.
At this point, Velocity will return to dofoo.vm and
output the "All done with dofoo.vm!" message.
「カウントダウン。」が表示された後、
Velocity は parsefoo.vm を走査し、8 からカウントダウンします。
カウントが 0 に達すると、「parsefoo.vm の処理完了!」メッセージを表示します。
この時点で、Velocity はdofoo.vm に戻って、
「dofoo.vm の処理完了!」メッセージを出力します。
The #stop script element allows the template designer to stop the execution of the template engine and return. This is useful for debugging purposes.
#stop スクリプト要素でテンプレートエンジンの実行を止めることができます。 これは、デバッグするときに役立ちます。
The #macro script element allows template designers to define a repeated segment of a VTL template. Velocimacros are very useful in a wide range of scenarios both simple and complex. This Velocimacro, created for the sole purpose of saving keystrokes and minimizing typographic errors, provides an introduction to the concept of Velocimacros.
#macro スクリプト要素で、VTL テンプレートで繰り返し出てくる部分を定義できます。 Velocimacro は、単純なものから複雑なものまで広範囲にわたるシナリオで非常に役立ちます。 次の Velocimacro は、 キーストロークを節約し、入力ミスを少なくするためだけに作られたものですが、 Velocimacro の概念を紹介するのに役立つでしょう。
The Velocimacro being defined in this example is d, and it can be called in a manner analogous to any other VTL directive:
この例で定義されている Velocimacro は d です。そして、 それは他の VTL 指示子 と同じような方法で呼び出すことができます：
When this template is called, Velocity would replace #d() with a row containing a single, empty data cell.
このテンプレートが呼ばれると、Velocity は #d() を一つの、 空のデータセルを含んでいる列と置換します。
A Velocimacro could take any number of arguments -- even zero arguments, as demonstrated in the first example, is an option -- but when the Velocimacro is invoked, it must be called with the same number of arguments with which it was defined. Many Velocimacros are more involved than the one defined above. Here is a Velocimacro that takes two arguments, a color and an array.
Velocimacro は任意の数の引数を取ることが出来ます (最初の例で示したとおり引数なしでもかまいません)。 ただし、Velocimacro が呼び出されるとき、 定義されたのと同じ数の引数で呼ばれなければなりません。 多くの Velocimacro は、上で定義したものより多くの引数を含みます。 これは、色と配列という2つの引数をとる Velocimacro です。
The Velocimacro being defined in this example, tablerows, takes two arguments. The first argument takes the place of $color, and the second argument takes the place of $somelist.
この例(tablerows)で定義されている Velocimacro は、2つの引数をとります。 最初の引数は、$color となり、2番目の引数は、$somelist となります。
Anything that can be put into a VTL template can go into the body of a Velocimacro. The tablerows Velocimacro is a foreach statement. There are two #end statements in the definition of the #tablerows Velocimacro; the first belongs to the #foreach, the second ends the Velocimacro definition.
VTL テンプレートに入れられるものは何でも、Velocimacro の本体に入れることができます。 tablerows Velocimacro は、foreach 文です。 2つの #end 文が、#tablerows Velocimacro の定義にありますが、 最初の end で #foreach が終了し、二番目の end で Velocimacro 定義が終了します。
Notice that $greatlakes takes the place of $somelist. When the #tablerows Velocimacro is called in this situation, the following output is generated:
$greatlakes が $somelist に代わることに注意してください。 #tablerows Velocimacro が上記のように呼ばれるとき、以下の出力が生成されます。
Velocimacros can be defined inline in a Velocity template, meaning that it is unavailable to other Velocity templates on the same web site. Defining a Velocimacro such that it can be shared by all templates has obvious advantages: it reduces the need to redefine the Velocimacro on numerous templates, saving work and reducing the chance of error, and ensures that a single change to a macro available to more than one template.
Velocimacro は Velocity テンプレート内で インライン で定義できますが、 その場合は同じ Web サイトの他の Velocity テンプレートには利用できません。 全てのテンプレートで共有できるような Velocimacro を定義することには、 明らかにいくつかの利点があります。例えば、多数のテンプレートで Velocimacro をいちいち定義する必要を減らせますし、それにより作業量が節約されたり、 エラーの可能性が減りますし、一つのマクロに対する一箇所の変更が複数のテンプレートに反映されることを保証します。
Were the #tablerows($color $list) Velocimacro defined in a
Velocimacros template library, this macro could be used on any of
the regular templates. It could be used many times and for many
different purposes. In the template mushroom.vm devoted
to all things fungi, the #tablerows Velocimacro could be
invoked to list the parts of a typical mushroom:
#tablerows($color $list) Velocimacro が Velocimacro
テンプレートライブラリで定義されている場合、
このマクロはどの通常のテンプレートでも使うこともできます。
それは、何度でも使えますし、どんな用途でも使うことが出来ます。
菌類百科専門の mushroom.vm テンプレートの中で、
#tablerows Velocimacro は、
典型的なキノコの各部分をリストするために呼び出すことができます：
When fulfilling a request for mushroom.vm, Velocity
would find the #tablerows Velocimacro in the template
library (defined in the velocity.properties file) and
generate the following output:
mushroom.vm の要求を満たすとき、Velocity は
#tablerows Velocimacro をテンプレートライブラリ
(velocity.properties ファイルにおいて定義されています) から見つけて、
以下の出力を生成します。
Velocimacros can take as arguments any of the following VTL elements :
Velocimacro は、以下の VTL 要素のどれでも引数として取ることができます。
When passing references as arguments to Velocimacros, please note that references are passed 'by name'. This means that their value is 'generated' at each use inside the Velocimacro. This feature allows you to pass references with method calls and have the method called at each use. For example, when calling the following Velocimacro as shown
Velocimacro の引数としてリファレンスを渡す際、 リファレンスは「名前渡し」されることに注意してください。 つまり、Velocimacro 内で使われるたびにその値が「生成される」ことを意味します。 この機能を使って、リファレンスにメソッド呼び出しを渡して、 使うたびにそのメソッドを呼ぶようにできます。 例えば、以下に示すように Velocimacro を呼び出すと、
results in the method bar() of the reference $foo being called 3 times.
結果として、リファレンス $foo のメソッド bar() が3回呼び出されます。
At first glance, this feature appears surprising, but when you take into consideration the original motivation behind Velocimacros -- to eliminate cut'n'paste duplication of commonly used VTL -- it makes sense. It allows you to do things like pass stateful objects, such as an object that generates colors in a repeating sequence for coloring table rows, into the Velocimacro.
一見、この機能は驚くべきことのように見えます、 しかし、あなたが Velocimacro の背景にある最初の動機 ― よく使われる VTL をカット&ペーストすることによる重複を除去する ― を考慮すれば、納得できるかと思います。 この機能により、 Velocimacro に「状態を保持する」(Stateful) オブジェクト (例えばテーブル列に色をつけるために繰り返しシーケンスで色を生成するオブジェクト) を渡すようなことができます。
If you need to circumvent this feature, you can always just get the value from the method as a new reference and pass that :
この機能を回避する必要があるならば、常にメソッドから値をリファレンスとして取得し、 それを渡せばよいのです。
Several lines in the velocity.properties file allow for
flexible implementation of Velocimacros. Note that these are also
documented in the Developer Guide.
velocity.propertiesファイル内の何行かを使えば、Velocimacro を柔軟に実装できます。
注意: 開発者ガイドも参照してください。
velocimacro.library - A comma-separated list of all
Velocimacro template libraries. By default, Velocity looks for
a single library: VM_global_library.vm. The configured template path
is used to find the Velocimacro libraries.
velocimacro.library
─
全ての Velocimacro テンプレートライブラリのコンマ区切りリスト。
デフォルトでは、Velocity は VM_global_library.vm
というライブラリのみを探します。
設定されたテンプレートパスは Velomacro ライブラリを見つけるのに使用されます。
velocimacro.permissions.allow.inline - This property,
which has possible values of true or false, determines whether
Velocimacros can be defined in regular templates. The default,
true, allows template designers to define Velocimacros in the
templates themselves.
velocimacro.permissions.allow.inline
─
このプロパティは true または false の値を取ることができ、
Velocimacro を通常のテンプレートで定義できるかどうか判定します。
デフォルト (true) では、テンプレートで Velocimacro を定義できます。
velocimacro.permissions.allow.inline.to.replace.global -
With possible values of true or false,
this property allows the user to specify if a Velocimacro defined
inline in a template can replace a globally defined template, one
that was loaded on startup via the velocimacro.library
property. The default, false, prevents
Velocimacros defined inline in a template from replacing those
defined in the template libraries loaded at startup.
velocimacro.permissions.allow.inline.to.replace.global
─
このプロパティは true または false の値を取ることができ、
テンプレート内でインラインで定義された Velocimacro が
グローバルで定義されたテンプレート
(スタートアップ時にvelocimacro.library
プロパティ経由でロードされたもの)
を上書きできるかどうかを指定します。
デフォルトでは false なので、
スタートアップでロードされたテンプレートライブラリで定義されたものは
インラインの Velocimacro では上書きできません。
velocimacro.permissions.allow.inline.local.scope - This
property, with possible values of true or false, defaulting to false,
controls if Velocimacros defined inline are 'visible' only to the
defining template. In other words, with this property set to true,
a template can define inline VMs that are usable only by the defining
template. You can use this for fancy VM tricks - if a global VM calls
another global VM, with inline scope, a template can define a
private implementation of the second VM that will be called by the
first VM when invoked by that template. All other templates
are unaffected.
velocimacro.permissions.allow.inline.local.scope
─
このプロパティは true または false の値を取ることができ、
デフォルトは false です。
インラインで定義された Velocimacro が、
定義したテンプレートでだけ「見える」かどうかを制御します。
つまり、このプロパティを true にすると、定義されたテンプレート内でのみ有効な
インライン VM を定義することが出来ます。
これを使った、手の込んだ VM のテクニックがあります。
グローバルな VM が別のグローバルな VM を呼ぶ場合、
テンプレートはインラインスコープで、前者の VM から呼ばれる後者の
VM のプライベート実装を定義できます。
他のどのテンプレートにも影響ありません。
velocimacro.context.localscope - This property has the
possible values true or false, and the default is false. When true,
any modifications to the context via #set() within a Velocimacro
are considered 'local' to the Velocimacro, and will not
permanently affect the context.
velocimacro.context.localscope
─
このプロパティは true または false の値を取ることができ、
デフォルトは false です。
true のときは、Velocimacro 内の #set() によるコンテキストへの変更はすべて、
Velocimacro に「ローカル」であると扱われて、
コンテキストに永続的な影響を及ぼしません。
velocimacro.library.autoreload - This property
controls Velocimacro library autoloading. The default value
is false. When set to true
the source Velocimacro library for an invoked Velocimacro will be checked
for changes, and reloaded if necessary. This allows you to change and
test Velocimacro libraries without having to restart your application or
servlet container, just like you can with regular templates.
This mode only works when caching is off
in the resource loaders (e.g. file.resource.loader.cache = false ).
This feature is intended for development, not for production.
velocimacro.library.autoreload
─
このプロパティは Velocimacro の自動ロードを制御します。
デフォルトの値は false です。
true にセットされると、呼び出された Velocimacro に対応する
Velocimacro ライブラリのソース変更がチェックされ、必要に応じてリロードされます。
これにより、ちょうど普通のテンプレートでできるように、
アプリケーションやサーブレットコンテナを再起動せずに Velocimacro
ライブラリを変更、テストすることができます。
このモードはリソースローダーでキャッシングを off にした時
(例えば file.resource.loader.cache = false にした時)
だけ有効です。
この機能は開発用で、本番環境用ではありません。
Currently, Velocimacros must be defined before they are first used in a template. This means that your #macro() declarations should come before using the Velocimacros.
現在、Velocimacro はテンプレートで最初に使われる前に定義されていなければなりません。 つまり、 #macro() 宣言が Velocimacro を使う前に出てくる必要があります。
This is important to remember if you try to #parse()
a template containing inline #macro() directives. Because
the #parse() happens at runtime, and the parser decides if
a VM-looking element in the template is a VM at parsetime,
#parse()-ing a set of VM declarations won't work as expected.
To get around this, simply use the velocimacro.library
facility to have Velocity load your VMs at startup.
インラインの #macro() 指示子を含んでいるテンプレートを #parse()
しようとするときには、このことに気をつける必要があります。
というのも、 #parse() は実行時に発生し、
パーサはテンプレート中の VM のように見える要素が VM かどうかをパース時に判定するため、
VM 宣言を #parse() しても期待したようには動かないのです。
これを回避するには、単に velocimacro.library 機能を使ってください。
Velocity はあなたの VM を起動時にロードします。
VTL directives can be escaped with the backslash character ("\") in a manner similar to valid VTL references.
VTL 指示子は、VTL リファレンスと同様に、バックスラッシュ (「\」) でエスケープできます。
Extra care should be taken when escaping VTL directives that contain multiple script elements in a single directive (such as in an if-else-end statements). Here is a typical VTL if-statement:
一つの指示子に複数のスクリプト要素が含まれている VTL 指示子 (if-else-end 文など)をエスケープする時は、 特に注意が必要です。 典型的な VTL の if 文は以下のようなものです：
If $jazz is true, the output is
$jazz が true ならば、出力は
If $jazz is false, there is no output. Escaping script elements alters the output. Consider the following case:
$jazzが false ならば、出力はありません。 スクリプト要素をエスケープすると、出力が変わります。 以下の場合を考えてみましょう。
Whether $jazz is true or false, the output will be
$jazzが ture か false かどうかに関係なく、 出力は、
In fact, because all script elements are escaped, $jazz is never evaluated for it's boolean value. Suppose backslashes precede script elements that are legitimately escaped:
実際、全てのスクリプト要素がエスケープされるので、$jazz の真偽は決してチェックされません。 バックスラッシュが正しくエスケープされたスクリプト要素の前にあるとしましょう。
In this case, if $jazz is true, the output is
この場合、$jazzが true ならば、出力は
となります。
To understand this, note that the #if( arg ) when
ended by a newline (return) will omit the newline from the output.
Therefore, the body of the #if()
block follows the first '\', rendered
from the '\\' preceding the #if().
The last \ is on a different
line than the text because there is a newline after 'Ganelin', so
the final \\, preceding the #end is part of the
body of the block.
これを理解するためには、#if( arg ) が
改行(return) で終了しているときに、その改行は出力から除外されることに着目してください。
そのため、#if() ブロックのボディが最初の「\」 (#if() とその前の 「\\」 の処理結果)に続きます。
最後の「\」は別の行になっています。それは、「Ganelin」の後に改行があり、
#end の前にある最後の \\ は、ブロックのボディの一部であるためです。
If $jazz is false, there is no output. Note that things start to break if script elements are not properly escaped.
$jazzが false ならば、出力はありません。
[訳注：実際には、#if( arg ) とその前の「\\」の処理結果である「\」
だけが出力されます。]
スクリプト要素が適切にエスケープされていなけば、おかしくなることに注意してください。
Here the #if is escaped, but there is an #end remaining; having too many endings will cause a parsing error.
ここでは、#if はエスケープされますが、#end が残っています。 end が余分なので、解析エラーを引き起こすことになります。
Although VTL in this user guide is often displayed with newlines and whitespaces, the VTL shown below
このユーザガイドの中の VTL は多くの場合、下記のように改行と空白を含んで表示されています。
is equally valid as the following snippet that Geir Magnusson Jr. posted to the Velocity user mailing list to illustrate a completely unrelated point:
Geir Magnusson Jr. は、改行や空白が全く無関係というのを示すために Velocity ユーザのメーリングリストに次のようなコードを投稿しました。
Velocity's behaviour is to gobble up excess whitespace. The preceding directive can be written as:
Velocity は、余分な空白を吸収するように振舞います。 上の指示子は以下のように書くことができます：
or as
または
In each case the output will be the same.
どちらの場合も出力は同じです。
Velocity has a handful of built-in mathematical functions that can be used in templates with the set directive. The following equations are examples of addition, subtraction, multiplication and division, respectively:
Velocity には一握りですが組み込みの計算機能があり、 テンプレートのset 指示子で使うことができます。 以下の式は、それぞれ加算、減算、乗算、除算の例です。
When a division operation is performed, the result will be an integer. Any remainder can be obtained by using the modulus (%) operator.
除算が実行される場合も結果は整数となります。 余りについては剰余演算子 (「%」) を使って取得できます。
Only integers (...-2, -1, 0, 1, 2...) are permissible when performing mathematical equations in Velocity; when a non-integer is used, it is logged and a null will be returned as the output.
Velocity で数式演算を実行する時は、整数だけ(...-2、-1、0、1、2...)が許可されており、 非整数が使われるとログに記録され、null が出力として返されます。
The range operator can be used in conjunction with #set and #foreach statements. Useful for its ability to produce an object array containing integers, the range operator has the following construction:
範囲演算子は、#set や #foreach 文と一緒に使うことができます。 要素に整数を持つオブジェクト配列を生成するのに役立つ範囲演算子は、 次のように生成できます。
Both n and m must either be or produce integers. Whether m is greater than or less than n will not matter; in this case the range will simply count down. Examples showing the use of the range operator as provided below:
n と m は両方とも整数であるか、整数を生成しなければなりません。 m が、n より大きいか、小さいかは重要ではありません; より小さい場合には、範囲は単にカウントダウンします。 下記は範囲演算子の使い方を示している例です。
Produces the following output:
以下の出力を生成します:
Note that the range operator only produces the array when used in conjunction with #set and #foreach directives, as demonstrated in the fourth example.
4番目の例が示しているとおり、範囲演算子は #set と #foreach 指示子とともに使われた時だけ配列を生成することに注意してください。
Web page designers concerned with making tables a standard size, but where some will not have enough data to fill the table, will find the range operator particularly useful.
HTMLの表を決まったサイズにしたいのに、 表を埋めるにはデータが足りないこともあります。 そんな時、範囲演算子は特に便利です。
When a reference is silenced with the ! character and the ! character preceded by an \ escape character, the reference is handled in a special way. Note the differences between regular escaping, and the special case where \ precedes ! follows it:
リファレンスを「!」で沈黙させていて、 「!」の前に「\」エスケープ文字があるときは、 リファレンスは特別扱いされます。 通常のエスケープと、 「\」に「!」が続く特別な場合の違いに注意してください。
This renders as:
これは以下のように処理されます。 [訳注: 2行目は実際には「$!{」となります。]
Contrast this with regular escaping, where \ precedes $:
これを、「\」が「$」に先行する、通常のエスケープと比較してみましょう。
This renders as:
これは以下のように処理されます。
This section is a mini-FAQ on topics relating to Velocimacros. This section will change over time, so it's worth checking for new information from time to time.
このセクションは、Velocimacro に関するミニ FAQ です。 このセクションは、時とともに変更されるでしょう、 ですから新しい情報を時々確認するのは有用です。 [訳注：このバージョンでは変更されませんが、 次のバージョンでは変更されているかもしれません]
Note : Throughout this section, 'Velocimacro' will commonly be abbreviated as 'VM'.
注意: このセクションでは、「Velocimacro」は通常「VM」と略します。
Example : #center( #bold("hello") )
例 : #center( #bold("hello") )
No. A directive isn't a valid argument to a directive, and for most practical purposes, a VM is a directive.
いいえ。指示子は指示子の有効な引数にはなりません。 また、一般的に、 VM は指示子です。
However..., there are things you can do. One easy solution is to take advantage of the fact that 'doublequote' (") renders it's contents. So you could do something like
それでも…、解決策はあります。簡単なものとして、 ダブルクォート (") がその内容を処理することを利用する方法があります。 なので、このようにできます。
You can save a step...
以下のように省略も可能です…
Please note that in the latter example the arg is evaluated inside the VM, not at the calling level. In other words, the argument to the VM is passed in in its entirety and evaluated within the VM it was passed into. This allows you to do things like :
注意: 後者の例では、引数は VM 内部で評価されます。呼び出し時ではありません。 言い換えると、VM への引数は、そっくりそのまま渡されて、 渡された VM の中で評価されます。その結果、次のようなことが可能です。
Where the output is
ここで出力は以下のようになります。
because the evaluation of the "#inner($bar)" happens inside #outer(), so the $bar value set inside #outer() is the one that's used.
"#inner($bar)" の評価は、#outer() の内部で発生するため、 $bar の値としては #outer() 内部でセットされたその値が使われます。
This is an intentional and jealously guarded feature - args are passed 'by name' into VMs, so you can hand VMs things like stateful references such as
この機能は意図的なものであり、十分に保護されています ─ 引数は VM に「名前渡し」されるので、以下のように、 「状態を保持する」(Stateful) リファレンスなどを VM に渡すことが出来ます。
And have rowColor() called repeatedly, rather than just once. To avoid that, invoke the method outside of the VM, and pass the value into the VM.
また、rowColor() は1回ではなく、[#foo() の呼び出しごとに] 何度も呼ばれます。 これを禁止するには、 VM の外側でメソッドを呼び出し、 VM には値を渡してください。
Currently, Velocimacros must be defined before they are first used in a template. This means that your #macro() declarations should come before using the Velocimacros.
現在、Velocimacro はテンプレートで最初に使われる前に定義されていなければなりません。 つまり、 #macro() 宣言が Velocimacro を使う前に出てくる必要があります。
This is important to remember if you try to #parse()
a template containing inline #macro() directives. Because
the #parse() happens at runtime, and the parser decides if
a VM-looking element in the template is a VM at parsetime,
#parse()-ing a set of VM declarations won't work as expected.
To get around this, simply use the velocimacro.library
facility to have Velocity load your VMs at startup.
インラインの #macro() 指示子を含んでいるテンプレートを #parse()
しようとするときには、このことに気をつける必要があります。
というのも、 #parse() は実行時に行われ、
パーサは、テンプレート内の VM のように見える要素が VM かどうかをパース時に決定するため、
VM の宣言を #parse() しても期待したようには動かないのです。
これを回避するには、単に velocimacro.library 機能を使ってください。
Velocity はあなたの VM を起動時にロードします。
There is a property, meant to be used in development, not production :
そのためのプロパティがあります。これは開発時に使用するためのもので、 本番環境用ではありません。
velocimacro.library.autoreload
velocimacro.library.autoreload
which defaults to false. When set to true along with
デフォルトは、 false です。 true にセットする時は、下記の指定と一緒に使います。
<type>.resource.loader.cache = false
<type>.resource.loader.cache = false
(where <type> is the name of the resource loader that you are using, such as 'file') then the Velocity engine will automatically reload changes to your Velocimacro library files when you make them, so you do not have to dump the servlet engine (or application) or do other tricks to have your Velocimacros reloaded.
(ここで、 <type> は、'file' など使用するリソースローダの名前です) そうすると Velocity エンジンは、自動的にあなたの Velocimacro ライブラリファイルが変更されたときに変更をリロードしようとします。 そのため、サーブレットエンジン (あるいはアプリケーション) を再起動したり Velocimacro をリロードするために小細工をする必要はありません。
Here is what a simple set of configuration properties would look like.
簡単なプロパティ設定はこのようになります。
Don't keep this on in production.
本番環境ではこの状態のままにしておかないでください。
A common question that developers ask is How do I do String concatenation? Is there any analogue to the '+' operator in Java?.
開発者共通の疑問として、 「文字列の連結はどうするのか？Javaにおける '+' 演算子のようなものがあるのか？」というのがあります。
To do concatenation of references in VTL, you just have to 'put them together'. The context of where you want to put them together does matter, so we will illustrate with some examples.
VTLにおいてリファレンスの結合を行うには、単に 「並べて記述する」だけです。 並べて記述するといっても状況によりますので、 いくつかの例を使って示します。
In the regular 'schmoo' of a template (when you are mixing it in with regular content) :
テンプレートの一般的な「シュムー」[訳注：VTL 以外の部分]において(一般的な内容に混ぜる時)、
and the output will render as 'The clock is BigBen'. For more interesting cases, such as when you want to concatenate strings to pass to a method, or to set a new reference, just do
出力は「その時計は BigBen.」と処理されます。 もうすこし面白い例として、メソッドに渡すために文字列を結合したい場合や 新しいリファレンスにセットしたい場合は以下のようにします。
Which will result in the same output. As a final example, when you want to mix in 'static' strings with your references, you may need to use 'formal references' :
結果として同じ出力になります。 最後の例として、リファレンスを「静的な」文字列と混ぜたい場合、 「正式リファレンス」を使う必要があるかもしれません。
Now the output is 'The clock is BigTallBen'. The formal notation is needed so the parser knows you mean to use the reference '$size' versus '$sizeTall' which it would if the '{}' weren't there.
出力は「その時計は BigTallBen.」になります。正式表記は パーサに「$sizeTall」ではなく「$size」リファレンスを使うということを 知らせるのに必要です。「{}」がないと「$sizeTall」になってしまいます。
If you encounter any mistakes in this manual or have other feedback related to the Velocity User Guide, please email the Velocity user list. Thanks!
このマニュアルの誤りなど、Velocity ユーザガイドに関するフィードバックを行う時は、 Velocity ユーザメーリングリスト に電子メールを送ってください。 よろしくお願いします。