Upgrading from PocketQuery 3.x to 4.x will generally be very smoothly and for 99% of users there should be no action required. Still, a lot has changed under the hood, which is mostly due to the fact that it’s now possible to rename PocketQuery entities (Queries, Datasources, Templates, Converters).

Entity Keys in Template APIs

A few more low-level templating APIs now require query/template keys rather than template names. This applies to the following methods.

Templating Velocity API (updated docs: Velocity API Available In Templates):

  • $PocketQuery.executeQuery

  • $PocketQuery.template

Templating JavaScript API (updated docs: Javascript API Provided By PocketQuery)

  • PocketQuery.queryColumns

  • PocketQuery.queryJson

  • PocketQuery.queryArray

You can obtain the keys for queries and templates from the admin UI (below the name input field):

If you have questions, please create a ticket!

New dynamic parameter form

We have changed the template for the dynamic parameter forms. This is what will be included if you check the Use change params template macro parameter. In some cases, you have included and adapted this template yourself. The new template can be found here: Template For Dynamic Parameter Change. If you are using the old template code in any of your templates, you will see a warning about some methods being deprecated (getValueFromMapEntry, getParameterFromRequestOrMacro). We have created a FAQ article that should help you to replace these functions: How to replace 4.x deprecated PocketQuery functions in Templates?. If anything is not clear, please create a ticket!

Deprecated Velocity helper methods

A few Velocity helper methods have been deprecated. For these you will see a warning message on the PocketQuery admin dashboard:

  • $PocketQuery.getParameterFromRequestOrMacro (see “New dynamic parameter form“ above)

  • $PocketQuery.getValueFromMapEntry (see “New dynamic parameter form“ above)

  • $PocketQuery.dataTags

  • $PocketQuery.renderMacroByMarkup (Wiki markup is deprecated by Atlassian, please use $PocketQuery.renderMacro instead)

  • $PocketQuery.renderWikiMarkup (Wiki markup is deprecated by Atlassian)

  • $PocketQuery.renderXhtml

If you are unsure how to replace the deprecated helper methods in your Templates, please create a ticket!

Deprecated JsonPath query field

The JSON Path field for queries has been deprecated in favor of Converters. Anything that was done with this field can also be achieved with a Converter. Please look at How to migrate from JSON Path to a Converter. If you need help, please create a ticket!

Changes to PocketQuery.load

There is an undocumented JavaScript API method PocketQuery.load that we have used in some support cases and examples. If you are using this method, please create a ticket!


And as a final note: if you experience any problem whatsoever, please create a ticket! 🙂 We are really happy to help!