Velocity API Available in Templates

Query result

$result

The variable $result contains the result from your Converter.

To learn more about result formatting, refer to Writing Your Own PocketQuery Templates and Writing Your Own PocketQuery Converters.

Example

Result passed from Converter

{
  a: 1,
  b: 2
}

Template

<p>$result</p>
#foreach($elem in $result.entrySet())
  <p>$elem.key: $elem.value</p>
#end

Result

{a=1,b=2}
a: 1
b: 2

Query Parameters

$queryParameters

Allows you to access the parameter values passed to your Query. If your Query statement makes use of wildcards, you can also find their values in this Map.

Example

Query Statement

SELECT *
FROM table
WHERE x = :parameter
AND y = :@space.key

Template

<p>$queryParameters</p>
<p>$queryParameters.get("parameter")</p>
<p>$queryParameters.get("@space.key")</p>

Result

{parameter=VALUE, @space.key=SPACE}
VALUE
SPACE

Template insertion by Template ID

$PQ.template(
  templateId
)

templateId: string

Renders another Template inside the caller Template.

It requires a Template ID, which is a unique identifier of the template you want to parse (you can obtain it in the Template administration). You can call $PQ.template("default") to render the default Template.

Warning: For each Query execution, $PQ.template and $PQ.templateByName can be called to a maximum of 15 times combined.

Example

Template 1 (main)

<p>I am the first template</p>
$PQ.template("cd789c83-e523-0ad1-ba66-61pl84c85f11")

Template 2 (called)

<p>I am the second template</p>

Result

I am the first template
I am the second template

Macro execution

$PQ.renderPocketQueryMacro(
  queryId,
  parameters?
)

queryId: string
parameters: map (optional)

Executes another Query (including its Converter and Template) and returns the rendered result (as a Velocity template code). If you are looking to just get the raw result of another Query, use $PQ.executeQuery instead.

It requires 1 parameter: queryId, which is the ID of the Query to be executed (it can be obtained in the Query administration). The second argument is required in the case where the executed Query contains parameters. In that case, these parameters must be provided.

Example

$PQ.renderPocketQueryMacro("er989c83-e563-12d1-hj23-61pl84c85f56")
$PQ.renderPocketQueryMacro("81270amm-9ij6-kms2-l298-91p78s9852pl", {
  "parameters": {
    "country": "Germany",
    "city": "Munich"
  }
})

Query execution

$PQ.executeQuery(
  queryId,
  parameters?
)

queryId: string
parameters: map (optional)

Executes another Query and returns the result (without applying Converter or Template). This allows you to work with the result of another Query within your Template. If you are looking to directly render another Query, use $PQ.renderPocketQueryMacro instead.

It requires 1 parameter: queryId, which is the ID of the Query to be executed (it can be obtained in the Query administration). The second argument is required in the case where the executed Query contains parameters. In that case, these parameters must be provided.

Example

#set($myResult = $PQ.executeQuery("f3f307b2-50b9-4549-be2d-5d6b74db7649"))

## From here on you can use $myResult just like $result
#foreach ($row in $myResult)
  <div>
    #foreach ($column in $row)
      <span>$!column <span>
    #end
  </div>
#end

Locale (localization)

$PQ.getLocale(
  languageKey,
  countryKey?
)

languageKey: string
countryKey: string (optional)

Returns a ‘Locale’ (an object containing localization details) based on required country and language. This object is required for some other helpers to adjust their results to your location and language.

It requires 1 parameter: language key. If you want to be more specific (suitable for english-speaking countries), you can also optionally provide country key parameter.

The languageKey parameter refers to language identifier according to RFC-4646/4647.
The countryKey parameter is a country code according to ISO-3166 standard.

Example

#set ($czechLocale = $PQ.getLocale("cs", "CZ"))
#set ($germanLocale = $PQ.getLocale("de", "DE"))
#set ($canadianLocaleEn = $PQ.getLocale("en", "CA"))
#set ($canadianLocaleFr = $PQ.getLocale("fr", "CA"))

<p>$czechLocale.getDisplayCountry(): $czechLocale.getDisplayLanguage()</p>
<p>$germanLocale.getDisplayCountry(): $germanLocale.getDisplayLanguage()</p>
<p>$canadianLocaleEn.getDisplayCountry(): $canadianLocaleEn.getDisplayLanguage()</p>
<p>$canadianLocaleFr.getDisplayCountry(): $canadianLocaleFr.getDisplayLanguage()</p>

Result

Czech Republic: Czech
Germany: German
Canada: English
Canada: French

Random UUID

