%%(font-size:75%;color:gray;padding-bottom:1em) 
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