Velocity Tools

Cascade CMS's Velocity Tools are a collection of functions that can be used to retrieve and manipulate content in conjunction with Apache Velocity Template Language.

Just getting started with Velocity? Review Apache's Velocity 1.7 User Guide  .

Global Variables

Variable Output Description
$currentPage PageAPIAdapter Returns the current page as an API object.
$currentPagePath String Returns the path of the current page.
$currentPageSiteName String Returns the name of the current page's site.

Locator Tool

The Locator Tool retrieves assets located at a given path and optionally within a site with a given siteName as Cascade CMS API objects.

Tip - If a siteName is not provided, the Locator Tool will locate assets within the site where the Format is located. Use the $currentPageSiteName variable to locate assets in the site where the Format is being called from (the current page).

$_.locate

Locate an asset at the given path, with the specified type, and optionally inside of a site with the specified siteName.

Argument Type Description
path String
required
A path to an asset.
type EntityType
required
An asset type. Accepted types:

TYPE_LINKABLE (Pages, Files, and External Links)
TYPE_PAGE
TYPE_FILE
TYPE_FOLDER
TYPE_BLOCK
TYPE_TEMPLATE
TYPE_REFERENCE
TYPE_SYMLINK
TYPE_FORMAT

siteName String
optional
A site name.

$_.locateBlock

Locate a Block at the given path and optionally inside of a site with the specified siteName.

Example:

$_.locateBlock("blocks/index/all-events", "Calendar")
Argument Type Description
path String
required
A path to a Block.
siteName String
optional
A site name.

$_.locateFile

Locate a File at the given path and optionally inside of a site with the specified siteName.

Example:

$_.locateFile("files/logo.png", "Cascade University")
Argument Type Description
path String
required
A path to a File.
siteName String
optional
A site name.

$_.locateFolder

Locate a Folder at the given path and optionally inside of a site with the specified siteName.

Example:

$_.locateFolder("articles/2019", "News")
Argument Type Description
path String
required
A path to a Folder.
siteName String
optional
A site name.

$_.locateFormat

Locate a Format at the given path and optionally inside of a site with the specified siteName.

Example:

$_.locateFormat("_cms/formats/banner", "Cascade University")
Argument Type Description
path String
required
A path to a Format.
siteName String
optional
A site name.

$_.locateLinkable

Locate a Page, File, or External Link at the given path and optionally inside of a site with the specified siteName.

Example:

$_.locateLinkable("student-life/student-portal-link", "Cascade University")
Argument Type Description
path String
required
A path to a Page, File, or External Link.
siteName String
optional
A site name.

$_.locatePage

Locate a Page at the given path and optionally inside of a site with the specified siteName.

Example:

$_.locatePage("about-us/contact", "Cascade University")
Argument Type Description
path String
required
A path to a Page.
siteName String
optional
A site name.

$_.locateReference

Locate a Reference at the given path and optionally inside of a site with the specified siteName.

Example:

$_.locateReference("about-us/contact", "Cascade University")
Argument Type Description
path String
required
A path to a Reference.
siteName String
optional
A site name.

Query API

The Locator Tool can also be used to query for assets using a specified Metadata Set or Content Type. To construct a query:

  • Create the query object with query()
  • Choose to query byMetadataSet() or byContentType()
  • Optionally, set filtering and sorting parameters
  • Execute the query with execute()

Example:

#set ($query = $_.query())
#set ($query = $query.byContentType("Article"))
#set ($query = $query.maxResults(10))
#set ($query = $query.sortBy("startDate"))
#set ($query = $query.sortDirection("desc"))
#set ($results = $query.execute())

Query methods can also be chained. Example:

#set ($results = $_.query().byContentType("Article").maxResults(10).sortBy("startDate").sortDirection("desc").execute())
Tip - Queries return API objects. Use $_PropertyTool.outputProperties($item) to output the properties available when working with an API object.

$_.query()

Creates the query object.

Example:

$_.query()

$_.query().byContentType

Return assets using the Content Type at the path provided.

Notes:

  • Can't be used in conjunction with  byMetadataSet().
  • Querying byContentType() will return only page assets.

Example:

$_.query().byContentType("Article").execute()
Argument Type Description
path String
required
A path to a Content Type with optional site prefix.

$_.query().byMetadataSet

Return assets using the Metadata Set at the path provided.

Notes:

  • Can't be used in conjunction with  byContentType().

Example:

$_.query().byMetadataSet("site://News/Article").execute()
Argument Type Description
path String
required
A path to a Metadata Set with optional site prefix

