前言

翻译自： 官网 Apache Velocity Project

1. 访问

1.1 变量

$ [ ! ][ { ][a…z, A…Z ][ a…z, A…Z, 0…9, -, _ ][ } ]

示例：

$mud-Slinger_9
$!mud-Slinger_9
${mud-Slinger_9}
$!{mud-Slinger_9}

1.2 属性

Notation:

$ [ { ][ a…z, A…Z ][ a…z, A…Z, 0…9, -, _ ] .[a…z, A…Z ][a…z, A-Z, 0…9, -, _ ] [ } ]

示例：
$customer.Address
${purchase.Total}
对于 getProp(), isProp 可以用 $obj.prop 代替

1.3 方法

Notation:

$ [ { ][ a…z, A…Z ][ a…z, A…Z, 0…9, -, _ ] .[ a…z, A…Z ][a…z, A…Z, 0…9, -, _ ]( [optional parameter list…* ] ) [ } *]

示例:
$customer.getAddress()
${purchase.getTotal()}
$page.setTitle( “My Home Page” )

VTL Properties can be used as a shorthand notation for VTL Methods that take get and set. Either $object.getMethod() or $object.setMethod() can be abbreviated as $object.Method. 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.
对于 $object.getMethod(), $object.getMethod() 方法 可以使用 $object.method 代替

2. 指令

2.1 #set 创建变量

格式: # [ { ] set [ } ] ( $ref = [ ", ’ ]arg[ ", ’ ] )

参数说明:
$ref - The LHS of the assignment must be a variable reference or a property reference.
表达式左侧必须是一个变量引用或者属性引用
arg - The RHS of the assignment, arg is parsed if enclosed in double quotes, and not parsed if enclosed in single quotes. If the RHS evaluates to null, it is not assigned to the LHS.
表达式右侧，如果由双引号包裹，会被解析，单引号则不会，如果右侧表达式值为null，则不会被赋值

双引号单独说明一下
$className 为 “test0”
#{set}($test=“$className”)
$test // 输出为 test0

Examples:

Variable reference: #set( $monkey = $bill )
变量引用
String literal: #set( $monkey.Friend = ‘monica’ )
字符串字面量
Property reference: #set( $monkey.Blame = $whitehouse.Leak )
属性用用
Method reference: #set( $monkey.Plan = $spindoctor.weave($web) )
方法引用
Number literal: #set( $monkey.Number = 123 )
数字字面量
Range operator: #set( $monkey.Numbers = [1…3] )
数组
Object list: #set( $monkey.Say = [“Not”, $my, “fault”] )
对象列表
Object map: #set( $monkey.Map = {“banana” : “good”, “roast beef” : “bad”})
对象map

The RHS can also be a simple arithmetic expression, such as:
右侧表达式也可以是简单的数学表达式
加
Addition: #set( $value = $foo + 1 )
减
Subtraction: #set( $value = $bar - 1 )
乘
Multiplication: #set( $value = $foo * $bar )
除
Division: #set( $value = $foo / $bar )
取余
Remainder: #set( $value = $foo % $bar )

2.2 #if/#elseif/#else 分支控制

Format:

# [ { ] if [ } ] ( [condition] ) [output] [# [ { ] elseif [ } ] ( [condition] ) [output] ]* [# [ { ] else [ } ] [output] ] # [ { ] end [ } ]

Usage:

condition - If a boolean, considered true if it has a true false; if not a boolean, considered true if not null.
output - May contain VTL.

The == operator can be used to compare numbers, strings, objects of the same class, or objects of different classes. In the last case (when objects are of different classes), the toString() method is called on each object and the resulting Strings are compared.
== 操作符可以用来比较 数字，字符串，相同类型对象，不同类型对象。如果是不同类型对象，会先调用 toString 方法，然后使用字符串比较

2.3 #foreach 循环控制

# [ { ] foreach [ } ] ($ref in arg) statement # [ { ] end [ } ]

• $ref - The first variable reference is the item.
  列表中的元素
• arg - May be one of the following: a reference to a list (i.e. object array, collection, or map), an array list, or the range operator.
  可以是 对象数组，集合，map， 数组列表，范围操作符
• statement - What is output each time Velocity finds a valid item in the list denoted above as arg. This output is any valid VTL and is rendered each iteration of the loop.
  输出内容

Examples of the #foreach(), omitting the statement block :