$PQ.randomUUID()

Generates a random UUID String that can be used to create a unique identifier within a Template.
This is useful for Templates with JavaScript operating on the Query result, in cases where a Template is executed multiple times on the same page. This might be the case, for example, when a Query is used multiple times on a page with possibly different Query parameters.

Format date and time

$PQ.formatDate(
  timestamp, 
  format,
  timezone?
)

timezone: string
timestamp: number
format: string

Formats a date (as Unix Timestamp) into a human-readable format.

It accepts 2 parameters: timestamp, date format, and optionally timezone.
The timestamp parameter is a Unix timestamp in milliseconds.
The date format parameter is a date-time pattern, corresponding to date format standards.
The timezone parameter is a Time Zone in GMT format (e.g. “GMT”, “GMT-2”, “GMT+6”…), default is “GMT”.

Example

<p>$PQ.formatDate(1615973113000, "yyyy-MM-dd HH:mm:ss", "GMT")<p>
<p>$PQ.formatDate(1615973113000, "yyyy-MM-dd HH:mm:ss", "GMT+8")<p>
<p>$PQ.formatDate(1615973113000, "yyyy-MM-dd HH:mm:ss", "GMT+2")<p>
<p>$PQ.formatDate(1615973113000, "yyyy-MM-dd HH:mm:ss", "GMT-10")<p>

Result

2021-03-17 09:25:13
2021-03-17 17:25:13
2021-03-17 11:25:13
2021-03-16 23:25:13

Parse date and time

$PQ.parseDate(
  dateAsString, 
  format,
  timezone?
)

timezone: string
dateAsString: string
format: string

Converts a string representation of a date into a Unix Timestamp.

It requires 2 parameters: string representation of date, date format, and optionally timezone.

The date parameter is a date in string format.
The date format parameter is a date-time pattern, corresponding to date format standards.
The timezone parameter is a Time Zone in GMT format (e.g. “GMT”, “GMT-2”, “GMT+6”…), default is “GMT”.

Example

<p>$PQ.parseDate("2021-03-17 09:25:13","yyyy-MM-dd HH:mm:ss", "GMT")</p>
<p>$PQ.parseDate("2021-03-17 17:25:13","yyyy-MM-dd HH:mm:ss", "GMT+8")</p>
<p>$PQ.parseDate("2021-03-17 11:25:13","yyyy-MM-dd HH:mm:ss", "GMT+2")</p>
<p>$PQ.parseDate("2021-03-16 23:25:13","yyyy-MM-dd HH:mm:ss", "GMT-10")</p>

Result

1615973113000
1615973113000
1615973113000
1615973113000

Localized calendar

$PQ.getCalendar(
  locale,
  timezone?
)

locale: localization
timezone: string

Returns a new localized java.util.calendar instance.

It requires 2 parameters: localization and timezone.

The locale parameter is a Locale object described above.
The timezone parameter is a Time Zone in GMT format (e.g. “GMT”, “GMT-2”, “GMT+6”…), default is “GMT”.

Example

#set ($canadianLocaleEn = $PQ.getLocale("en", "CA"))
#set ($localizedCalendarCa = $PQ.getCalendar($canadianLocaleEn, "GMT-3"))
<p>$localizedCalendarCa.getTimeZone().getID()</p>

Result

GMT-03:00

Currency formatter

$PQ.formatCurrency(
  locale, 
  amount
)

locale: localization
amount: number

Formats a number as a currency.

It requires 2 parameters: localization and amount.

The locale parameter is a Locale object described above.
The amount is a number (format long, double, or int), which will be formatted.

Example

#set ($czechLocale = $PQ.getLocale("cs", "CZ"))
#set ($germanLocale = $PQ.getLocale("de", "DE"))
#set ($canadianLocaleEn = $PQ.getLocale("en", "CA"))
#set ($canadianLocaleFr = $PQ.getLocale("fr", "CA"))

<p>$PQ.formatCurrency($czechLocale, 10.0)</p>
<p>$PQ.formatCurrency($germanLocale, 10.0)</p>
<p>$PQ.formatCurrency($canadianLocaleEn, 10.0)</p>
<p>$PQ.formatCurrency($canadianLocaleFr, 10.0)</p>

Result

CZK 10.00
10,00 €
$10.00
10,00 $

Markdown formatter

$PQ.markdown(
  markdownText
)

markdownText: string

Formats Markdown text into HTML.

1 parameter is required: the Markdown text to be formatted.

Example

<p>$PQ.markdown("## Greetings")</p>
<p>$PQ.markdown("**Hello!!** I am greeting you")</p>

