• View
• Edit
• History
• Attach
• Print

00398

Description: The mailing list has had various threads about navigating wiki trails and wiki categories. This is a summary. The requirements range from lite -- minor but useful extensions to existing capabilities -- to full strength -- major extensions to the power of trails -- to heavy duty -- the suburban assault (er, utility) vehicle hits the trail.

There is an opportunity to clarify the ways in which PmWiki/WikiTrails and Categories can complement one another. This page assumes you are familiar with both sets of capabilities. A trail page is like a table of contents; the category group is like an index.

The following discussion uses the <<|TrailPage|>> notation in examples. All proposals apply equally to <|TrailPage|> and ^|TrailPage|^.

Contributors include chr, Pm, Radu, and others.

Trails Lite (do now)

Authors commonly put trail markup in a GroupHeader or a template. Provide a way to suppress trail output if the current page is off-trail:

• proposed solution is <<|?TrailPage|>> -- a question mark after the | separator
• we could write <<|?[[trail page]]|>> instead

Use DynamicWikiTrails trails, the URL determines whether a page is on or off trail.

With the introduction of categories, authors want to use a category page as an automatically-maintained trail. How is this going to be maintained if the categories are dynamic? I mean, you can't make a trail simply by alphabetical order of page names or some such; the best feature of a trail is that people can decide on the order of the pages in the trail. -Radu Um, why not? If you need to define the order, use a manual trail page, not a category page. TINFL Always suppress trail output if the current page is off-trail:

• proposed solution is <<|!CategoryPage|>> -- an exclamation mark after the | separator
• we could write <<|![[category page]]|>> instead
  Why is this not <<|[[!CategoryPage]]|>> ? --Pm
  I asked myself the same question when composing the page and tentatively concluded (a) to be consistent with <<|?[[trail page]]|>> (b) we may want <<|[[!Cat1]]|>> to mean 'look for a normal trail on page Category.Cat1' (c) so that a search for '!Cat1' or Category.Cat1 doesn't accidentally return a hit --jr

With some pages containing multiple trails, we need a simple method to list multiple trail pages. Also, some people prefer directives to markup:

• proposed solution is (:trails TrailPage1 ?TrailPage2 !CatPage:)
• an alternative solution is <<|TrailPage1 ?TrailPage2 !CatPage|>>
• to avoid bad line breaks, each trail is a new paragraph

Use DynamicTrails, DynamicWikiTrails and PageListExtensions to automatically list all the trails the pages is on.

Trails Full Strength (do later)

It should be easy for an author to set up a new trail page and automatically get trail navigation links, without having to add new markup to the pages on the trail:

• proposed solution is <<|!!CatPage|>> or (:trails !!CatPage:) markup -- 2 ! marks
• on a new TrailPage, add [[!trail]] markup to place it in Category.Trail
• on a new Category.Page, add [[!category]] markup to place it in Category.Category
• in a GroupHeader, write (:trails !!Trail !!Category:) -- the 2 ! say go to all pages in Category.Trail and Category.Category and generate page lists from them; then create suitable trail navigation for the current page

• in this example, one list of pages is static and the other is dynamic

There is nothing special about the words [[!trail]] and [[!category]] -- they are just handy examples.

Now we turn to the question of dynamically turning trail navigation on and off, depending on what the visitor clicks...

When a visitor arrives on a page for the first time, all trails through that page should be "lit". When the visitor starts following a trail, other trails through the current page should "turn off". If the visitor leaves the trail for another page, such as by following an off-trail link, any trails through the new page should light up. So:

• proposed solution is that << PreviousPage | TrailPage | NextPage >> should generate [[PreviousPage(?trail=TrailPage)]] and [[NextPage(?trail=TrailPage)]]
• if I click previous or next, PmWiki now knows that I am moving along TrailPage's trail (from the ?trail=TrailPage in the address)
• so PmWiki can hide any other trails that may pass through the new page
• only trail links carry a ?trail= so following any other link will re-light the trails

This can be done with a combination of: DynamicTrails, DynamicWikiTrails and PageListExtensions.

And this works whether the ?trail= a static wiki trail or a dynamic category trail.

Trails Heavy Duty (do one day)

But there is yet more we could do...

An author may want to control the placement of the trail navigation on the page, using trail information from the GroupHeader, GroupFooter or template:

• proposed solution is that <|> indicates "put the trail output here"

With DynamicWikiTrails an author may control the placement of the output.

An author may want to create a hierarchy of categories with associated trail navigation:

• proposed solution is that (:trails !!!CatPage:) would unravel a category structure like this...

• pages A[i] and B[i] could be category pages or trail pages -- the lists of stops on these pages define the trails

And somehow generating trail navigation using category pages has to be fast, so PmWiki can't search every page of the wiki every time to build the trail of pages in that category:

• a possible solution is to maintain a Main.AllCategories page, as a special kind of trail (cf Main.AllRecentChanges)
• [[FullName]]: [[!cat 1]] [[!cat 2]]
• but there's probably a better way...

Trail extensions (possibly never necessary)

If there's ever a need to centrally define stuff for a given trail, that should be done on the trail page (the alternative would be redundant repetition on every page that sports the trail markup, which is usually a very, very bad idea).

In that case, we'd probably need a markup like (:trail <option> <option> ...:) on the trail page.
Special trail markups can be defined using PageListTemplates, see DynamicTrails.

Joachim Durchholz March 27, 2005, at 09:37 AM