#V elocity Syntax

TODO: This article is currently just a braindump. It is very much work in progress)

References

A reference allows you to render code to the output. A reference is either a variable, or a series of method & property calls on a variable)

Variables

The simplest reference is a variable - $variable. This gets you the object in the current template named 'variable'. A variable name must start with a letter (a-z or A-Z), but after that can contain any alphanumeric character as well as '-' and '_'. The following are examples of valid variables:

• $variable
• $VARIABLE
• $VaRiAbLe
• $variable123
• $variable_123
• $variable-123

The following however are not considered variables, and are rendered as text

• $-variable
• $1Variable
• $1.00

The variable ends at the invalid character, so [email protected] will be output the value of $name, followed by @example.com.

Properties & Methods

Property $reference.Property Method $reference.Method(<ARGUMENT LIST>) (Where consists of 0 or more Expressions seperated by commas)

Silent references

By default, if a reference is being rendered to output cannot be fully evaluated, the original reference is output.

#set($name = 'John')
$doesNotExist
${doesNotExist}
$name.DoesNotExist
$name.Length
$name.Length.DoesNotExist

would output

$doesNotExist
${doesNotExist}
$name.DoesNotExist
4
$name.Length.DoesNotExist

If you don't want anything to be output if evaluation fails, then you can use a silent reference. A e.g. $!variable.

#set($name = 'John')
$!doesNotExist
$!{doesNotExist}
$!name.DoesNotExist
$!name.Length
$!name.Length.DoesNotExist

would output

4

Note that only the reference itself is silenced, any surrounding whitespace (including new lines) is not silenced)

Formal References

Sometimes

#set($length = 6)
#set($width = 4)
$lengthX$width

Velocity will render $lengthX4 rather than 6x4 because it is looking for the variable named lengthX rather than $length followed by 'x' then '$width' then . To work around this issue, we can use curly braces to make a formal reference which explicitly distinguishes the reference, from the text after it

#set($length = 6)
#set($width = 4)
${length}X${width}

Formal references can also be combined with silent references by inserting a ! after the $. E.g. $!{variable}, $!{$variable.Method().Property}

Set Directive

The set directive is used to assign a value to a variable. You can assign simple literal values, as well as more complex expressions #set($name = 'John') #set($name = $database.GetName()) #set($count = $count + 1)

You assign to Properties on the left hand side, as well as variables. #set($person.Surname = 'Smith')

If the right hand side evaluates to null, then no assignment is made. For example, the output of the following example would be Hello.

#set($x = 'Hello')
#set($x = $notSet)
$x

If Directive

The if directive can be used for conditional output. In the simplest case, the inner content is only output if the condition evaluates to TRUE.

#if($product.IsReleasedInFuture)
	This product will be available from $product.ReleaseDate
#end

If the condition evaluates to a non boolean value, then the result is coerced to a boolean (that is Null is treated as false, all other values are considered true)

#if(123)This evaluates to true, and will show this text #end
#if($notSet)$notSet is null, so the condition evaluates to false and will not render this text#end

You can provide an optional block which is evaluated if the condition evaluates to false.

#if($name == 'Jim')
    Your name is Jim
#else
    Your name is not Jim
#end

You can also test multiple conditions in the same #if directive through #elseif blocks. If multiple conditions match, only the first matching block is rendered to the output.

#if($number == 7)
   The number is 0
#elseif($number > 0)
   The number is greater than 0
#elseif($number > -3)
   The number is greater than -3
#else
   The number is less than or equal to -3
#end

This is purely syntactic sugar over nesting #if directives

#if($number == 7)
   The number is 0
#else
   #if($number > 0)
      The number is greater than 0
   #else
      #if($number > -3)
	     The number is greater than -3
      #else
         The number is less than or equal to -3
	  #end
   #end
#end

(I say almost equivalent because some of the whitespace in this example is significant. If you remove the indentation from the two examples, they produce identical results. )

Numeric Literals

Numbers come in two forms, integers (42, -5) and floating point numbers (3.142, -2.718)

Strings

Strings come in two forms - single and double quoted. Single strings are treated exactly as is - 'Hello $name' evaluates to Hello $name. Double quoted strings are interpolated and evaluated. "Hello $name" would evaluate to Hello Bob (assuming $name is set to 'Bob')

You can even use directives in interpolated strings, although what you can do is limited as you can't include new lines.

#set($x = "#foreach($i in [1..5])$i,")
$x

would output 1,2,3,4,5,

If you need to use a quote character inside a string, you can use double quotes e.g. 'Jim''s Bag' or "Jane said "Hello"" to Bob"`.

Boolean Literals

true and false. (Note, these are case sensitive)

Lists

TODO: Describe lists

#set($list = [1.5, 'Jim', $product.Name, 9])
$list.Add('Alice')
$list.Remove('Jim')
The list contains $list.Count items
#if($list.Contains(9))
	The list contains the number 9
#else
	The list does not contain the number 9
#end

Range

A range expression can be considered as a list containing every number between a start and end point in order. For example[6..3] can be considered is equivalent to [6,5,4,3]. Range expressions are most often used with a foreach directive when some kind of counter is required For example

#foreach($count in [5..1])
$count...
#end
Thunderbirds are Go

would output

5...
4...
3...
2...
1...
Thunderbirds are Go

Mathematical Expressions

TODO: Discuss precedence

For example, the first two expressions below will set $x to be 11. The second however will be 15

#set($x = 1 + 2 * 5)
#set($x = 1 + (2 * 5))
#set($x = (1 + 2) * 5)

Relational Expressions

TODO: Equality & Comparison

Comments

Comments allow you to put descriptive text into your template that can be seen when you're editing the template, but not shown when the template is rendered. They can also be useful when troubleshooting as you can comment out portions of the code to stop them executing, then uncomment them as you're troubleshooting.

Single line comments are designated by ## - the '##' and anything beyond it on the line are ignored when the template is evaluated. For example, the following template

Hello
## Single line comment
World

would output

Hello
World

Another form of comment is the block comment. Block comments can span multiple lines

#*
  This is a
  multi line
  block comment
*#

As well as any arbitrary range in the template - e.g. Hello #* Cruel *# world would output Hello world.

For anyone familiar with block comments in other programming languages, one thing to note is that block comments can be nested. For example, the following script would not output anything. (In many programming langues, Outer Comment Bottom *# would not be considered part of `the comment).

#*
    Outer Comment Top
    #* Inner Comment *#
    Outer Comment Bottom
*#

TODO: Formal Comments. Not sure what the purpose of this is, and why it's a third type of comment, and not a special case of block comments.

#**
This is a formal comment
@author Jimmy Smith
@version 5
*#