Description#

The QueryPlugin treats the pages and references between them like a database. You can query the pages using a simple syntax (AND, OR, NOT, ...). The matching pages are returned sorted alphabetically in a bulleted list.

The query is done against the ReferenceManager's collection of all pages/links so it's fast. The query results are "cached" for 30 seconds, so viewing pages with a query doesn't load the server too much.

In some sense the ReferringPagesPlugin is a degenerate form of this plugin (pages='(TO [ThisPage]').

Parameters#

The following parameters are currently supported...

• pages= Required. The page query string to be evaluated.
• echo= Optional, echo the parsed parenthesized query string back out, default = 'false', set to 'true' to see the formalized form of your query.
• emptytext= Optional. This is the (non-markup) text returned if there is no query result. The default is "No pages found."
• output= Optional. One of 'none', 'list', 'bullet', 'number', 'space' or 'comma'. This alters the output presentation of the query result pages. The default is 'list' which generates a simple vertical list; 'none' suppresses the list output; 'bullet' and 'number' generate bulleted and numbered lists (resp.); 'space' generates a space-delimited list; 'comma' generates a comma-delimited list.

Query Syntax#

The query syntax is pretty basic.

Parentheses

Must "balance" (the number of ( must match the number of ), and must "nest" properly ( ())( balances, but doesn't nest properly). Explicit parentheses are respected when present. As is typical of most queries, more parentheses are better, in that you don't have to worry about how the plugin dis-ambiguages and formalizes your query string.

Brackets

All page names in the query string must be surrounded by []'s. Failure to enclose a page name in []'s will cause the parser to choke. Brackets must "balance" and must not "nest". Note that the current version of the QueryPlugin now supports regular expression specification of page names, using the RegularExpressionSyntax built into Java.

AND, OR, NOT

Pretty much what you'd expect.

IS(...)

Selects the pages specified as ...

TO(...)

Selects pages that refer "to" the pages specified as ...

FROM(...)

Selects pages that are referenced "from" the pages specified as ...

Page Names

Must be in brackets, must be given as CamelCase (no spaces or special chars, named just like the page would apprear on the URL.

Regular Expressions for Page Names#

Square-bracketed page names as used in queries can now be specified using RegularExpressionSyntax (or "regex" for short). Regex is a relatively simple way of specifying wiki pages based on name matches. For example, the regex match for all pages is [.*]; or [.*Plugin] for all pages that end in "Plugin"; or [Wiki.*] for all pages that start with "Wiki", such as "~WikiAttachments", "~WikiName", etc. Note that the regex expressions are case-sensitive.

Example Usage#

Here is a "realistic" example (for you XP folks) that would list all pages linking to the pages [Bug] and [Open] and not linked to by [PlanningGame].

 [[{Query pages='TO( [[Bug] AND [[Open]) AND NOT( FROM( [[PlanningGame] ) )'}] 

Simple examples:

[{Query pages='TO [Main]'}]

Returns all pages referring to [Main].

[{Query pages='FROM [Main]'}]

Returns all pages that [Main] refers to.

[{Query pages='IS [Main]'}]

Returns the [Main] page.

[{Query pages='NOT TO [Main]'}]

Returns all pages that don't refer to [Main] (probably a lot!).

[{Query pages='NOT FROM [Main]'}]

Returns all pages that [Main] doesn't refer to (again, probably a lot!).

[{Query pages='IS NOT [Main]'}]

Returns every page except for the [Main] page.

[{Query pages='NOT IS [Main]'}]

Same as IS NOT, yup the parser/evaluator is pretty flexible.

Generated HTML#

    <p>Query: ((TO( [[Bug] AND [[Open])) AND (NOT( FROM( [[PlanningGame] ) )))</p>
    <ul>
      <li><a href="...">~QueryResultOne</a></li>
      ...
    </ul>

Status/Notes#

This is still considered BETA! Help in testing would be appreciated!

Testing#

Try the QueryPluginTest page.