This plugin was distributed previously as part of the McKessonApsWikiPlugins package, now as part of the CeryleWikiPlugins. This documentation is updated for the new version as appropriate.

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

Prefix Operators IS, TO, FROM, NOT OPERATOR (...)
Infix Operators AND, OR (... OPERATOR ...)
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 appear 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!


QueryPlugin is part of CeryleWikiPlugin.

Beware that you have to specify the fully qualified classname (org.ceryle.wiki.plugin.Query) , you can only omit the package name if the Plugin class is in the so called default packages (com.ecyrd.jspwiki.plugin com.ecyrd.jspwiki.forms)


The Query Plugin requires org.ceryle.xml.XHTML which isn't included in the ceryle-wikiutil-%VERSION%.jar. If anyone can provide a link to the jar as it is required within PluginTextUtils class, that would be great.

--AnonymousCoward, 05-Aug-2008

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-25) was last changed on 10-Mar-2010 19:32 by Allhours