Using Velocity 3.0 Tools

Starting with Rhythmyx 7.3.2 patch 732_20180928, Percussion uses version 3.0 of the Velocity Tools. These tools are compliant with the Velocity 2.0 Template Engine. The Velocity tools are defined in 'tools.xml,' and includes new tools such as JsonTool, LogTool, and CollectionTool by default as of the 09/28 release. Previous tools and the new tools are made available by default on templates used within the CMS. The Velocity documentation for the tools can be found here.

The 'tools.xml' file is located on the server under the following location(s):

JBoss: AppServer\server\rx\deploy\rxapp.ear\rxapp.war\WEB-INF\config\velocity

Jetty: jetty\base\webapps\Rhythmyx\WEB-INF\config\velocity

Using the Velocity 3.0 Tools

The Velocity tools are made available on any template within the CMS. These can be accessed by using the '$' character followed by 'tools.' The prefixes are defined within the 'tools.xml' file mentioned above. Below are a few examples of how to use the new tools within a Snippet Template.

LogTool:

The Velocity LogTool documentation can be found here. This tool can be used to provide logging from within a template and is pretty straight forward to use. With the current configuration of Rhythmyx, this will log an entry to the 'velocity.log' file and the 'server.log' file.

From within a snippet template, for example, the following can be inserted:


#if(1 == 1)##

$tools.log.info("The expression above is true.")
#else##
$tools.log.error("The above expression should have been true :/")
#end##

Once the template is previewed or rendered, an entry will be made to the log files as such:

15:58:04,702 INFO [LogTool] The expression above is true.

Logging provides an additional way to provide information to users for debugging or for writing general information to a file.

JsonTool:

The JsonTool can be used to retrieve and manipulate JSON within a Velocity Template. The Velocity documentation for this tool can be found here. As an example, consider the 'example.json' file below with the following contents:

{
"rating":7,
"title":"Airplane!",
"year":"1980",
"directors": [
"Jim Abrahams",
"David Zucker"
]
}

and the following Velocity:

## json.read will read from a file resource on the server

#set($json = $tools.json.read("C:\\Users\\chriswright\\Desktop\\example.json"))##
 
JSON is: $json 
Rating is: $json.rating 
Title is: $json.title 
Year is: $json.year 
Directors: $json.directors 

This will produce the following output:

JSON is: {year=1980, directors=[Jim Abrahams, David Zucker], rating=7, title=Airplane!}
Rating is: 7
Title is: Airplane!
Year is: 1980
Directors: [Jim Abrahams, David Zucker]

Note: json.read will read a resource from a file on the server and json.fetch takes a URL as a parameter. Further documentation can be found on the Velocity site in the link above.

CollectionTool:

The CollectionTool is used to work with Java Collections. It can be used to sort and split collections. For example, considering the following:


#set($split = $tools.sorter.split("test3, test2, test1"))##

#foreach($str in $split)##
String is: $str 
#end##

This collection has been split (using $tools.sorter.split) into a Java String array (based on the ',' delimiter) and yields the following:

String is: test3
String is: test2
String is: test1

When looping through the array, the strings aren't sorted. However, they can easily be sorted using the tool:

$tools.collection.sort($split)##

#foreach($str in $split)##
String is: $str 

#end##

which results in the following:

String is: test1
String is: test2
String is: test3

This tool can be particularly useful when working with data structures that aren't sorted, such as the set of keys in the JSON example provided above:

#foreach($key in $tools.json.keySet())
Key is: $key 
#end

Yields the following:

Key is: year
Key is: directors
Key is: rating
Key is: title

However, using the CollectionTool results in:

#foreach($key in $tools.collection.sort($tools.json.keySet()))
Key is: $key 
#end

Key is: directors
Key is: rating
Key is: title
Key is: year