$_.query().hasMetadata

Return assets with metadata where name is set to value.

Example:

$_.query().byMetadataSet("Article").hasMetadata("department","Biology").execute()
Argument Type Description
name String
required
The name of a field in a Metadata Set.
value String
required
The metadata field value.

$_.query().hasAnyMetadataValues

Return assets with metadata where name is set to any of values.

Example:

$_.query().byMetadataSet("Article").hasAnyMetadataValues("department",["English", "Communications"]).execute()
Argument Type Description
name String
required
The name of a field in a Metadata Set.
values List 
required
A List of metadata field values.

$_.query().hasTag

Return assets that have at least tag assigned.

Example:

$_.query().byMetadataSet("Event").hasTag("Campus Events").execute()
Argument Type Description
tag String
required
The name of a tag.

$_.query().hasAnyTags

Return assets that have any of tags assigned.

Example:

$_.query().byMetadataSet("Event").hasAnyTags(["Campus Events", "Academics"]).execute()
Argument Type Description
tags List 
required
A List of tags.

$_.query().includeBlocks

Include Block assets in the query results.

Example:

$_.query().byMetadataSet("Default").includeBlocks(true).execute()
Argument Type Description
include Boolean 
required
true or false. Default is true.

$_.query().includeFiles

Include File assets in the query results.

Example:

$_.query().byMetadataSet("Default").includeFiles(true).execute()
Argument Type Description
include Boolean 
required
true or false. Default is true.

$_.query().includeFolders

Include Folder assets in the query results.

Example:

$_.query().byMetadataSet("Default").includeFolders(true).execute()
Argument Type Description
include Boolean 
required
true or false. Default is true.

$_.query().includePages

Include Page assets in the query results.

Example:

$_.query().byMetadataSet("Default").includePages(true).execute()
Argument Type Description
include Boolean 
required
true or false. Default is true.

$_.query().indexableOnly

Include only assets enabled for indexing in the query results.

Notes:

  • Assets disabled for indexing by their folder hierarchy but not at the individual asset level will still be returned.
  • When set to true, results must also have an empty Start Date or a Start Date in the past and an empty End Date or an End Date in the future.

Example:

$_.query().byContentType("Event").indexableOnly(true).execute()
Argument Type Description
include Boolean 
required
true or false. Default is true.

$_.query().maxResults

Limit the number of assets returned by the query to the amount specified.

Notes:

  • Default is 100 assets.
  • Maximum is 2000 assets.
  • The number of assets to be queried is not limited, but the maximum number of assets that can be returned from the results of the query is limited to 2000.

Example:

$_.query().byContentType("Article").maxResults(5).execute()
Argument Type Description
amount Integer  
required

An integer 1 through 2000 or -1 (returns the maximum).


$_.query().publishableOnly

Include only assets enabled for publishing in the query results.

Notes:

  • Assets disabled for publishing by their folder hierarchy but not at the individual asset level will still be returned.

Example:

$_.query().byContentType("Article").publishableOnly(true).execute()
Argument Type Description
include Boolean  
required

true or false.


$_.query().searchAcrossAllSites

Return assets from all sites in the query results.

Notes:

  • Can't be used in conjunction with  siteName().

Example:

$_.query().byContentType("Event").searchAcrossAllSites().execute()

$_.query().siteName

Return assets from the specified site in the query results.

Notes:

  • Can't be used in conjunction with  searchAcrossAllSites().

Example:

$_.query().byContentType("Event").siteName("Calendar").execute()
Argument Type Description
name String  
required

The name of a site.


$_.query().sortBy

Sort the query results by the specified field.

Notes:

  • Only one sortBy() call is used per query.
  • Use in conjunction with sortDirection() to specify direction of sort.

Example:

$_.query().byContentType("Profile").sortBy("title").execute()
Argument Type Description
field String  
required

"author"
"created"
"description"
"displayName"
"endDate"
"keywords"
"modified"
"name"
"path"
"reviewDate"
"startDate"
"summary"
"title"
"teaser"


$_.query().sortDirection

Used in conjunction with sortBy(), specify the direction of the sort.

Notes:

  • Only one  sortDirection() call is used per query.

Example:

$_.query().byContentType("Article").sortBy("startDate").sortDirection("desc").execute()
Argument Type Description
direction String  
required

"asc" or "desc"

Date Tool

The Date Tool allows users to retrieve, format, and compare datetime values. Timestamps returned in Index Block XML are Unix timestamps in milliseconds and can be converted to Java Dates   using the Date Tool.

