At line 9 added 5 lines |
This idea started as an XPATH extension of the page link syntax of JSPWiki. |
%%(border-left:4px solid silver; padding-left: 1.5em; margin-top:-1em; margin-bottom:1em;) |
It has been extended with new ideas of page organising concepts. |
%% |
|
At line 11 changed 2 lines |
!! Wiki Link syntax extended with XPATH |
|
!!! Introduction : extend Wiki Link syntax with XPATH |
At line 16 changed 3 lines |
to powerful expressions based on XPATH and JSR-170. |
It aims also to present an approach to extend JSPWiki |
with support for [WikiSubPages] and [WikiFarms]. (wiki-farms todo) |
to powerful expressions based on XPATH and JSR-170[1]. |
At line 22 changed 2 lines |
[SandBox] =>yield link to wiki page |
[SandBox/attach.jpg] =>yield link to attachment |
[SandBox] =>yield link to wiki page |
[SandBox/attach.jpg] =>yield link to attachment |
At line 27 changed 4 lines |
[SandBox/w:properties/variableX] =>yield value of wiki variable |
[SandBox/w:pages/SomeSubPage] =>yield link to a subpage |
[SandBox/w:versions/v123] =>yield link to wiki page version |
[SandBox/w:versions/v123/attach.jpg] =>yield link to attachment |
[SandBox/w:properties/variableX] =>yield value of wiki variable |
[SandBox/w:pages/SomeSubPage] =>yield link to a subpage |
[SandBox/w:versions/w:v123] =>yield link to wiki page version |
[SandBox/w:versions/w:v123/attach.jpg] =>yield link to attachment |
At line 34 changed 3 lines |
[SandBox/@variableX] =>yield value of wiki variable |
[SandBox/SomeSubPage] =>yield link to the subpage |
[SandBox/v123/attach.jpg] =>yield link to attachment |
[SandBox/@variableX] =>yield value of wiki variable |
[SandBox/SomeSubPage] =>yield link to the subpage |
[SandBox/w:v123/attach.jpg] =>yield link to attachment |
At line 44 changed 6 lines |
[SandBox/w:to] =>yield all referred-to page links |
[SandBox/w:from] =>yield all referred-from page links |
[SandBox/w:pages] =>yield links to all subpages of SandBox |
[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 |
[SandBox/w:to] =>yield all referred-to page links |
[SandBox/w:from] =>yield all referred-from page links |
[SandBox/w:pages] =>yield links to all subpages of SandBox |
[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 |
At line 54 added one line |
%%(border-left:4px solid silver; padding-left: 1.5em;) |
At line 53 changed one line |
!! Wiki Metadata XML model |
!!! Organisational Concepts |
At line 58 added 172 lines |
The extended [[page link] syntax would also provide support to some further extensions of JSPWiki for more advanced ''organisational concepts'' such as |
[WikiFarms|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#WikiFarm], |
[WikiWebs|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#WikiWeb], |
[WikiSubPages|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#WikiSubPages], |
[WikiCategories|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#WikiCategories] and |
[WikiTags|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#WikiTags]. |
See also ref.[2] |
|
!! ~WikiFarm |
|
URL Syntax: {{{http://baseURL/...}}} |
|
A ''~WikiFarm'' is a grouping of ~WikiWebs, running on the same wiki engine, behind the same ''baseURL''. |
It provides for a common administration platform for a set of wikis. |
All ~WikiWebs of a ~WikiFarm share the same ''user database'' and ''authentication'' policy. |
|
The ~WikiFarm ''~SiteMap'' page provides an overview of all its ~WikiWebs. |
{{{ |
[/w:wikiwebs] => renders a list of all WikiWebs' homepages in this WikiFarm |
}}} |
|
A ~WikiFarm provides overall administrative settings for properties such as:\\ |
'' |
baseURL, encoding, searchProvider, plugin.*, interWikiRef.* , rss.*, log4j.* |
authorizer, userdatabase.*, groupManager, aclManager, |
(new) defaultwikiweb |
'' |
|
!! ~WikiWeb |
|
URL Syntax: {{{http://baseURL/wikiwebnamespace:wikipagename}}} |
|
A ~WikiWeb allows ~WikiPages to be grouped into separate namespaces. |
|
This is especially useful when organising large chunks of information. |
It also improves ease of administration. \\ |
However, separate namespaces may also decrease usability |
as users must remember the ~WikiWeb name prior to the ~WikiPage name. |
Preferably, the name of the current ~WikiWeb should always be visible in the GUI. |
|
The ''current ~WikiWeb'' defines the scope of several wiki functions such as |
[PageIndex], [RecentChanges], [UnusedPages], [UndefinedPages] and [FindPage]. |
An extra ''wiki-web'' option is to be added to the [FindPage] (and other plugins) |
to allow searches in other sibling ~WikiWebs. |
A ~WikiWeb may want to provide its own global pages such as |
[LeftMenu], [LeftMenuFooter], [CopyrightNotice], [EditPageHelp], etc.. [3] |
|
A ~WikiWeb may specify a dedicated location of its page repository and have a dedicated security policy. |
|
A ~WikiWeb provides administrative settings via a GUI for properties such as:\\ |
'' |
%%strike frontPage%% homePage, templateDir, translatorReader.*, pageProvider, attachmentProvider, diffProvider, |
(new) wikiWebNamespace, wikiWebSkin, wikiWebSecurityPolicy |
'' |
|
Possibly, these properties could take another prefix iso {{jspwiki.}} |
{{{ |
jspwiki.pageProvider=... => default pageProvider |
zoo.pageProvider=... => pageProvider for the 'zoo' WikiWeb |
}}} |
|
Example |
{{{ |
[zoo:] => links to the home page of zoo: |
[zoo:Main] => link to the top Main page of zoo: |
[zoo:*//Main] => links to all Main pages of zoo: |
[Main] => links to zoo:Main when zoo: is the current wiki-web |
}}} |
|
%%(background:ff9;) |
Q. Is the term ''~WikiWeb'' clear enough. Other suggestions: ''wiki-site'', ... ? |
%% |
|
!! ~WikiSubPages |
|
URL Syntax: {{{http://baseURL/wikiwebnamespace:wikiparentpage/wikisubpage/wikisubsubpage}}} |
|
~WikiPages can act as a container for other ~WikiSubPages as well as attachments. |
Containment implies that e.g. renaming or deleting a ''parent'' ~WikiPage |
also impacts all its child pages and attachments. |
|
~WikiSubPages inherit the ACLs of their ancestor pages. Child pages can add (=restrict) ACLs |
to those of the ancestors but never relax them. (parental control ;-) |
|
Example |
{{{ |
[Birds/Stork] => child pages use / as delimitter |
[/Zoo/Birds/Stork] => absolute link |
(start with / to denote the root of the current WikiWeb) |
}}} |
See also [Greedy Page Links|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#GreedyPageLinks] to keep your links short and backward compatibile with the current JSPWiki links. |
|
|
!! More organising concepts |
|
While ~WikiFarms, ~WikiWebs and ~WikiSubPages implement pure hierarchical organising concepts. |
More rich grouping concepts are possible through |
[WikiCategories|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#WikiCategories] and |
[WikiTags|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#WikiTags]. |
|
! ~WikiCategories |
|
~WikiPages can be ''categorised'' into one or more ~WikiCategories. See also [WikiCategory] |
|
In order to mark a page for inclusion in a special category, just link it to the ''category page''. |
Category links can not be distinguished from ordinary page links. |
Typically the categorised pages link back to the category pages via ''Back To...'' or ''More Info...'' or ''See also ...'' links. |
The category page may contain a textual description of the grouping concept. |
It may use the [[{ReferredPagesPlugin}] to automatically list all categorised pages. |
|
%%(background:ff9;) |
Q. Can a category page categorise pages of multiple ~WikiWebs ? I would tend to say yes, |
although the [[{ReferredPagesPlugin}] would need some extra param to search for links |
outside the current ~WikiWeb. |
%% |
! ~WikiTags |
|
|
~WikiPages can be tagged with one or more ~WikiTags. |
|
In order to mark a page with a tag, you will add some ''metadata'' to the page. |
Typically, GUI support is available for easy page tagging |
(select a tag from the existing set of tags of the current ~WikiWeb) |
and to facilitate page searches based on certains tags. |
|
Example: |
{{{ |
[/w:tags/*] =>list all tags in this WikiWeb |
[*[@tag='food']] =>list all pages tagged with 'food' |
}}} |
|
!! Greedy Page Links |
|
The concept of ''greedy page links'' will keep your page links short and provide backward compatibility |
with the current style of page-linking. |
|
When resolving a [[page-link], the wiki-engine will first try to match ''any'' of the |
children of the ''current page''. |
When no match is found, the wiki-engine will continue its search from the root of the ''current ~WikiWeb''. |
Use XPATH expressions to target more specific sets of pages. [4] |
|
With the ''greedy page link alghorithm'', a single [[page-link] can now result in one or more clickable page links. |
By default, the generated set of links are separated with a space. See [Formatting Wiki Links|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#FormattingWikiLinks] to change this formatting. |
|
Example of the ''greedy'' page-link algorithm : |
|| Current Page || Wiki markup... || Links to... |
| /Zoo | [[Food] | /Zoo/Birds/flamingo/Food\\/Zoo/Birds/Stork/Food\\/Zoo/Birds/Stork/Summer/Food |
| /Zoo/Birds | [[Food] | /Zoo/Birds/flamingo/Food\\/Zoo/Birds/Stork/Food\\/Zoo/Birds/Stork/Summer/Food |
| /Zoo/Birds/Stork | [[Food] | /Zoo/Birds/Stork/Food\\/Zoo/Birds/Stork/Summer/Food |
| /Zoo/Birds/Stork/Summer | [[Food] | /Zoo/Birds/Stork/Summer/Food |
| /Zoo/Birds | [[Main] | /Main (the [[Birds] has no ''Main'' page children) |
|
Example of XPATH expresssions : |
|| Current Page || Wiki markup... || Links to... |
| /Zoo/Birds/Stork | [[Summer/Food] | /Zoo/Birds/Stork/Summer/Food |
| /Zoo/Birds/Stork | [[./Food] | /Zoo/Birds/Stork/Food |
| /Zoo/Birds/Stork | [[.//Food] | /Zoo/Birds/Stork/Food\\/Zoo/Birds/Stork/Summer/Food |
| /Zoo/Birds/Stork/Summer | [[../Food] | /Zoo/Birds/Stork/Food |
| /Zoo/Birds/Stork/Sumer | [[..//Food] | /Zoo/Birds/Stork/Food\\/Zoo/Birds/Stork/Summer/Food |
| /Zoo/Birds/Stork | [[../*/Food] | /Zoo/Birds/flamingo/Food\\/Zoo/Birds/Stork/Food |
| any page | [[/Zoo/Birds] | /Zoo/Birds |
| any page | [[/Zoo/Birds/*/Food] | /Zoo/Birds/flamingo/Food\\/Zoo/Birds/Stork/Food |
|
%%(background:ff9;) |
Q. What is the default format of a link ? |
Is it the absolute path, such as {{/Zoo/Birds/Stork/Summer/Food}}. |
Or the relative (and shorter) path, such as {{Stork/Summer/Food}} or {{./Stork/Summer/Food}} ? |
%% |
|
%% |
!!! Wiki Metadata XML model |
|
At line 59 removed one line |
\\''TODO: check how this will work with interwiki links.'' |
At line 64 removed 6 lines |
<w:author> ... </w:author> |
<w:pagename> ... </w:pagename> |
<w:pathname> ... </w:pathname> |
<w:created> ... </w:created> |
<w:lastModified> ... </w:lastModified> |
<w:versionNumber> ... </w:versionNumber> |
At line 239 added 7 lines |
<w:name> ... </w:name> |
<w:path> ... </w:path> |
<w:length> ... </w:length> |
<w:author> ... </w:author> |
<w:created> ... </w:created> |
<w:lastModified> ... </w:lastModified> |
<w:versionNumber> ... </w:versionNumber> |
At line 76 changed 7 lines |
<w:filesize> ... </w:filesize> |
<w:author> ... </w:author> |
<w:filename> ... </w:filename> |
<w:pathname> ... </w:pathname> |
<w:created> ... </w:created> |
<w:lastModified> ... </w:lastModified> |
<w:versionNumber> ... </w:versionNumber> |
<w:properties> |
<w:name> ... </w:name> |
<w:path> ... </w:path> |
<w:length> ... </w:length> |
<w:author> ... </w:author> |
<w:created> ... </w:created> |
<w:lastModified> ... </w:lastModified> |
<w:versionNumber> ... </w:versionNumber> |
</w:properties> |
At line 84 changed 3 lines |
<v1> ... </v1> |
<v2> ... </v2> |
<v3> ... </v3> |
<w:v1> ... </w:v1> |
<w:v2> ... </w:v2> |
<w:v3> ... </w:v3> |
At line 95 changed 3 lines |
<v1> ... </v1> |
<v2> ... </v2> |
<v3> ... </v3> |
<w:v1> ... </w:v1> |
<w:v2> ... </w:v2> |
<w:v3> ... </w:v3> |
At line 288 added 4 lines |
<w:wikiwebs> |
<wikiweb1:homePage> ... <wikiweb1:homePage> |
<wikiweb2:homePage> ... <wikiweb2:homePage> |
</w:wikiwebs> |
At line 113 changed one line |
! Overview of predefined elements inside the Wiki Metadata XML model |
!! Overview of predefined elements inside the Wiki Metadata XML model |
At line 115 changed 2 lines |
|| Name || Description || Type |
| <w:pages> | Set of pages. Used as root element or as a collection of sub-pages | ''pages'' |
|| Child Node || Description || Type |
| <w:pages> | Set of pages. Used as root element or as a collection of sub-pages | ''page'' nodes |
| <w:properties> | Set of properties, or metadata of a page or attachment | ''properties'' |
| <w:attachments> | Set of attachments | ''attachment'' nodes |
| <w:versions> | Set of page or attachment versions | ''page'' or ''attachment'' nodes |
| <w:to> | Set of pages which are being referred by this page (outgoing links) | ''page'' nodes |
| <w:from> | set of pages which are referring to this page (incoming links) | ''page'' nodes |
| <w:wikiwebs> | set of pages referring to the rootpages of all wikiwebs in this wikifarm | ''page'' nodes |
|| Property Node || Description || Type |
| <w:name> | Page or Attachment Name, including punctuations| String |
| <w:path> | Complete path name, including names of parent pages | String |
At line 118 changed 3 lines |
| <w:pagename> | Page Name, including punctuations | String |
| <w:filename> | File Name or an attachment, including punctuations | String |
| <w:pathname> | Complete path name, including names of parent pages | String |
| <w:length> | length (number of bytes) of a page or attachment | number |
At line 124 removed 9 lines |
| <w:filesize> | Filesize (number of bytes) of an attachment | number |
| <w:properties> | Set of properties, or metadata of a page or attachment | ''properties'' |
| <w:attachments> | Set of attachments of a page | ''attachments'' |
| <w:versions> | set of page or attachment versions | ''pages'' or ''attachments'' |
| <w:to> | Set of pages which are being referred by this page (outgoing links) | ''pages'' |
| <w:from> | set of pages which are referring to this page (incoming links) | ''pages'' |
| <w:parent> | Parent page | ''page'' |
|
|
At line 135 changed 3 lines |
The contents of a ''page'' or ''attachment'' always refers to its current state. |
The {{<w:versions>}} element provides a set of pages or attachements of |
all past __and current__ versions. |
* __Wiki Names__\\ |
Page or Attachment nodes use a wiki-name without punctuations or blanks. |
The {{<w:name>}} property contains the full name, including punctuations and blanks. |
At line 318 added 4 lines |
* __Versions node__ \\ |
Page or Attachment nodes always refer to their current state. |
The {{<w:versions>}} node contains references to all past __and current__ versions. |
Each version gets a unique sequence number propery like this: {{w:v1}}, {{w:v2}}, {{w:v%%sub xx%%}}. |
At line 140 changed one line |
All sibling ''pages'', sibling ''attachments'' or sibling ''properties'' are assumed to be unique. In other words, there can not be a page with the same name inside a single w:pages element. |
* __Same Name Siblings__ (JSR-170[1], chap 4.3) \\ |
All nodes inside {{<w:pages>}}, {{<w:attachments>}} or {{<w:property>}} must have a unique name. |
In other words, there can not be a page with the same name |
inside a single {{<w:pages>}} node; all page properties have unique names etc. |
(multi-value properties need further investigation) |
At line 142 changed one line |
The <w:from> and <w:to> are ''virtual'' elements, in the sense that they are computed on request, rather then being physically present in the document tree. |
* __Virtual nodes__ \\ |
The {{<w:from>}} and {{<w:to>}} nodes are ''virtual'' in the sense that they are computed |
on request, rather then being physically present in the document tree. |
At line 159 changed 2 lines |
/w:pages/SandBox/w:versions/v127/w:properties/versionLabel |
=> SandBox/v127/@versionLabel |
/w:pages/SandBox/w:versions/w:v127/w:properties/versionLabel |
=> SandBox/w:v127/@versionLabel |
At line 377 added 3 lines |
You can use local wiki page variables inside xpath expressions too, prefix them with a $. |
{{{ |
[{SET node='Main' }] |
At line 189 changed one line |
!Implementation |
[$node/w:to] |
}}} |
At line 384 added 2 lines |
! Implementation |
|
At line 197 changed one line |
!! Wiki Link Format |
!!! Formatting Wiki Links |
At line 210 changed one line |
[./w:filesize|Sanbox/attach.png] --todo check this out |
[@w:length|Sanbox/attach.png] |
At line 222 changed one line |
[* ./w:pagename has version @liveVersion, here is the [link|.] |Sandbox/w:to] |
[* @w:name has version @liveVersion, here is the [link|.] |Sandbox/w:to] |
At line 227 changed one line |
[{SET format='* ./w:pagename has version @liveVersion, here is the [link|.]' }] |
[{SET format='* @w:name has version @liveVersion, here is the [link|.]' }] |
At line 239 changed one line |
[{SET tableformat='| ./w:pagename | @liveVersion | [link|.]' }] |
[{SET tableformat='| @w:name | @liveVersion | [link|.]' }] |
At line 439 added 17 lines |
%%(border-left:4px solid silver; padding-left: 1.5em;) |
!!! Footnotes |
|
[#1] JSR-170 : see [http://www.jcp.org/en/jsr/detail?id=170] |
|
[#2] Inspired by lots of stuff on the jspwiki mailing list, also on [http://twiki.org/cgi-bin/view/Codev/OrganizingPrinciples] |
|
[#3] ~WikiWebs may define they own global pages suchs as [[LeftMenu] etc. |
By default, a ~WikiWeb will ''inherit'' these pages from the default ~WikiWeb at creation.\\ |
Example contents of [[LeftMenu] of a newly created ~WikiWeb: |
{{{ |
[{InsertPage page='<default-wiki-web>:LeftMenu'}] |
}}} |
|
[#4] [The greedy page link|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#Greedy page link] algoritm actually executes following XPATH expressions: |
* If not-empty, return {{[[.//pagename]}} : matches all subpages of the current page |
* Otherwise return {{[[//pagename]}} : matches all subpages of the root page of the current ~WikiWeb |
At line 457 added 2 lines |
|
%% |
At line 335 removed one line |
[Rolf subpage requirements|IdeaWikiLinksThroughXPATHIncludingSubPagesSupport#I noticed a gap in the definition of subpage] |