Result (user sees rendered markup)

<p><h2>Greetings</h2></p>
<p><strong>Hello!!</strong> I am greeting you</p>

New List

$PQ.newList(
  items?
)

items: enumeration (optional)

Creates a new list of items.

It accepts an enumeration of list items. The number of items is not limited. On the returned list, you can call standard Java lists methods.

Example

#set ($listOfNumbers = $PQ.newList(51, 22, 63, 42))
#set ($listOfStrings = $PQ.newList("ab", "cd", "ac", "ca"))
#set ($listOfObjects = $PQ.newList({"a": 12}, {"a": 90}, {"a": 63}, {"a": 8}))

<p>List of Numbers is empty: $listOfNumbers.isEmpty(). Items: $listOfNumbers</p>
<p>List of Strings has $listOfStrings.size() items, the first is: '$listOfStrings.get(0)'</p>
<p>Attributes of objects in ListOfObject are:</p>
<ul>
#foreach($elem in $listOfObjects)
  <li>$elem.a</li>
#end
</ul>

Result

List of Numbers is empty: false. Items: [51, 22, 63, 42]
List of Strings has 4 items, the first is: 'ab'
Attributes of objects in ListOfObject are:
12 90 63

New list of unique items (Set)

$PQ.newSet(
  items?
)

items: enumeration (optional)

Creates a new set of items. A set is a special type of list, containing only unique items.

It accepts an enumeration of list items. The number of items is not limited. On the returned set, you can call standard Java lists methods.

Example

#set ($setOfNumbers = $PQ.newSet(51, 67, 23, 10))
#set ($setOfStrings = $PQ.newSet("ab", "cd", "ab", "ca"))

<p>Set of numbers is empty: $setOfNumbers.isEmpty(). Has $setOfNumbers.size() unique elements.</p>
<p>Set of strings has the follwoing elements: $setOfStrings. The first is '$setOfStrings.get(0)'.</p>

Result

Set of numbers is empty: false. Has 4 unique elements.
Set of strings has the follwoing elements: ab, cd, ca. The first is 'ab'.

New Map

$PQ.newMap()

Creates an empty map.

A map is a collection of key:value attributes (such as a JSON object) called entries. You can use it to create custom objects in the Velocity template. On the created map, you can call standard Java methods.

Example

#set ($map = $PQ.newMap())
#set ($result = $map.put("a", 23))
#set ($result = $map.put("b", 41))

<p>Map has $map.size() items:</p>
#foreach($entry in $map.entrySet())
  <p>$entry.key: $entry.value</p>
#end

Result

Map has 2 items:
a: 23
b: 41

Object to flat list

$PQ.toList(
  object
)

object: object

Creates a List out of any Object, flattening nested objects inside.

The Default Template uses this function to make a list out of the result. This allows the result to always be displayed as a table, no matter how complex it is.

Example

#set($nestedObject1 = {"a": {"1": 123, "2": 3, "3": 98}, "b": {"1": 432, "3": 13}})
<p>$PQ.toList($nestedObject1)</p>

Result

[{a.1=123, a.2=3, a.3=98, b.1=432, b.3=13}]

Object flattening

$PQ.toFlatMap(
  object
)

object: object

Flattens an object. Nested object's parameters are appended to the parent object’s keys.

Example

#set($nestedObject2 = {"a": {"1": 123, "2": 3, "3": 98}, "b": {"1": 432, "3": 13}})
<p>$PQ.toFlatMap($nestedObject2)</p>

Result

{a.1=123, a.2=3, a.3=98, b.1=432, b.3=13}

Make list items unique

$PQ.makeUnique(
  list
)

list: list

Converts a collection (list/set/array) to a set (a list containing unique items only).

Example

#set($nonUniqueList = [1, 45, 2, 2, 45])
#set($uniqueList = $PQ.makeUnique($nonUniqueList))

<p>Before: $nonUniqueList</p>
<p>After: $uniqueList</p>

Result

Before: [1, 45, 2, 2, 45]
After: [1, 2, 45]

Sort list

$PQ.sort(
  list,
  compareBy?
)

list: list
compareBy: string

Sorts the provided list so its items are in an ascending oder.

There are two ways to sort the list. You can either use the default comparator (for non-structured items). If the list contains structures (objects/maps), you can sort them using some particular parameter.

Example

#set($structuredList = [{"a": 5}, {"a": 1}, {"a": 3, "b": 4}])
#set($unstructuredList1 =[2,3,5,1])
#set($unstructuredList2 = ["hello", "ahoj", "hallo"])

