|Title|Wiki Links Through XPATH, including SubPages support
|Date|23-May-2006 22:17:36 EEST
|JSPWiki version|
|Submitter| [DF|DirkFrederickx]
|[Idea Category]|GenericIdea
|[Idea Status]|NewIdea

!! Wiki Link syntax extended with XPATH
See also [XPath]

This page describes an approach to extend the wiki [[link syntax] 
to powerful expressions based on XPATH and JSR-170.
It would also allow to add subpages to JSPWiki.

Example of current syntax :
   [SandBox]                            =>yield link to wiki page
   [SandBox/attach.jpg]                 =>yield link to attachment
Example of extended Wiki Link syntax :
   [SandBox/w:properties/variableX]     =>yield value of wiki variable
   [SandBox/w:versions/v123]            =>yield link to wiki page version
   [SandBox/w:versions/v123/attach.jpg] =>yield link to attachment

   [SandBox/@variableX]                 =>yield value of wiki variable
   [SandBox/v123/attach.jpg]            =>yield link to attachment

Normally, the wiki link syntax returns a single result, being a link to a wiki page or attachment.
From the previous examples, you can see that it is also possible to return the value of page __variables__ as well as links to page __versions__ different from the latest version.

Additionally, XPATH expressions will allow to return multiple results, separated by a space. 
   [SandBox/w:to]                       =>yield all referred-to page links
   [SandBox/w:from]                     =>yield all referred-from page links
   [SandBox/w:versions]                 =>yield links to all versions of SandBox
   [SandBox/w:properties]               =>yield all variables (how? name=value)
   [SandBox/w:attachments]              =>yield all attachment links

!! Wiki Metadata XML model

A Wiki Link can be written be means of an [XPath] expression.
In order to do that, you need to understand the underlying xml model.

The namespace ''w;'' is preserved for the predefined wiki elements.
\\''TODO: check how this will work with interwiki links.''

     <w:author> ... </w:author>
     <w:created> ... </w:created>
     <w:pageName> ... </w:pageName>
     <w:lastModified> ... </w:lastModified>
     <w:versionNumber> ... </w:versionNumber>
       <aProperty1> ... </aProperty1>
       <aProperty2> ... </aProperty2>
         <w:fileName> ... </w:fileName>
         <w:fileSize> ... </w:fileSize>
       <v1> ... </v1>
       <v2> ... </v2>
       <v3> ... </v3>
       <aPageX1> ... </aPageX1>
       <aPageX2> ... </aPageX2>
       <aPageY1> ... </aPageY1>
       <aPageY2> ... </aPageY2>
     ... <pagecontent - wiki markup text> ...
   <aPage2> ... <aPage2>

Shortcut syntax is defined for properties, attachments and versions. 
Also the root-path {{/w:pages/}} can be dropped. This way, the syntax
becomes backwards compatible with the current syntax.
                                           => SandBox/@versionLabel

                                           => SandBox/attach.png

                                           => SandBox/v127/@versionLabel

!! XPATH expression

XPATH expression allow for a powerful querying of the wiki repository.
(See [XPath] for more details)

Some examples:

Return a list of to-pages having a fruit variable
Return a list of to-pages where the fruit variable equals 'apple'
Use (brackets) when you need logical operators (avoid syntax ambiguity)
  [(SandBox/w:to[@fruit='apple'] | SandBox/w:to[@fruit='approved'])]
XPATH evens supports string functions. Following example returns a 
list of pages with the search string matched


It should be possible to use a standard xpath processing java library as a plugin to wiki to support this kind of expressions. 
Probably, we need to write some back-end to provide the xpath with a ''virtual'' xml structure to mimic the internal repository of JSPWiki.

Ref. [JXPATH|http://jakarta.apache.org/commons/jxpath/] Apache library. Check it.

!! Wiki Link Format

With the extended syntax, a wiki link can now return
(i) a hyperlink, (ii) a variable value, (iii) a set of hyperlinks or (iv) a set of values.
Therefor additional formatting capabilities are needed.

Standard __wiki link format__ syntax allows a static ''format'' text.
  [Play around|Sandbox]
More elaborated format string allows to reference variables inside the referenced page
or attachement.
  [Speed is @speed|Sandbox]
In case the wiki link return multiple results, the format string is iterated over each result.
Example: following expression returns a bullet list of pages with the value of @liveVersion 
and a link to that page as well.
               use {{.}} to refer to the iterated result of the wiki-path
  [* @pagename has version @liveVersion, here is the [link|.] |Sandbox/w:to]


Use page variables (prefixed with $) to replace more complex format strings.
  [{SET formatAuthor='Author of @pagename is @author' }]


  [{SET format='* ./$pagename has version ./$liveVersion, here is the [link|.]' }]
               idem, with format string defined in $format of this page

               idem, with format string defined in $format of the Main page

  || PageName     || LiveVersion   || Link
  [{| ./$pagename | ./$liveVersion | [link|.] }|wiki-path] 
               idem, with table header and table body as output format


Please log your remarks/suggestions here

Yup.  Great idea.  Would go together excellent with the idea of using JSR-170 as a backend repository...

-- JanneJalkanen