Velocity Changelog

Overview

The Velocity context contains objects that can be accessed when writing a format. As of Cascade 5.7, the only object supplied is a representation of the exact same XML that would be passed to an XSLT format assigned to the same region. The XML is represented in a document object model using JDOM. The data in the object is accessed through the functions of the JDOM API. The context object and entry point into the available data is called the "contentRoot" and it is a JDOM Element.

In the case where the block assigned to the region or the content being supplied from the page's default region or structured data is not wrapped by a root element the root element is "system-xml".

A handful of tools were made available in the Velocity context in Cascade 6.2, and as of Cascade 6.10, still more tools have been added to the Velocity context. See the Velocity Tools page for more information.

The context currently contains the following objects:

As of 8.0.2

  • SerializerTool.toJson(element, removeRootElement) and SerializerTool.toJson(string, removeRootElement) have been added which allow Format writers to convert JDOM elements and XML strings into JSON.

As of 7.12.2

  • Query API - search for assets based on a number of search criteria.

As of 7.10.1

  • currentPage - currently rendered version of the page API object, which can be a draft, a working copy, a past version or a current version. In contrast, calling Locator Tool's "locatePage" method and passing current page's path and site name would always result in a current version of the page.

As of 7.4:

  • Locator Tool - accessed through just “_” character, for example: $_.locatePage(“/path”) - allows accessing Cascade Server assets using the Cascade Server API.
  • _PropertyTool - provides a list of available properties in an object, also provides an easy null check function.
  • _SortTool modification - now the tool has all the methods that the Apache SortTool provides in addition to the existing methods.
  • currentPagePath - a String containing path of the currently rendered Page
  • currentPageSiteName - a String containing name of the currently rendered Page’s Site

As of 7.0:

  • _FieldTool - Tool providing access to Java constants, such as Calendar.DAY_OF_WEEK, etc.

As of 6.10:

  • _DisplayTool - Tool containing some convenient diplay/formatting utilities for various data types.
  • _EscapeTool - Tool used to safely escape text for a variety of different languages, including XML, HTML, JavaScript, etc.
  • _MathTool - Tool containing numerous useful math and number conversion/manipulation methods.
  • _NumberTool - Tool containing convenient number formatting methods.

As of 6.2:

  • contentRoot - JDOM Element containing the XML supplied for the current region. This content could be coming from a block or the page's own structured data or xml. To view the raw XML, simply apply no Format to that region.
  • _DateTool - Tool used to manipulate numeric date values.
  • _XPathTool - Tool used to access data in an XML data structure using the XPath language.
  • _SerializerTool - Tool used to serialize an XML data structure to text.
  • _SortTool - Tool used to sort collections of JDOM Elements
  • _StringTool - Tool containing useful string manipulation method

In addition, 6.10 includes an upgrade of the Velocity Engine to version 1.7, which includes a number of improvements to the native language features.  For more on the improvements to Velocity in Cascade 6.10, check out the 6.10 Script Formats Webinar.  

Note:  The original release of 6.10 also included a LoopTool in the Velocity Context.  Because this tool has compatability issues with version 1.7 of the Velocity Engine, and because the 1.7 engine includes native language support for virtually all of the LoopTool functionality, this tool will be removed as of 6.10.2, and we encourage using the native looping enhancements outlined below in lieu of the LoopTool.

Objects in the context are referenced using a dollar sign ($) before the name of the object.

Velocity Engine 1.7 Improvements

With the release of Cascade 6.10, there are enhancements to Velocity's native support for loop management.  These improvements make it easier to track iteration counts, indexes and nested loops.  Specifically, the #break directive is now supported within Velocity scripts in Cascade and within every #foreach loop, there is now a new native reference, $foreach.  The $foreach reference gives access to information about the current loop, like the current index and count through properties: $foreach.index, $foreach.count, $foreach.hasNext, etc.

The following example shows how you can easily reference the current index of an iteration and use this index to reference a corresponding index of a parallel list:


            #set ( $keys = ["first","second","third","fourth"] )  
#set ( $values = ["value 1","value 2","value 3","value 4"] )  
#foreach ( $key in $keys )  
    <li>${key} -- ${values.get($foreach.index)}</li>  
#end
            

Line-by-line explanation:

  1. Creates an array, $keys, containing the values "first", "second", "third" and "fourth".
  2. Creates an array, $values, containing the values "value 1", "value 2", "value 3" and "value 4".
  3. Begins a looping structure which will loop over each item in the $keys array.  
  4. Outputs each item in the $keys array, alongside the corresponding item from the parallel $values array, using the native $foreach.index property to reference the identical index as the current iteration of the $keys list..
  5. Ends loop. 

Additionally, for nested loops, the $foreach reference contains pointers to parent loop structures through $foreach.parent.  The $foreach.parent reference contains all the same properties as $foreach: count, index, hasNext, etc.  You can reference nested loops multiple levels deep using references like $foreach.parent.parent.parent, etc.  Below is an example of how properties of a parent loop can be referenced from within a child loop:


            #set ( $outerList = ["outer 1","outer 2","outer 3","outer 4"] )  
#set ( $innerList = ["inner 1", "inner 2", "inner 3", "inner 4", "inner 5"] )  
#foreach ( $outer in $outerList )  
    <p>${outer}</p>   
    #foreach ( $inner in $innerList )  
        #if ( $foreach.parent.count == 2 )  
            #break  
        #end  
        <p>   ${inner}</p>  
    #end      
#end
            

Line-by-line explanation:

  1. Creates an array, $outerList, containing values "outer 1", "outer 2", "outer 3" and "outer 4".
  2. Creates an array, $innerList, containing values "inner 1", "inner 2", "inner 3", "inner 4" and "inner 5".
  3. Begins a loop over $outerList.
  4. Outputs each value in $outerList.
  5. Begins a nested loop over $innerList.
  6. Tests the current iteration count of the outer loop, using native $foreach.parent.count.
  7. If the iteration count conditions from line 6 are met, stop iteration $innerList only.
  8. Ends #if statement.
  9. Outputs each value in $innerList, indented 3 spaces.
  10. Ends the inner #foreach loop.
  11. Ends the outer #foreach loop.

Including Script Formats

In Cascade Server 7.6 and above, it is possible to include Velocity code from one Script Format in another Script Format using the #import statement.  Below is a simple example of a Velocity macro that is declared in one Format and then included and used in another Format using an import statement.

Format: /_cascade/formats/include/print


            #macro(printElementName $element)  
$element.name  
#end
            

Format: /_cascade/formats/display-elements


            #import('/_cascade/formats/include/print')  
#set($elements = $_XPathTool.selectNodes($contentRoot, '//system-page'))  
  
#foreach($element in $elements)  
    <p>#printElementName($element)</p>  
#end
            

The import statement takes a single argument that is a path to another Format in the system. To import a Format from another Site, prepend the path with 'site://<site name>'. A variable can be supplied to the import statement as well.


            #set($myPath = 'site://example.com/_cascade/formats/include/print')  
#import($myPath)
            

Note that imported Velocity macros can only be used below the line where the Format is included.


            #printElementName($element)  ← Bad, comes before import, will not execute correctly  
#import('/_cascade/formats/include/print')  
#printElementName($element) ← Good, comes after import
            

If for some reason the Format you are trying to include cannot be found, an error will occur when you attempt to test the Format using the Format Editing UI or when viewing a Page that uses the Format.