Page tree
Skip to end of metadata
Go to start of metadata

Velocity enables you to use a number of variables and call methods on specific objects. When writing PocketQuery templates, the following variables and objects are available:

Additionally, there are various objects available that are specific to PocketQuery:

General

$result (List of Map<String,Object>)

The result of the query. This is a List of Maps, e.g.:

[
{Name: 'Germany', Continent: 'Europe', Region: 'Western Europe'},
{Name: 'Sweden', Continent: 'Europe', Region: 'Nordic Countries'}
]
$pocketErrors (List) A list of errors (if any) that occured executing the PocketQuery macro
$stackTrace (String) The stack trace of the last error (if any)
$debug (Boolean)True if debug mode is enabled, false otherwise
$page (Page)

The current Confluence page (or other ContentEntityObject)

$space (Space)The current Confluence space
$user (User)The current Confluence user

Macro parameters

$processedMacroParameters (Map<String,Object>)Parameters set for the macro, each of them is also accessible directly. Includes the options debug, allowgetparams, includechangetemplate, dynamicloadinitially, includereloadbutton, disableautoload as well as the queryname and the queryparameterstring (parameter map as string).
$debug (Boolean)Whether or not the debug option is enabled
$allowgetparams (Boolean)Whether or not GET parameters, i.e. the option "Enable dynamic parameters", are enabled
$includechangetemplate (Boolean)Whether or not the option "Use change params template" is enabled
$dynamicloadinitially (Boolean)Whether or not the option "Load macro dynamically" is enabled
$includereloadbutton(Boolean)Whether or not the option "Include reload button" is enabled
$disableautoload (Boolean)Whether or not the option "Disable autoload" is enabled

Query

$query (Query)The query object (contains all fields of a query entity described above)
$queryName (String)The name of the query
$queryparameterstring (String)Map queryparameters formatted as String.
$queryParameters (Map<String, Object>)Parameters that were given to the query in the PocketQuery macro (in the macro browser or by GET parameters)
$queryExecutionTime (Long)Time in milliseconds the database transaction took
$rawResult (Object)Raw query result

Utils

$date (Date)Date object, initialized to the time of macro execution
$calendar (Calendar)Calendar object, initialized to the time of macro execution
$dateFormatter (DateFormatter)DateFormatter object for Confluence-oriented date formatting
$friendlyDateFormatter (FriendlyDateFormatter)FriendlyDateFormatter object for Confluence-oriented date formatting
$numberTool (NumberTool)NumberTool object for number formatting
$math (MathTool)MathTool object for advanced math operations
$sums (Map<String, Long>)Contains the summed up values of all columns of the result that contain only numeric values. Each value can be accessed using $sums.get("columnName") or $sums.columnName

    

The PocketQuery Velocity Helper

In addition to the objects above, there is a global Velocity helper object available in PocketQuery templates that contains some utility methods. You can access this helper with the context key $PocketQuery. Below you find a list of the methods that are currently available.

PocketQuery Specific / Templating


$PocketQuery.executeQuery(String queryname)

@param queryname indentifier for the query
@return result set

Executes the given query and returns the result set that was fetched from the datasource and postprocessed. If a converter is set, it will be executed, but the rendering of the template will be skipped.

This can be useful if you want to combine data from one datasource with another without rendering the whole query.

Note: You have to check for errors yourself when using this. Make use of hasErrors() and printErrors() accordingly.

Example:

#set($myResult = $PocketQuery.executeQuery("myQueryName"))

#if($myResult.hasErrors())
  $myResult.printErrors()
#else

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

#end

$PocketQuery.executeQuery(String queryname, Map<String, Object> parameterValues)

@param queryname indentifier for the query
@param parameterValues parameters (see example)
@return result set

Executes the given query with the given parameter values and returns the result set that was fetched from the datasource and postprocessed. If a converter is set, it will be executed, but the rendering of the template will be skipped. You can also pass query parameters that will be used in the execution of your query.

This can be useful if you want to combine data from one datasource with another without rendering the whole query.

Note: You have to check for errors yourself when using this. Make use of hasErrors() and printErrors() accordingly as seen above.

Example:

#set($myResult = $PocketQuery.executeQuery("myQueryName", {
  "MyWord" : "Bird",
  "MyNumber" : 1
}))