Full API documentation:


$_DateTool.difference

Returns a String representing the difference between now and then.

Examples:

$_DateTool.whenIs(1578526435000, 1577836800000)
## Expected output: 2 days earlier
#set ($currentDate = $_DateTool.getDate())
#set ($pubDate = $currentPage.lastPublishedOn)
$_DateTool.whenIs($currentDate, $pubDate)
## Expected output: 2 weeks earlier
Argument Type Description
now Date / Long 
required
A Date or a Number representing a Unix timestamp in milliseconds.
then Date / Long 
required
A Date or a Number representing a Unix timestamp in milliseconds.

$_DateTool.format

Returns a String representing a date in a specified format.

Examples:

$_DateTool.format('medium', $date)
$_DateTool.format('EEEE MM/dd/yy', $date)
Argument Type Description
format String
optional
A String representing the desired date format. See Java's documentation for predefined formats   and customizable simple date formats  .
date Date or Calendar
required
A Date or Calendar.

$_DateTool.getCalendar

Returns the current date as a Calendar.

Example:

$_DateTool.getCalendar()

$_DateTool.getDate

Returns a date or the current date as a Date.

Examples:

$_DateTool.getDate()
#set ($page = $_XPathTool.selectSingleNode($contentRoot, "//calling-page/system-page"))
#set ($pubDate = $page.getChild("last-published-on").value)
$_DateTool.getDate($pubDate)
Argument Type Description
date String  
optional
A Unix timestamp in milliseconds.

$_DateTool.getDay

Returns a Number representing the day in a date or the current date.

Example:

$_DateTool.getDay()
Argument Type Description
date Date or Calendar  
optional
A Date or Calendar.

$_DateTool.getMonth

Returns a Number representing the month in a date or the current date.

Note: In Java, the first month of the year in the Gregorian and Julian calendars is JANUARY which is 0.

Example:

$_DateTool.getMonth()
Argument Type Description
date Date or Calendar  
optional
A Date or Calendar.

$_DateTool.getTime

Returns a Number representing the current time.

Example:

$_DateTool.getTime()

$_DateTool.getValue

Returns an Integer representing the value for the field in the date.

Example:

$_DateTool.getValue(1, $date)
Argument Type Description
field Integer
required

An Integer representing a Calendar field type. Available types:

0 = Era
1 = Year
2 = Month
3 = Week of Year
4 = Week of Month
5 = Day of Month
6 = Day of Year
7 = Day of Week
8 = Day of Week in Month
9 = AM/PM
10 = Hour
11 = Hour of Day
12 = Minute
13 = Second
14 = Millisecond
15 = Zone offset
16 = DST offset

date Date
required
A Date.

$_DateTool.getYear

Returns a Number representing the year in a date or the current date.

Example:

$_DateTool.getYear()
Argument Type Description
date Date or Calendar  
optional
A Date or Calendar.

$_DateTool.toDate

Returns a date in the specified format as a Date.

Example:

#set ($date = $currentPage.getStructuredDataNode("date").textValue)
#set ($date = $_DateTool.toDate("MM-dd-yyyy",$date))
$_DateTool.format("EEEE, MMMM dd, yyyy", $date)
Argument Type Description
format String  
required
A String representing a date format.
date Object  
required
An Object representing a date.

$_DateTool.toDays

Returns a Number representing the number of days between Unix Time 0 (midnight UTC/GMT on January 1, 1970) and a time.

Example:

$_DateTool.toDays(1577836800000)
## Expected output: 18262
Argument Type Description
time Long 
required
A Number representing time in milliseconds.

$_DateTool.toHours

Returns a Number representing the number of hours between Unix Time 0 (midnight UTC/GMT on January 1, 1970) and a time.

Example:

$_DateTool.toHours(1577836800000)
## Expected output: 438288
Argument Type Description
time Long 
required
A Number representing time in milliseconds.

$_DateTool.toMinutes

Returns a Number representing the number of minutes between Unix Time 0 (midnight UTC/GMT on January 1, 1970) and a time.

Example:

$_DateTool.toMinutes(1577836800000)
## Expected output: 26297280
Argument Type Description
time Long 
required
A Number representing time in milliseconds.

$_DateTool.toMonths

Returns a Number representing the number of months between Unix Time 0 (midnight UTC/GMT on January 1, 1970) and a time.

Example:

$_DateTool.toMonths(1577836800000)
## Expected output: 608
Argument Type Description
time Long 
required
A Number representing time in milliseconds.