Reference: #foreach ( $item in $items )
Array list: #foreach ( $item in [“Not”, $my, “fault”] )
Range operator: #foreach ( $item in [1…3] )

Additionally, the maximum allowed number of loop iterations can be controlled engine-wide (an ability introduced in Velocity 1.5). By default, there is no limit:
可以通过设置，指定 foreach list的最大长度
# The maximum allowed number of loops.
directive.foreach.maxloops = -1

2.4 #include - 引入本地文件，文本展示

Format:

# [ { ] include [ } ] ( arg[ arg2 … argn] )

Usage:

arg - Refers to a valid file under TEMPLATE_ROOT.
路径一定要是 模板根目录下的

Examples:

String: #include( “disclaimer.txt” “opinion.txt” )
字符串引用
Variable: #include( $foo $bar )
变量引用

2.5 #parse - 引入本地文件，velocity 解析后展示

Format:

# [ { ] parse [ } ] ( arg )

Usage:

arg - Refers to a template under TEMPLATE_ROOT.
Examples:

String: #parse( “lecorbusier.vm” )
Variable: #parse( $foo )
允许循环引用，默认最深10层。可以设置参数 parse_directive.maxdepth 决定最大深度
Recursion permitted. See parse_directive.maxdepth in velocity.properties to change from parse depth. (The default parse depth is 10.)

2.6 #stop - 停止模板解析

Format:

# [ { ] stop [ } ]

Usage:

This will stop execution of the current template. This is good for debugging a template.
停止解析模板，可以用来debug模板解析

2.7 #break - 停止当前指令

Format:

# [ { ] break [ } ]

Usage:

This will break execution of the current content directive. This is good for exiting a #foreach loop early, but also works in other scopes. You can even pass the scope control reference for a specific outer scope to break execution of all scopes outward to the specified one.
停止当前指令解析，也可以跳出当前 scope, 到外部 scope

2.8 #evaluate - 动态解析字符串或引用

Format:

# [ { ] evaluate [ } ] ( arg )

Usage:

arg - String literal or reference to be dynamically evaluated.
字符串或者字符串引用
Examples:

String: #evaluate( ‘string with VTL #if(true)will be displayed#end’ )
Variable: #evaluate( $foo )

2.9 #define - 定义一个“块”引用

Format:

# [ { ] define [ } ] ( $ref )statement# [ { ] end [ } ]

Usage:

$ref - Reference that is assigned the VTL block as a value.
标识 “块” 的名称
statement - Statement that is assigned to the reference.
“块” 的内容
Example:

#define( $hello ) Hello $who #end 
#set( $who = "World!") 
$hello   ## displays Hello World!

2.10 #macro - 定义一个带参数的块

Format:

# [ { ] macro [ } ] ( vmname $arg1 [ $arg2 $arg3 … $argn ] ) [ VM VTL code… ] # [ { ] end [ } ]

Usage:

• vmname - Name used to call the VM (#vmname)
  块名称
• 参数列表
  $arg1 $arg2 [ … ] - Arguments to the VM. There can be any number of arguments, but the number used at invocation must match the number specified in the definition.
  可以有任意数量的参数，调用的参数数量必须与定义一直
• [ VM VTL code… ] - Any valid VTL code, anything you can put into a template, can be put into a VM.
  Once defined, the VM is used like any other VTL directive in a template.
  块的内容
• 调用

#vmname( $arg1 $arg2 )

Except, that when you wish to call a VM with a body, then you must prefix the name of the VM with @. The content of that body may be referenced in the macro definition via $!bodyContentasmanyorfewtimesasyoulike.特别的，当你想使用带body的参数调用时，必须要在块名称前加上“@”。body内容可以在块中使用，通过‘$!bodyContent` 使用

#@vmname( $arg1 $arg2 ) here is the body#end

VMs can be defined in one of two places:
带参数块可以定义在两个地方

• Template library: can be either VMs pre-packaged with Velocity or custom-made, user-defined, site-specific VMs; available from any template
• Inline: found in regular templates, only usable when velocimacro.permissions.allowInline=true in velocity.properties.
  设置 velocimacro.permissions.allowInline=true 时，可以在行内使用

3 注释

3.1 单行注释

## This is a comment.**

3.2 多行注释

#**This is a multiline comment.This is the second line.
*#

3.3 带特殊字符注释

#[[This has invalid syntax that would normally need 
"poor man's escaping" like:- #define()- ${blah]]#