pWiki/bootstrap/Doc/Path.md

pWiki Path

XXX a Wiki is a set of pages, mostly top level pages, mosty titled in WikiWord style, pWiki follows this culture but does not restrict either page nesting or title formatting. But following this style is recommended.

XXX write a set of recommendations...

Basic terminology

Path
One or more names separated by "/" that identifies a view.

We call the last name in the path sequence a title.

We call the sub-path without the title a basedir or simply dir.

In pWiki, there is no distinction between a page and a directory, thus we do not use the term, instead, we may use the term sub-page

View
A path that resolves to a page that may or may not be at that specific path.

(see: Page acquisiton below)

Page
A set of data associated with a path.

A page is identified by it's path, but this does not require that every sub-path of that path must exist.

XXX a word about bootstrap pages that can't be deleted...

WikiWord
XXX

Page acquisition

pWiki path system differs from how traditional file system paths are handled. In pWiki if a path does not reference a page directly a search is conducted to find an alternative page. This search is call page acquisition.

Acquisition process:
A set of rules defining how a page is retrieved via a path.

This is used as a simple and uniform mechanism to:

• Get default pages for specific situations
  Like [Templates/EmptyPage] to handle the page not found condition.
• define generic templates/pages accessible by multiple pages in path
  A good example would be the viewer used to show this page [Templates/_view] and all of it's chrome like the path above and links in the footer (when viewing through pWiki)
• Overload default templates/pages

The acquisition order/rules:

1. if path matches a specific page, target page is found
2. if path does not match a page:
3. if title matches a page in the parent path, page is found
4. repeat until we either have a match or reach root (empty basedir)
5. if no match is found, check if title exists in [Templates] in basedir
6. if no match is found, check if title exists in [/System]
7. if no match is found, repeat process for EmptyPage instead of title

Example:

For path Path/To/Page the following paths are checked in order and the first matching page is returned:

• Check path as-is then go up:
  • Path/To/Page
  • Path/Page
  • Page
• Check in Templates, in path and up:
  • Path/To/Templates/Page
  • Path/Templates/Page
  • Templates/Page
• Check root System:
  • System/Page
• Check EmptyPage in path, then in templates:
  • Path/To/EmptyPage
  • Path/EmptyPage
  • EmptyPage
  • Path/To/Templates/EmptyPage
  • Path/Templates/EmptyPage
  • Templates/EmptyPage (This is guaranteed to exist)

Exceptions:

• System/settings is global and can not be overloaded for use as system configuration. This is done for security reasons.

Default pages

XXX

• Templates/EmptyPage
• Templates/EmptyToDo
• Templates/EmptyOutline

Relative and absolute paths (".", ".." and "/")

XXX

Path patterns ("*" and "**")

XXX

Path actions

XXX path elements that perform actions on pages but do not actually correspond to actual pages.

Path variables

$NOW

XXX

Also see the \@now() macro: [Doc/Macros].

WikiWord

XXX not actualy part of the path spec but a way (culture) to define paths in pages + automatic link creation.