Using the PocketQuery Macro
Queries are maintained by Confluence administrators are executed (and possibly parameterized) using the PocketQuery macro. This page describes its features.
Embedding the Macro
Within any Confluence page or blog post, you can embed this Macro with the {} syntax or using the macro editor.
Macro parameters
The PocketQuery macro has different parameters that control how database contents are to be presented in the view of the page. Some of these parameters are only available if other parameters are checked.
These are the parameters:
Query Name: Name of the target query defined by a PocketQuery administrator. All queries available in the current space are provided in a select box.
Query Parameters: If the query selected above requires one or more parameters, they can be set here. Several wildcards can be used as parameters (see below).
Load macro dynamically: Make the contents of the query load asynchronously in the background. With this checked, the page load won’t be delayed by the loading of the PocketQuery macro. This will be a performance benefit, especially if you have multiple PocketQuery macros on one page.
Include reload button: (requires: “Load macro dynamically”) Shows a small reload button in the top right corner by which the contents of the PocketQuery macro will reload. This is especially useful if your database contents change frequently. (See also Section "Dynamic load" below.)
Allow URL parameters: Allows to pass query parameters in the URL. The syntax for these parameters in the URL is
pq_parameterName. If the option “Use change params template” is also checked, the parameter changes will also be reflected in the URL. If additionally, “Load macro dynamically” is checked, the browser history will be used to equally reflect this in the URL. (See also section “Dynamic parameters” below.)Use change params template: (requires: “Load macro dynamically” OR “Allow URL parameters”) Shows a form above the result in which the user can dynamically change the query parameters. If “Load macro dynamically” is used the result will change without page reload. Otherwise, the page is reloaded with the appropriate GET parameters.
Debug Mode: Shows debug information on the page for error analysis.
The following wildcards can be given as parameters:
@username - the username of the current Confluence user.
@userfullname - the full name of the current Confluence user.
@usermail - the email address of the current Confluence user.
@page - the title of the current Confluence page/blogpost.
@pageid - the ID of the current Confluence page/blogpost.
@spacekey - the space key of the current Confluence page/blogpost.
@spacecategory - searches for a space category starting with
pq-in the current space and uses the part after the dash as value. For example, a space categorypq-myvaluewill be used asmyvaluefor the query parameter. Currently only one such wildcard can be used per space.
These wildcards will be replaced by the actual content before the query is executed. Furthermore, the wildcards specific to the datasource can be used, e.g. % for SQL databases.
For users that are not logged into Confluence @username, @userfullname and @usermail will return "anonymous".
Dynamic load
If the option "Load macro dynamically" is enabled, the page that contains the PocketQuery won't have to wait for the PocketQuery data to be loaded. Instead, the page will completely load first and PocketQuery will fetch its data in the background, showing a loading icon in the meantime.
This will be a tremendous performance improvement if your results are comprising in size. Also, this option can be very handy if combined with dynamic parameters and the "change params template" (see below) which enables live changes to the contents currently shown without having to reload the page.
Dynamic parameters
If you want to parameterize a PocketQuery macro dynamically when the page is loaded, you can make use of the Allow URL parameters feature (i.e. check the Allow URL parameters checkbox in the macro parameters, as described above). If set, dynamic parameters can be passed as GET parameters to the page URL. They have to be addressed using their name specified in the PocketQuery administration prefixed with pq_ to avoid naming collisions.
For example, if you have a macro for a query with two query parameters min and max, you can open your page like this: <your-confluence-page-url>?pq_min=10&pq_max=50. Note that GET-Parameters override the values you specified in the macro.
Note that if you use special characters or wildcards within the parameter value, you need to URL encode them. For example, the wildcard symbol % becomes %25.
If you have multiple PocketQuery macros on one page that have a parameter with the same name, the GET parameter will set all these parameter values. This can be a useful feature, but be aware of unwanted name conflicts.
If you additionally check the “Use change params template” option, a form will be shown above the result that enables to change the parameters in the page.
If you additionally check the “Load macro dynamically” option, the parameters will be given to request and results will correspond to these parameters as well. It makes much sense to combine this with the “change params template” because users can simply change the parameters in the form and a submit won’t trigger a reload of the page, but will show the updated results directly in the page. In that case, the URL will also change dynamically for permalink ability and not to lose the browser history (“back” and “forward” buttons).
Example usage: Dynamic parameters generally enable a big set of possibilities, e.g.:
Links to the same Confluence page (that includes a PocketQuery macro) using different query parameters to display completely different data.
Reload button for refreshing the contents from the database and get a live view.
The macro option "Enable change params template" uses dynamic parameters in the background. Of course, it is possible to rebuild, customize and enhance its functionality - for more details, see Templating Tutorial.