$_DateTool.toSeconds

Returns a Number representing the number of seconds between Unix Time 0 (midnight UTC/GMT on January 1, 1970) and a time.

Example:

$_DateTool.toSeconds(1577836800000)
## Expected output: 1577836800
Argument Type Description
time Long 
required
A Number representing time in milliseconds.

$_DateTool.toWeeks

Returns a Number representing the number of weeks between Unix Time 0 (midnight UTC/GMT on January 1, 1970) and a time.

Example:

$_DateTool.toWeeks(1577836800000)
## Expected output: 2608
Argument Type Description
time Long 
required
A Number representing time in milliseconds.

$_DateTool.toYears

Returns a Number representing the number of years between Unix Time 0 (midnight UTC/GMT on January 1, 1970) and a time.

Example:

$_DateTool.toYears(1577836800000)
## Expected output: 50
Argument Type Description
time Long 
required
A Number representing time in milliseconds.

$_DateTool.whenIs

Returns a String representing the difference between now and then or between the current time and then.

Examples:

$_DateTool.whenIs(1578526435000, 1577836800000)
## Expected output: -2 days
#set ($pubDate = $currentPage.lastPublishedOn)
$_DateTool.whenIs($pubDate)
## Expected output: -2 weeks
Argument Type Description
now Date / Long 
optional
A Date or a Number representing a Unix timestamp in milliseconds.
then Date / Long 
required
A Date or a Number representing a Unix timestamp in milliseconds.

Display Tool

The Display Tool provides methods for controlling the display of references.


$_DisplayTool.alt

Returns the value of the object if defined, otherwise returns null or alternate.

Example:

$_DisplayTool.alt($title,"No title provided.")
Argument Type Description
value Object
required
Any object.
alternate Object
optional
Any object.

$_DisplayTool.br

Returns a String in which new line characters (\n) are prepended with HTML line break tags (<br/>).

Example:

