|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

----

Great idea.
However I see as a drawback in terms of usageal that it would add yet one new way to build content or lists out of other WIki pages.
As far as I know, we have:
* [Tasks Plugin], although the name is misleading, is an elaborate query engine to build tables out of several source pages.
** Pros: outputs ''contents'' of source poages (not only links to source pages), filters using arbitrary criteria on the contents itself
** cons: non-standard plugin, and slightly constrains the source pages structure, constrains the result format (table).
* [Query Plugin], again misnamed, builds a list of links references, based on references only (TOs and FROMs). This is somehow an elaborate form of the [Referring Pages Plugin], which lists only the FROMs).
** Pros: performance (supposedly), as it queries the ReferenceManager, and does not have to traverse page contents.
** Cons: non-standard plugin, outputs only links (no content), forces link structure on source pages, no content filtering
* IdeaWikiLinksThroughXPATHIncludingSubPagesSupport, the mechanism suggested on this very page.
** Pros: configurable formatting, filter criteria based on links ''and'' metadata contents (variables, attachments, versions), may end up into JSPWiki core as Janne seems interested :o)
** Cons: no filtering on raw text contents (other than variables or attachments), but maybe I misunderstood your examples, no filtering on page names (as of the examples, although it can surely be included for cheap)

Overall, merging the 3 ideas within a single mechanism, preferrably included in JSPWiki core, would make up a powerful Wiki query engine, enabling usage of [Wiki as a database].

-- [JDuprez]
%%
%%