• View
• Edit
• History
• Print
• Backlinks

WikiTrails

The WikiTrails feature allows wiki authors to create "trails" through sequences of pages in the wiki.

The idea is explained in Vannevar Bush's 1945 article As We May Think(approve links), section 7, which describes an implementation using microfilm inspired by the trails of association in human thinking:

Creating a trail

Before you can use a trail through a group of pages, you have to create a "trail index" on a separate page, which we will call the "trail index page". On that trail index page, you simply create a numbered or bulleted list of links. (So every numbered or bulleted list of links implicitly creates a trail.) It is important that each page name (link) be the first item following each bullet.

An example trail index page might contain:

• Installation how to install
• The customisation page
• PmWiki some other text PmWiki Philosophy (The latter won't be in the trail because it is preceded by text)
• Yet some other text. PmWiki Features (This won't be in the trail because it follows text)
• Download (This won't be in the trail because it starts with the %centre% style.)
• PmWiki.WikiStyles
• Some text (This won't be in the trail because it is not a link)
• PageLists
• http://pmwiki.org (This won't be in the trail because it is not a page link)
  • Features
• PmWiki:InterMap (This won't be in the trail because it is an InterMap link)
• Cookbook

PmWiki philosophy

Design notes (The first link will, and the second link won't, be in the trail (definition list))

• Security (This won't be in the trail because its preceded by a (hidden) anchor)
• Links (This won't be in the trail because its preceded by a (hidden) %newwin% style)
• Troubleshooting (This won't be in the trail because its preceded by a (hidden) italic style)

1. PITS
   1. 00895

creates the following "wikitrail", using pagelist to display it:

(:pagelist trail={$FullName}#trailstart#trailend
fmt={$FullName}#traillist:)

Observations

1. In general, indentation levels in the page list don't matter -- trails are a linear sequence of pages.
2. A page is part of the trail only if the page link immediately follows the list markup.

Trail types

PmWiki defines 2 trail markups:

• <<|[[Trail Index Page]]|>> displays as "<< PreviousPage | Trail Index Page | NextPage >>".
• <|[[Trail Index Page]]|> displays as "< PreviousPage | Trail Index Page | NextPage >", except the appropriate arrow is omitted at the beginning and end of the trail.

Trail link syntax

The trail link has the same syntax as a standard link, this means for example you can specify

• <|[[TrailIndexPage | +]]|>

Trail links can be restricted by anchors (links to a specific location within a page), this means you can have more than one trail on a page, or start a trail from a specific location in a page.

• <|[[Trail Index Page#trailstart#trailend]]|>

Using the trail

What makes a trail "work" is adding trail markup on the pages in the trail (i.e. the pages that are listed in the bullet/numbered list on the trail index page).

To build a trail, add trail markup like <<|[[TrailIndexPage]]|>> to a page, where TrailIndexPage is the page, described above, containing the bulleted list of pages in the trail. PmWiki will display the trail markup with links to any previous and next pages in the trail.

The trail markup can be placed anywhere in a page, and a page can contain multiple trail markups. If you are adding a trail to every page in a group, consider setting the trail markup in the GroupHeader or GroupFooter pages instead of on every individual page in your group.

Path trail

^|[[TrailIndexPage]]|^ treats the list levels as a hierarchy and displays the "path" to reach the current page (i.e., a "breadcrumb" trail). In the example trail above, the markup ^|TrailIndexPage|^ on TrailPage4 would display as "TrailIndexPage | TrailPage2 | TrailPage4".

Wiki administrators can change the trail separator of the "path" trail ( ^|[[TrailIndexPage]]|^ ) from the default | by setting the variable $TrailPathSep in the config.php file. For instance $TrailPathSep = ' > '; will output "TrailIndexPage > TrailPage2 > TrailPage4".

Circular trails

Typically, a trail is a linear list with a first and a last page. However, the trail can be made "circular" by repeating the first page as the last item in the trail index:

 * [[TrailPage1]]
 * [[TrailPage2]]
 ...
 * [[TrailPageN]]
 * [[TrailPage1]]

If the trail index page is intended to be read by others, the last item can be made invisible using %item comment%:

 * [[TrailPage1]]
 * [[TrailPage2]]
 ...
 * [[TrailPageN]]
 * [[TrailPage1]] %item comment%

Cross Group Trails

Trail pages on both sides of group boundaries must be fully qualified with group names.

Other notes

Trail style

PmWiki encapsulates the trail with a wikitrail css class. This allows the wiki trail to be customised by defining CSS for the wikitrail in the local.css file.

Trail in page lists

Trails from a single page can only be displayed using the pagelist trail parameter. For example

(:pagelist trail=PmWiki/WikiTrails
fmt=PmWiki.WikiTrails#traillist
order=random count=3:)

Questions

How can the trail be made to start at (or from) the "parent page"?

That is the first trail markup should be visible on the "parent page". In the example below the next and prev pages should show as (arbitrarily) the first and last pages on the trail (excluding any loop entry).

<|[[{$FullName}]]|>

Why doesn't my trail show up?

Don't provide link text or title markup. (This is probably a bug for feature that needs a PITS. entry).

<| [[Documentation index | +]] |> 

<| [[Documentation index | link
text]] |> 

<| [[Documentation index]] |>