$_DisplayTool.br("Here is a String with
a line break.")
## Expected output: Here is a string with<br/>a line break.
Argument Type Description
message String
required
A String.

$_DisplayTool.capitalize

Returns a String in which the first letter is capitalized.

Example:

$_DisplayTool.capitalize("here is a String.")
## Expected output: Here is a String.
Argument Type Description
message String
required
A String.

$_DisplayTool.cell

Returns a String that is truncated or padded to length and appended with an optional suffix if truncated.

Example:

$_DisplayTool.cell("Here is a String over 10 characters long.",10,"...")
## Expected output: Here is...
Argument Type Description
message String
required
A String.
length Integer
optional

The number of characters to which the message will be truncated or padded (with spaces).

The default is 30.

suffix

String
optional

A suffix to append to the message if truncated.

The default is "..."


$_DisplayTool.list

Returns String representing a list separated by a separator and optional lastSeparator.

Example:

$_DisplayTool.list(["A", "B", "C"], ", ", ", or ")
## Expected output: A, B, or C
Argument Type Description
list List
required
A List of any Objects.
separator String
optional

A String to use as a separator.

The default is ", ".

lastSeparator

String
optional

A String to use as a separator between the penultimate and last items in the list.

The default is " and ".


$_DisplayTool.message

Returns String message formatted with values.

Example:

$_DisplayTool.message("{0}, {1}, or {2}", "A", "B", "C")
## Expected output: A, B, or C
Argument Type Description
message String
required
A String.
values Object
required

Any number of input Objects.


$_DisplayTool.plural

Returns a singular or plural word depending on the amount. If an alternative plural is not provided, basic rules of English pluralization will be used.

Example:

$_DisplayTool.plural(3,"mouse","mice")
## Expected output: mice
Argument Type Description
amount Integer
required
An Integer.
singular String
required

A singular word.

plural

String
optional

A plural word.


$_DisplayTool.space

Returns a String containing the specified number of spaces.

Example:

$_DisplayTool.space(3)
Argument Type Description
number Integer
required
Number of space characters.

$_DisplayTool.stripTags

Returns a String without HTML tags or with only specified allowedTags.

Example:

$_DisplayTool.stripTags("<p>Here is a <code>String</code> with <strong>HTML</strong> tags.</p>","p","code")
## Expected output: <p>Here is a <code>String</code> with HTML tags.</p>
Argument Type Description
html String
required
A String.
allowedTags String
optional

Any number of allowed HTML tags.


$_DisplayTool.truncate

Returns a String truncated to 30 characters or the specified length, appended with "..." or an optional suffix if truncated, and optionally truncated at the end of a word.

Example:

$_DisplayTool.truncate("Here is a truncated String.",15,"...",true)
## Expected output: Here is a...
Argument Type Description
message String
required
A String.
length Integer
optional

A maximum length.

Default is 30.

 

suffix

String
optional

A suffix to append to the string if truncated.

Default is "...".

truncateAtWord

Boolean
optional

true or false

Default is false.

If true, the output will be truncated at the space closest to the end of the String.


$_DisplayTool.uncapitalize

Returns a String in which the first letter is uncapitalized.

Example:

$_DisplayTool.uncapitalize("Here is a String.")
## Expected output: here is a String.
Argument Type Description
message String
required
A String.

Escape Tool

The Escape Tool contains programming language-specific escape functionality, as well as methods and properties for outputting safely escaped special characters.

Full API documentation:


$_EscapeTool.getB / $_EscapeTool.getBackslash

Returns a backslash.

Example:

$_EscapeTool.getB()
## Expected output: \

$_EscapeTool.getD / $_EscapeTool.getDollar

Returns a dollar sign.

Example:

$_EscapeTool.getD()
## Expected output: $

$_EscapeTool.getE / $_EscapeTool.getExclamation

Returns an exclamation mark.

Example:

$_EscapeTool.getE()
## Expected output: !

$_EscapeTool.getH / $_EscapeTool.getHash

Returns a hash / pound sign.

Example:

$_EscapeTool.getH()
## Expected output: #

$_EscapeTool.getN / $_EscapeTool.getNewLine

Returns a new line character.

Example:

$_EscapeTool.getN()
## Expected output: \n

$_EscapeTool.getQ / $_EscapeTool.getQuote

Returns a quotation mark.

Example:

$_EscapeTool.getQ()
## Expected output: "

$_EscapeTool.getS / $_EscapeTool.getSingleQuote

Returns a single quote / apostrophe.

Example:

$_EscapeTool.getS()
## Expected output: '

$_EscapeTool.html

Returns an escaped HTML String.

Notes:

  • Due to Cascade CMS's XHTML validation, using $_EscapeTool.xml() is recommended even when escaping content for HTML output.

Example:

$_EscapeTool.html('Here is a String with an ampersand (&).')
## Expected output: Here is a String with an ampersand (&amp;).
Argument Type Description
content String
required
A String.

$_EscapeTool.javascript

Returns an escaped JavaScript String.

Example:

$_EscapeTool.javascript('Here is a String with "quotation marks".')
## Expected output: Here is a String with \"quotation marks\".
Argument Type Description
content String
required
A String.

$_EscapeTool.unescapeHtml

Returns an unescaped String containing HTML.

Example:

$_EscapeTool.unescapeHtml('Here is a String with an  escaped ampersand (&amp;).')
## Expected output: Here is a String with an escaped ampersand (&).
Argument Type Description
content String
required
A String.

$_EscapeTool.unescapeJavaScript

Returns an unescaped String containing JavaScript.

Example:

$_EscapeTool.unescapeJavaScript('if (i === \"foo\")')
## Expected output: if (i === "foo").
Argument Type Description
content String
required
A String.

$_EscapeTool.unescapeXml

Returns an unescaped String containing XML.

Example:

$_EscapeTool.unescapeHtml('&lt;foo&gt;bar&lt;/foo&gt;')
## Expected output: <foo>bar</foo>
Argument Type Description
content String
required
A String.

$_EscapeTool.unicode

Returns a String representing a Unicode character.

Example:

$_EscapeTool.unicode('004D')
## Expected output: M
Argument Type Description
code String
required
A hexidecimal code representing a Unicode character.

$_EscapeTool.url

Returns an escaped URL String.

Example:

$_EscapeTool.url('www.example.com/page?key=value')
## Expected output: www.example.com%2Fpage%3Fkey%3Dvalue
Argument Type Description
content String
required
A String.

$_EscapeTool.xml

Returns an escaped XML String.

Example:

$_EscapeTool.html('Here is a String with an ampersand (&).')
## Expected output: Here is a String with an ampersand (&amp;).
Argument Type Description
content String
required
A String.

Field Tool

The Field Tool provides access to Java public constant values, which are otherwise inaccessible in Velocity scripts.

Full API documentation:


$_FieldTool.in

Returns a Classes' public static variables.

Examples:

$_FieldTool.in($_DateTool.getCalendar()).JANUARY
## Expected output: 0

Example adding time to a Calendar:

#set ($date = $_DateTool.getDate())
#set ($calendar = $_DateTool.getCalendar())
$calendar.add($_FieldTool.in($calendar).DAY_OF_YEAR, 1)
<p>Today = ${date}</p>
<p>Tomorrow = ${calendar.getTime()}</p>
Argument Type Description
object Object 
required
An Object, which gives access to the Classes' public static variables

List Tool

The List Tool provides operations to perform on lists or arrays.

$_ListTool.removeNull

Removes items from a List that either do not have a given propertyName or it is null.

Notes:

  • Set this to a variable to retain the removed items for processing.

Example:

#set ($articles = $_.query().byContentType("Article").execute())
#set ($removed = $_ListTool.removeNull($articles, "metadata.startDate"))
Argument Type Description
list List
required
A List of any objects.
propertyName String
required
 A String representing a property name.

$_ListTool.reverse

Reverses a List.

Example:

$_ListTool.reverse(["A","B","C"])
## Expected output: [C, B, A]
Argument Type Description
list List
required
A List of any objects.

$_ListTool.toList

Converts an Array to a List.

Example:

#set ($categories = $currentPage.metadata.getDynamicField("categories"))
#set ($categories = $_ListTool.toList($categories.values))
Argument Type Description
array Array
required
An Array of any objects.

Math Tool

The Math Tool provides convenience methods for converting numeric text to real numbers and performing various mathematical operations.

Full API documentation:


$_MathTool.abs

Returns the absolute value of a number.

Example:

$_MathTool.abs(-3)
## Expected output: 3
Argument Type Description
number Number
required
A number.

$_MathTool.add

Returns the sum of numbers.

Example:

$_MathTool.add(12,30)
## Expected output: 42
Argument Type Description
numbers Number
required
Any number of Numbers.

$_MathTool.ceil

Returns the smallest integer that is not less than the given number.

Example:

$_MathTool.ceil(3.14159)
## Expected output: 4
Argument Type Description
number Number
required
A number.

$_MathTool.div

Returns the quotient of numbers or null if any denominator equals zero.

Example:

$_MathTool.div(9,3)
## Expected output: 3
Argument Type Description
numbers Numbers
required
Any number of Numbers.

$_MathTool.floor

Returns the integer portion of number.

Example:

$_MathTool.floor(3.14159)
## Expected output: 3
Argument Type Description
number Number
required
A Number.

$_MathTool.getRandom

Returns a pseudo-random Double greater than or equal to 0.0 and less than 1.0.

Example:

$_MathTool.getRandom()

$_MathTool.idiv

Returns the result of performing integer division on number1 and number2.

Example:

$_MathTool.idiv(9.33,3.14)
## Expected output: 3
Argument Type Description
number1 Number
required
A Number.
number2 Number
required
A Number.

$_MathTool.max

Returns the maximum of numbers.

Example:

$_MathTool.max(7,23,11)
## Expected output: 23
Argument Type Description
numbers Numbers
required
Any number of Numbers.

$_MathTool.min

Returns the minimum of numbers.

Example:

$_MathTool.min(7,23,11)
## Expected output: 7
Argument Type Description
numbers Numbers
required
Any number of Numbers.

$_MathTool.mod

Returns the result of performing integer modulus on number1 and number2.

Example:

$_MathTool.mod(9.33,3.14)
## Expected output: 0
Argument Type Description
number1 Number
required
A Number.
number2 Number
required
A Number.

$_MathTool.mul

Returns the product of numbers.

Example:

$_MathTool.min(6,7)
## Expected output: 42
Argument Type Description
numbers Numbers
required
Any number of Numbers.

$_MathTool.pow

Returns the result of number1 to the power of number2.

Example:

$_MathTool.pow(3,3)
## Expected output: 27
Argument Type Description
number1 Number
required
A Number.
number2 Number
required
A Number.

$_MathTool.random

Returns a pseudo-random number greater than or equal to number1 and less than number2.

Notes:

  • If both arguments are whole numbers then the returned number will also be, otherwise a Double will be returned.

Example:

$_MathTool.random(1,10)
Argument Type Description
number1 Number
required
A Number.
number2 Number
required
A Number.

$_MathTool.round

Returns number rounded to the nearest whole integer.

Example:

$_MathTool.round(3.14159)
## Expected output: 3
Argument Type Description
number Number
required
A Number.

$_MathTool.roundTo

Returns number rounded to the specified number of decimalPlaces.

Example:

$_MathTool.roundTo(2,3.14159)
## Expected output: 3.14
Argument Type Description
decimalPlaces Number
required
The number of decimal places to round to.
number Number
required
A Number.

$_MathTool.sub

Returns the difference of numbers (subtracted in order).

Example:

$_MathTool.sub(10,7)
## Expected output: 3
Argument Type Description
numbers Numbers
required
Any number of Numbers.

$_MathTool.toDouble

Returns number as a Double.

Example:

$_MathTool.toDouble(3)
## Expected output: 3.0
Argument Type Description
number Object
required
Any Object.

$_MathTool.toInteger

Returns number as an Integer.

Example:

$_MathTool.toInteger(3.14159)
## Expected output: 3
Argument Type Description
number Object
required
Any Object.

$_MathTool.toNumber

Returns number as a Number.

Example:

$_MathTool.toNumber("3")
## Expected output: 3
Argument Type Description
number Object
required
Any Object.

Number Tool

The Number Tool contains several methods for formatting various types of numeric data.

Full API documentation:


$_NumberTool.currency

Returns a String representing object formatted as currency.

Example:

$_NumberTool.currency(3.14159)
## Expected output: $3.14
Argument Type Description
object Object
required
Any Object.

$_NumberTool.format

Returns a String representing object in the given format.

Example:

$_NumberTool.format("integer",3.14159)
## Expected output: 3
Argument Type Description
format String
optional
"default" (number)
"number"
"currency"
"percent"
"integer"
object Object
required
Any Object.

$_NumberTool.integer

Returns a String representing object formatted as an integer.

Example:

$_NumberTool.integer(3.14159)
## Expected output: 3
Argument Type Description
object Object
required
Any Object.

$_NumberTool.number

Returns a String representing object formatted as a number.

Example:

$_NumberTool.number(3.14159)
## Expected output: 3.142
Argument Type Description
object Object
required
Any Object.

$_NumberTool.percent

Returns a String representing object formatted as a percentage.

Example:

$_NumberTool.percent(3.14159)
## Expected output: 314%
Argument Type Description
object Object
required
Any Object.

$_NumberTool.toNumber

Returns a Number representing object in the given format or null if no conversion is possible.

Example:

$_NumberTool.toNumber("percent","314%")
## Expected output: 3.14
Argument Type Description
format String
optional
"default" (number)
"number"
"currency"
"percent"
"integer"
object Object
required
Any Object.

Property Tool

The Property Tool can be used to view and evaluate the properties of Cascade CMS API objects.


$_PropertyTool.isEmpty

Returns  true if the object is null, an empty string, or contains only whitespace characters, otherwise  false.

Example:

$_PropertyTool.isEmpty($category.values[0])
Argument Type Description
object Object
required
An API object.

$_PropertyTool.isNull

Returns  true if object is null, otherwise  false.

Example:

$_PropertyTool.isNull($category)
Argument Type Description
object Object
required
An API object.

$_PropertyTool.outputFirstNotEmpty

Returns a string of the first non-empty property in the list of properties provided.

Example:

$_PropertyTool.outputFirstNotEmpty($currentPage.metadata.title, $currentPage.getStructuredDataNode("heading").textValue, $currentPage.name)
Argument Type Description
properties Object
required
A list of any number of API object properties

$_PropertyTool.outputProperties

Return a list of all available properties and methods an object exposes as well its type.

Example:

$_PropertyTool.outputProperties($currentPage)
Argument Type Description
object Object
required
An API object.

Regex Tool

The Regex Tool provides the ability to work with complex regular expressions.

$_RegexTool.compile

Returns a Pattern object   representing a valid regular expression.

Examples:

$_RegexTool.compile("^[a-zA-Z0-9]*$")

#set ($text = "A string to search for links containing the pattern https:// .")
#set ($patternString = ".*https://.*")
#set ($pattern = $_RegexTool.compile($patternString))
#set ($matcher = $pattern.matcher($text))
#set ($matches = $matcher.matches())
## Expected output: true
Argument Type Description
regex String 
required
A String representing a valid regular expression

Serializer Tool

The Serializer Tool provides a way to serialize JDOM elements as XML or JSON. This makes it possible to do things like output the markup of a WYSIWYG without having to output each node in the JDOM tree manually.


$_SerializerTool.serialize

Returns a String representing element as XML.

Example:

<wysiwyg>
<p>Here is a <strong>WYSIWYG</strong> element.</p>
<p>It has multiple lines.</p>
</wysiwyg>
#set ($wysiwyg = $_XPathTool.selectSingleNode($contentRoot, "//wysiwyg"))
#set ($serialized = $_SerializerTool.serialize($wysiwyg,true))
## Expected output:
<p>Here is a <strong>WYSIWYG</strong> element.</p>
<p>It has multiple lines.</p>
Argument Type Description
element Element
required
Any Element.
removeRoot Boolean
required

true or false

If true the root element of the Element will not be included in the output.


$_SerializerTool.toJson

Returns a String representing element or xml as JSON.

Example:

<a>
<b>B</b>
<c>C</c>
</a>
#set ($a = $_XPathTool.selectSingleNode($contentRoot, "//a"))
$_SerializerTool.toJson($a, true) ## Expected output:
{"b":"B","c":"C"}
Argument Type Description
element / xml Element / String
required
Any Element or String.
removeRoot Boolean
required

true or false

If true the root element of the Element or String will not be included in the output.

Sort Tool

The Sort Tool is modeled after the <xsl:sort/> directive.


$_SortTool.addSortCriterion

Adds a new set of parameters to be used during the next sort().

Notes:

  • Defaults will be used if input values are not recognized.
  • This method can be called multiple times to apply any number of criteria.

Example:

$_SortTool.addSortCriterion("title", "en", "text", "ascending", "upper-first")
Argument Type Description
xpath String 
required
XPath specifying the node/value to sort on.
language String 
required

A lowercase two-letter ISO-639 code. Default is "en".

dataType String 
required

The type of data. Default is "text".

"text"
"number"
"qname"

order String 
required

The sort order. Default is "ascending".

"ascending"
"descending"

caseOrder String 
required

If text, choose whether to sort by uppercase or lowercase letters first. Default is "lower-first".

"lower-first"
"upper-first"


$_SortTool.sort

Returns a sorted List based on the values from  addSortCriterion(), otherwise defaults are used.

Examples:

$_SortTool.addSortCriterion("name", "en", "text", "ascending", "upper-first")
$_SortTool.sort($pages)
#set ($currentFolderChildren = $currentPage.parentFolder.children)
#set ($sorted = $_SortTool.sort($currentFolderChildren,"name"))
$_SortTool.sort($courses, "metadata.dynamicField(course-number).value")
$_SortTool.sort($articles,"structuredDataNode(main/header).textValue:desc")
Argument Type Description
objects List 
required
A List of Objects.
property / properties String / List
optional

A String representing a property or a List of properties (in order) to sort by.

String Tool

The String Tool provides methods to find and return content within a string.

$_StringTool.generateUUID

Returns a String that represents a randomly generated UUID.

Example:

$_StringTool.generateUUID()
## Sample output: 29ecf0f3-7db4-41b5-94a2-3e170338c3b5

$_StringTool.getStringBuilder

Returns a new StringBuilder instance.

Example:

#set ($stringBuilder = $_StringTool.getStringBuilder())
#set ($_void = $stringBuilder.append("foo"))
#set ($_void = $stringBuilder.append("+"))
#set ($_void = $stringBuilder.append("bar"))
$stringBuilder
## Sample output: foo+bar

$_StringTool.substringAfter

Returns a String that exists after the needle in the haystack.

Example:

$_StringTool.substringAfter("aaabbbccc", "bbb")
## Expected output: ccc
Argument Type Description
haystack String 
required
A String to search within.
needle String 
required
A String to search for.

$_StringTool.substringBefore

Returns a String that exists before the needle in the haystack.

Example:

$_StringTool.substringBefore("aaabbbccc", "bbb")
## Expected output: aaa
Argument Type Description
haystack String 
required
A String to search within.
needle String 
required
A String to search for.

XPath Tool

The XPath Tool allows users to query JDOM XML using an XPath expression. A full list of available methods on the XPath Tool can be found in the JDOM XPath API   .

Tip - Just getting started with XPath? Check out this tutorial on XPath and XPath Syntax   .

$_XPathTool.selectNodes

Returns a List of nodes matching a given xpath expression within content.

Example:

#set ($pages = $_XPathTool.selectNodes($contentRoot,"//system-page"))
Argument Type Description
content XMLElement
required
An XML Element.
xpath String 
required
An XPath expression.

$_XPathTool.selectSingleNode

Returns a Node matching a given xpath expression within content.

Example:

#set ($currentPage = $_XPathTool.selectSingleNode($contentRoot,"//system-page[@current]"))
Argument Type Description
content XMLElement
required
An XML Element.
xpath String 
required
An XPath expression.