Velocity API available in Templates

General

Query result

TEXT

$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

CODE

{
  a: 1,
  b: 2
}

Template

HTML

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

Result

CODE

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

Query Parameters

TEXT

$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

CODE

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

Template

CODE

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

Result

CODE

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

Template insertion by Template ID

CODE

$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)

HTML

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

Template 2 (called)

CODE

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

Result

TEXT

I am the first template
I am the second template

Template insertion by Template name

TEXT

$PQ.templateByName(
  templateName
)

templateName: string

Renders another Template inside the caller Template.

It requires a Template name, which can change over time. Please, use this method only in the case you are sure the name won’t change. Otherwise, use $PQ.template(templateId). You can also call $PQ.template("default") to obtain 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)

HTML

<p>I am the first template</p>
PQ.templateByName("Template 2")

Template 2 (called)

HTML

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

Result

TEXT

I am the first template
I am the second template

Macro execution

TEXT

$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

HTML

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

Query execution

TEXT

$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

HTML

#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)

CODE

$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

HTML

#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

TEXT

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

Random UUID

CODE

$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.

Date/Time Formatting

Format date and time

TEXT

$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

HTML

<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

CODE

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

TEXT

$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

HTML

<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

TEXT

1615973113000
1615973113000
1615973113000
1615973113000

Localized calendar

CODE

$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

HTML

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

Result

TEXT

GMT-03:00

Text and Currency Formatting

Currency formatter

TEXT

$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

HTML

#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

TEXT

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

Markdown formatter

CODE

$PQ.markdown(
  markdownText
)

markdownText: string

Formats Markdown text into HTML.

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

Example

HTML

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

Result (user sees rendered markup)

HTML

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

Collection Operations

New List

TEXT

$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

HTML

#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

TEXT

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)

TEXT

$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

HTML

#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

TEXT

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

TEXT

$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

HTML

#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

CODE

Map has 2 items:
a: 23
b: 41

Object to flat list

CODE

$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

HTML

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

Result

TEXT

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

Object flattening

CODE

$PQ.toFlatMap(
  object
)

object: object

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

Example

HTML

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

Result

TEXT

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

Make list items unique

CODE

$PQ.makeUnique(
  list
)

list: list

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

Example

HTML

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

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

Result

CODE

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

Sort list

CODE

$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

HTML

#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

TEXT

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

CODE

$PQ.reverse(
  list
)

list: list

Reverses the order of items in the provided list.

Example

HTML

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

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

Result

TEXT

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

Java Utils

PocketQuery provides some standard Java Utils. You can use them as standard Java objects and call their methods to format and convert your query results. Note that these utils are not available under the $PQ or $PocketQuery namespace, but under the global namespace..

Date (java.util)

CODE

$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

HTML

#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

TEXT

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)

CODE

$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

HTML

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

Result

TEXT

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

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

CODE

$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

HTML

#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

TEXT

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)

CODE

$linkTool

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

This tool helps you to build URLs.

Example

HTML

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

Result

CODE

foobar.html?id=25#section4

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

CODE

$escapeTool

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

This tool helps render tags and code snippets correctly.

Example

HTML

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

Result

CODE

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

Calendar (java.util)

CODE

$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

HTML

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

Result

TEXT

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]]