...
The first concept in Velocity is a reference. A reference is how you access a given object to manipulate things. When your template executes, there will be many predefined objects that you can reference, but we want to look at how to set a basic reference and then access it later in the template. Let's look at a Hello World example.
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<html> <body> #set( $foo = "Velocity" ) Hello $foo World! </body> <html> |
...
Any good programming or scripting language will allow you to have comments in the code that will not appear in the final product (in the case of Velocity, the rendered HTML page). In Velocity, a comment is all the text on the line that comes after two hash symbols (#) in a row. Let's take our Hello World example from the references section and add some comments.
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<html> <body>## Assign the value of Velocity to the variable $foo #set( $foo = "Velocity" )## Inject the contents of $foo into our Hello World statement Hello $foo World! </body> <html> |
While this may be total overkill for a Hello World example, comments are a great idea to include in your code. You may know everything that you're doing in a complex piece of code, but are you going to remember your decisions six months from now? What if another web developer has to come behind you and maintain or enhance the code? The bottom line is that comments are worth your time to write and will pay dividends in the future.
You can also include multi-line comments within your code by starting a line with a pound symbol immediately followed by the asterisk symbol "#*" and ending another line with the symbols reversed "*#". Below is an example of a multi-line comment from the Velocity User Guide.
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
This is text that is outside the multi-line comment. Online visitors can see it. #* Thus begins a multi-line comment. Online visitors won't see this text because the Velocity Template Engine will ignore it. *# Here is text outside the multi-line comment; it is visible. |
...
| Tip |
|---|
Complete documentation is available online by clicking the "Documentation" link to the left of the template editor. The online documentation shows all the methods available for each object. or https://secure.ultracart.com/merchant/catalog/documentationSave.do |
For this example, we will show how to call a set method to store a value in custom field 1 on the cart and then fetch it.
...
Velocity supports common directions, such as if, if/else, and if/else/if/else style conditional directives. The simplest conditional directive is a basic "#if" statement.
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
#if( $foo ) <strong>Foo is true!</strong> #end |
As long as the variable "foo" evaluates to true, then the HTML code between the #if and the #end statement will be included in the rendered output. You can also test a single condition and then output two different values.
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
#if( $foo )
<strong>Foo is true!</strong>#else
Foo is false!#end
Another common scenario is to evaluate multiple conditions to determine a value to display. This is accomplished with the "#if/#elseif/#else" syntax.
#if( $foo == 1 )
<strong>North</strong>
#elseif( $foo == 2 )
<strong> East</strong>
#elseif( $foo == 3 )
<strong>South</strong>
#else
<strong>West</strong>
#end
|
...
Let's review the "#foreach" loop that we used in the Hello World example in Chapter 2.
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
#foreach ($item in $group.getItems())
<a href="${baseUrl}${group.getPath()}${item.getMerchantItemID()}.html">
${item.getDescription()}</a><br>
#end
|
...
During a Velocity loop, the variable "$velocityCount" is automatically assigned the current index of the loop. This built-in variable is useful for looping through items and outputting a numbered list. Another common use of the "$velocityCount" variable is to stop the loop after a certain number of objects are processed. Let's take the loop above and stop it after ten loops.
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
#foreach ($item in $group.getItems())
<a href="${baseUrl}${group.getPath()}${item.getMerchantItemID()}.html">
${item.getDescription()}</a><br>
#if ($velocityCount >= 10) #break
#end
|
...
Velocity has the typical mathematical operations found in most languages built-in: addition (+), subtraction (-), multiplication (*), division (/), and modulus (%). Below is an example of performing a mathematical operation on "bar" and assigning the result to the variable "foo".
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
#set( $foo = $bar + 3 ) #set( $foo = $bar - 4 ) #set( $foo = $bar * 6 ) #set( $foo = $bar / 2 ) #set( $foo = $bar % 5 ) |
...