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

%%tabbedSection
%%tab-Proposal
!! 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:pages>
   <aPage1>
     <w:author> ... </w:author>
     <w:created> ... </w:created>
     <w:pageName> ... </w:pageName>
     <w:lastModified> ... </w:lastModified>
     <w:versionNumber> ... </w:versionNumber>
     <w:properties>
       <aProperty1> ... </aProperty1>
       <aProperty2> ... </aProperty2>
     </w:properties>
     <w:attachments>
       <anAttachment1>
         <w:fileName> ... </w:fileName>
         <w:fileSize> ... </w:fileSize>
       </anAttachment1>
     </w:attachments>
     <w:versions>
       <v1> ... </v1>
       <v2> ... </v2>
       <v3> ... </v3>
     </w:versions>
     <w:to>
       <aPageX1> ... </aPageX1>
       <aPageX2> ... </aPageX2>
     </w:to>
     <w:from>
       <aPageY1> ... </aPageY1>
       <aPageY2> ... </aPageY2>
     </w:from>
     ... <pagecontent - wiki markup text> ...
   </aPage1>
   <aPage2> ... <aPage2>
 </w:pages>
}}}

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.
{{{
   /w:pages/SandBox/w:properties/versionLabel
                                           => SandBox/@versionLabel

   /w:pages/SandBox/w:attachments/attach.png
                                           => SandBox/attach.png

   /w:pages/SandBox/w:versions/v127/w:properties/versionLabel
                                           => 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
{{{
  [SandBox/w:to[@fruit]]
}}}
Return a list of to-pages where the fruit variable equals 'apple'
{{{
  [SandBox/w:to[@fruit='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
{{{
  [SandBox/w:to[contains(text(),'jsp')]]
  [SandBox/w:from[starts-with('Description')]]
}}}

!Implementation

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]
  [@filesize|Sanbox/attach.png]
}}}
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' }]
  [$formatAuthor|Sandbox/w:to]
}}}

{{{

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

  [[SandBox/$format]|wiki-path] 
               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

}}}
%%
%%tab-Discussion

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

----

agree, it's a very good idea to use the namespace abbriviation in order to identify xpath queries inlined to the content.

some smaller questions towards a structure free of redundancy:

*do you mind to specify a property more than once in order to form a set of values under one name?
**looks like this is consitent to your use of set-returns in your xpath results
*I wonder how you would keep the ''to''s and ''from''s consistent over a wiki repository
*I wonder what's the difference between w:to and any other property set - other than it's used more often
*I would recommend to have one page element for each page version, as you did. I wonder why you need all the versions specified in one page, though.
*As a result here's [Rolfs slightly improved version]

--[rsc|mailto:rolf@august.de], 24-May-2006
%%
%%