<p>Unsorted: $structuredList, sorted: $PQ.sort($structuredList, "a")</p>
<p>Unsorted: $unstructuredList1, sorted: $PQ.sort($unstructuredList1)</p>
<p>Unsorted: $unstructuredList2, sorted: $PQ.sort($unstructuredList2)</p>

Result

Unsorted: [{a=5}, {a=1}, {a=3, b=4}], sorted: [{a=1}, {a=3, b=4}, {a=5}]
Unsorted: [2, 3, 5, 1], sorted: [1, 2, 3, 5]
Unsorted: [hello, ahoj, hallo], sorted: [ahoj, hallo, hello]

Reverse list

$PQ.reverse(
  list
)

list: list

Reverses the order of items in the provided list.

Example

#set($originalList =[2,3,5,1])
#set($reversedList = $PQ.reverse($originalList))

<p>Original list items: $originalList</p>
<p>Reversed list items: $reversedList</p>

Result

Original list items: [2, 3, 5, 1]
Reversed list items: [1, 5, 3, 2]

Date (java.util)

$date

Returns a new java.util.Date instance.

You can call $date.getTime() to obtain current Unix Timestamp. The result can be formatted using Format date and time helper, which will help you adjust a result to your time zone (by default, CET is considered).

Example

#set($currentTimestamp = $date.getTime())
#set($fancyCurrentDate = $PQ.formatDate("GMT+1", $currentTimestamp, "yyyy-MM-dd HH:mm:ss"))
<p>Current timestamp is: $currentTimestamp. Or simply $date.<p>
<p>It is $fancyCurrentDate in my time zone!</p>

Result

Current timestamp is: 1616054544210. Or simply Thu Mar 18 09:02:24 CET 2021.
It is 2021-03-18 09:02:24 in my time zone!

Number tool (org.apache.velocity.tools.generic)

$numberTool

Returns a new org.apache.velocity.tools.generic.NumberTool instance.

The default currency formatting is euro. Navigate to Currency formatting to see other formatting options.

Example

#set($testDouble = 10.05)
<p>Integer of $testDouble is $numberTool.integer($testDouble)</p>
<p>Or it is '$numberTool.currency($testDouble)' as currency.</p>

Result

Integer of 10.05 is 10
Or it is 'EUR10.05' as currency.

Math tool (org.apache.velocity.tools.generic)

$mathTool

Returns a new org.apache.velocity.tools.generic.MathTool instance.

This instance can be use for basic mathematical operations, such as finding the average or maximum of some numbers.

Example

#set($testInt1 = 10.05)
#set($testInt2 = 20.05)

<p>From $testInt1 and $testInt2 is $mathTool.max($testInt1, $testInt2) greater</p>
<p>Average is $mathTool.getAverage([$testInt1, $testInt2]).</p>
<p>Addition is $mathTool.add($testInt1, $testInt2).</p>
<p>Multiplication is $mathTool.mul($testInt1, $testInt2).</p>

Result

From 10.05 and 20.05 is 20.05 greater
Average is 15.05.
Addition is 30.1.
Multiplication is 201.50250000000003.

Link tool (org.apache.velocity.tools.generic)

$linkTool

Returns a new org.apache.velocity.tools.generic.LinkTool instance.

This tool helps you to build URLs.

Example

$linkTool.relative('foobar.html').param('id','25').anchor('section4')

Result

foobar.html?id=25#section4

Escape tool (org.apache.velocity.tools.generic)

$escapeTool

Returns a new org.apache.velocity.tools.generic.EscapeTool instance.

This tool helps render tags and code snippets correctly.

Example

<p>Not escaped: <root name='name'><elem></elem></root></p>
<p>Escaped: $escapeTool.xml("<root name='name'><elem></elem></root>")</p>

Result

Not escaped: 
Escaped: <root name='name'><elem></elem></root>

Calendar (java.util)

$calendar

Returns a new default java.util.calendar instance.

The localization of the instance is default (CET). If you want to adjust the instance to your location, please, navigate to Localized calendar helper.

Example

<p>$calendar.getTimeZone()</p>

Result

sun.util.calendar.ZoneInfo[id="Europe/Berlin",offset=3600000,dstSavings=3600000,useDaylight=true,transitions=143,lastRule=java.util.SimpleTimeZone[id=Europe/Berlin,offset=3600000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=2,startMonth=2,startDay=-1,startDayOfWeek=1,startTime=3600000,startTimeMode=2,endMode=2,endMonth=9,endDay=-1,endDayOfWeek=1,endTime=3600000,endTimeMode=2]]