$PocketQuery.template(String templateKey)

@param templateKey indentifier for the template to be rendered
@return rendered template string

Return the rendered HTML of the template with the given template key while using the data of the current result. This can be useful if you want to display the result of the related query in two different ways.

The template can be:

  • The default PocketQuery template with the key “default”
  • A PocketQuery template created in PocketQuery admin. The template key will be the name of the template
  • A template in the PocketQuery plugin resources. In that case the template key is as in pattern “pocketquery-%templateKey%.vm"

Examples in Velocity templates:

Render the query data first as default table and below that using your custom template
$PocketQuery.template("default")
$PocketQuery.template("MyCustomTemplateName")

$PocketQuery.dataTags(Map<String, Object> params)

@param params Map of parameters for data attributes
@return generated data attributes string

Will produce a HTML data attributes string from the given parameters. If a map like { one: ‘1’, two: ‘2’ } is given, the result will be ‘data-one=”1” data-two=”2”‘. Example in Velocity templates:

<div $PocketQuery.dataTags({ "language":"German", "country":"Germany" })>
	My div with data attributes
</div>

This will produce:

<div data-language="German" data-country="Germany">
	My div with data attributes
</div>
 

$PocketQuery.getParameterFromRequestOrMacro(String key, HttpServletRequest request, Map<String, Object> queryParameters)

@param key The key of the parameter

@param request The current HTTP request

@param queryParameters The query parameters passed to the query from the PocketQuery macro

@return The value for the requested key

 

 

Retrieve the parameter value from the given request or the given parameter map. This is associated with the “GET parameter pass-through” feature.

Keys in the request parameters are always prefixed with “pq_”. If nothing is found in the request, the query parameters are searched.

Examples in Velocity templates:

$PocketQuery.getParameterFromRequestOrMacro($key, $req, $queryParameters)

Rendering


$PocketQuery.renderMacro(String name)

@param name macro name
@return rendered macro HTML

Return the rendered HTML of the macro with the given name without macro parameters or any further environment options.

Examples in Velocity templates:

$PocketQuery.renderMacro("cheese")

$PocketQuery.renderMacro(String name, Map<String, Object> options)

@param name macro name
@param options map as described above
@return rendered macro HTML

Return the rendered HTML of the macro with the given name using the given map of options. Options are currently:

  • page (ContentEntityObject): the underlying content entity object (mostly page or blogpost) (defaults to null)
  • parameters (Map<String, String>): macro parameters (parameterName => parameterValue) (defaults to an empty map)
  • body (String): macro body (defaults to null)
  • bodytype (String): type of the body string, either “plaintext” or “richtext” (defaults to “richtext”). If “plaintext” is set, the body content is not interpreted.

Examples in Velocity templates:

$PocketQuery.renderMacro("info", {
  "page": $page,
  "parameters": { "title": "PocketQuery rocks!" },
  "body": "This is an info macro that says 'PocketQuery rocks!'"
})

$PocketQuery.renderMacroByMarkup(String markup)

@param markup Markup string - can be either wiki markup or XHTML storage format
@return rendered macro HTML

Return the rendered HTML a macro defined by the given markup string. Markup can be either XHTML
or wiki markup storage format.

Examples in Velocity templates:

$PocketQuery.renderMacroByMarkup('<ac:structured-macro ac:name="info">
		<ac:parameter ac:name="title">PocketQuery rocks!</ac:parameter>
		<ac:rich-text-body>
			<p>This is an info macro that says "PocketQuery rocks!"</p>
		</ac:rich-text-body>
	</ac:structured-macro>')

$PocketQuery.renderMacroByMarkup("{infohi_is_ the cheese macro: {cheese}{info}}")

$PocketQuery.renderMacroByMarkup(String markup, ContentEntityObject ceo)

@param markup markup string - can be either wiki markup or XHTML storage format
@param ceo underlying ContentEntityObject (mostly page or blogpost)
@return rendered macro HTML

Return the rendered HTML a macro defined by the given markup string. Markup can be either XHTML
or wiki markup storage format. Use the given ContentEntityObject (mostly page or blogpost) as environment.

Examples in Velocity templates:

$PocketQuery.renderMacroByMarkup('<ac:structured-macro ac:name="info">
	<ac:parameter ac:name="title">PocketQuery rocks!</ac:parameter>
	<ac:rich-text-body>
		<p>This is an info macro that says "PocketQuery rocks!"</p>
	</ac:rich-text-body>
	</ac:structured-macro>', $page)

$PocketQuery.renderMacroByMarkup("{infohi_is_ the cheese macro: {cheese}{info}", $page)

$PocketQuery.renderPocketQueryMacro(String queryName)

@param queryName name of the target PocketQuery query
@return rendered PocketQuery macro HTML

Return the rendered HTML of the PocketQuery macro using the query with the given query name.
The query name is the one defined in PocketQuery admin.

Examples in Velocity templates:

$PocketQuery.renderPocketQueryMacro("WorldPopulation")

$PocketQuery.renderPocketQueryMacro(String queryName, Map<String, Object> options)

@param queryName name of the target PocketQuery query
@param options parameters (see below)
@return rendered PocketQuery macro HTML

Return the rendered HTML of the PocketQuery macro using the query with the given query name.
The query name is the one defined in PocketQuery admin. Use the given map of options for further
configuration. Options are currently:

  • page (ContentEntityObject): the underlying content entity object (mostly page or blogpost) (defaults to null)
  • parameters (Map<String, String>): parameters for the PocketQuery statement (parameterName => parameterValue) (defaults to an empty map)
  • dynamic load (String): if you want the macro to be rendered in the background (Ajax), set this to “true”

Examples in Velocity templates:

$PocketQuery.renderPocketQueryMacro("WorldPopulation", {
  "page": $page,
  "parameters": { "Continent":"Europe" },
  "dynamicload": "true"
})

$PocketQuery.renderWikiMarkup(String wikiMarkup)

@param wikiMarkup wiki markup string
@return rendered HTML of the given wiki markup string

Return the rendered HTML of the given wiki markup string.

Examples in Velocity templates:

$PocketQuery.renderWikiMarkup("{infohi_is_ the cheese macro: {cheese}{info}")

$PocketQuery.renderXhtml(String xhtml)

@param xhtml XHTML string as in the storage format of Confluence content
@return rendered HTML of the given XHTML markup

Return the rendered HTML of the given XHTML markup storage format string.

Examples in Velocity templates:

$PocketQuery.renderXhtml('<ac:structured-macro ac:name="info">
	<ac:rich-text-body><p><strong>This</strong> <em>is</em> the cheese macro: 
		<ac:structured-macro ac:name="cheese" />
	</p></ac:rich-text-body>
	</ac:structured-macro>')

Utils


$PocketQuery.getValueFromMapEntry(Entry<String, Object> entry)

@param entry The target Map.Entry
@return The value of the Map.Entry

Get the actual value from the given Map.Entry. Takes the first item if the value is an array.

Examples in Velocity templates:

$PocketQuery.getValueFromMapEntry("myParameterKey")

$PocketQuery.newList()

@return newly created List object

Create a new List and return it.

Examples in Velocity templates:

$PocketQuery.newList()

$PocketQuery.newMap()

@return newly created Map object

Create a new Map and return it.

Examples in Velocity templates:

$PocketQuery.newMap()

$PocketQuery.newSet()

@return newly created Set object

Create a new Set and return it.

Examples in Velocity templates:

$PocketQuery.newSet()

$PocketQuery.reverse(Collection<String> collection)

@param collection collection to reverse
@return reversed collection

Reverse the order of the given collection and return the result.

Examples in Velocity templates:

$PocketQuery.reverse($myArrayList)

$PocketQuery.sort(Collection<String> collection)

@param collection collection to sort
@return sorted collection

Sort the given collection alphabetically and return the result.

Examples in Velocity templates:

$PocketQuery.sort($myArrayList)

$PocketQuery.formatDate(Date date, String formatString)

@param date date to be formatted
@param formatString format string as required by SimpleDateFormat
@return sorted collection

Formats a given date to a desired format. Uses java.text.SimpleDateformat, so all format strings must be compliant to the specification.

$PocketQuery.formatDate($myDate, "dd.MM.yyyy")
  
  • No labels