1 3281ec97 2023-03-06 jrmu version=pmwiki-2.3.4 ordered=1 urlencoded=1
2 3281ec97 2023-03-06 jrmu author=MFWolff
3 5127fd58 2021-12-17 jrmu charset=UTF-8
4 3281ec97 2023-03-06 jrmu csum=path trail (+89)
5 5127fd58 2021-12-17 jrmu name=PmWiki.WikiTrails
7 5127fd58 2021-12-17 jrmu targets=PmWiki.PageLists,PmWiki.GroupHeader,PmWiki.Links,PmWiki.ListStyles,Cookbook.CSSInWikiPages,PmWiki.Installation,PmWiki.LocalCustomizations,PmWiki.PmWiki,PmWiki.PmWikiPhilosophy,PmWiki.WikiStyles,PmWiki.Uploads,PmWiki.InterMap,Cookbook.Cookbook,PmWiki.TextFormattingRules,PmWiki.DesignNotes,PmWiki.Security,PmWiki.Troubleshooting,PmWiki.GroupHeaders,PmWiki.ConditionalMarkup,PmWiki.FullName,PmWiki.WebFeeds
8 3281ec97 2023-03-06 jrmu text=(:Summary: Trails from lists items from a single page:)%0a(:Audience: authors (basic) :)%0aThe WikiTrails feature allows wiki authors to create "trails" through sequences of pages in the wiki. You simply specify pages and their order on a "trail index", and then place the navigation markup on the pages that you will be navigating. %0a%0a(Don't confuse the [[PmWiki/PageLists|pagelist]] directive with WikiTrails - they are different animals as explained in the [[#faq|Q and A]] below.)%0a%0a[[#types]]%0a!! Trail types%0aPmWiki defines 2 trail markups, specifying a trail index link:%0a%0a* %25pmhlt%25[@%3c%3c|[[Trail Index Page]]|>>@] displays as "[=%3c%3c PreviousPage | Trail Index Page | NextPage >>=]".%0a%0a* %25pmhlt%25[@%3c|[[Trail Index Page]]|>@] displays as "[=%3c PreviousPage | Trail Index Page | NextPage >=]", except the appropriate arrow is omitted at the beginning and end of the trail.%0a%0aand for a [[#pathtrail| trail path]]:%0a* %25pmhlt%25[@^|[[TrailIndexPage]]|^@]%0a%0aMarkup is most often added to a [[group header]] or group footer.%0a%0a[[#linksyntax]]%0a!! Trail index page link markup%0aThe trail index page link has the same markup as a standard [[link(s)]], %0athis means for example you can specify:%0a* %25pmhlt%25[@%3c|[[TrailIndexPage | +]]|>@]%0a* %25pmhlt%25[@%3c%3c|[[TrailIndexPage | A description]]|>>@]%0a%0aTrail index page links can be restricted by [[links#anchors|anchors]] (links to a specific location within a page),%0athis means you can have more than one trail on a page, or start a trail from a specific location in a page.%0a* %25pmhlt%25[@%3c|[[Trail Index Page(#trailstart#trailend)]]|>@]%0a%0a[[#creating]]%0a!! Creating a trail index%0a%0aBefore you can use a trail through a set of pages, you have to create a "trail index" on a separate page, which we will call the "trail index page". %0aOn that trail index page, you simply create a numbered, bulleted, or definition [[PmWiki:ListStyles|list]] of links. (So every numbered or bulleted list of links implicitly creates a trail.) %0a%0aIt is important that each page name ([[Links|link]]) be the first item following each bullet; any text or formatting in front of the page name link will exclude it from the trail.\\%0aIf you want to style your trail index, you can [[Cookbook:CSSInWikiPages|include a CSS]].%0a%0aAn example trail index page might be the following list:%0a[[#trailstart]]%0a* [[Installation]] how to install%0a* [[The customisation page->LocalCustomizations]]%0a* [[PmWiki]] some other text [[PmWiki Philosophy]] [-(The latter won't be in the trail because it is preceded by text)-]%0a* Yet some other text. [[PmWiki.WikiStyles]] [-(This won't be in the trail because it follows text)-]%0a* %25center%25[[PmWiki/Uploads]] [-(This won't be in the trail because it is preceded by the [=%25center%25=] style.)-]%0a%0a* Some text [-(This won't be in the trail because it is not a link)-]%0a* [[PmWiki/PageLists]] {PmWiki/PageLists$:Summary}%0a* [[https://pmwiki.org]] [-(This won't be in the trail because it is not a page link)-]%0a** [[PmWiki:InterMap]] [-(This won't be in the trail because it is an [[InterMap]] link)-]%0a* [[Cookbook:Cookbook]] [-(This won't be in the trail because it is an [[InterMap]] link)-] %0a: [[PmWiki philosophy]] : [[Design notes]] [-(The first link in this definition list will, and the second link won't, be in the trail defined by ([[TextFormattingRules#DefinitionLists | definition list]]))-]%0a* [[#security]][[Security]] [-(This won't be in the trail because its preceded by a (hidden) [[Links#anchors | anchor]])-]%0a* %25newwin%25[[Links]] [-(This won't be in the trail because its preceded by a (hidden) [=%25newwin%25=] style)-]%0a* ''[[PmWiki/Troubleshooting]]'' [-(This won't be in the trail because its preceded by (hidden) ''italic'' style markup)-]%0a[[#trailend]]%0a%0aThe list above creates the following "wikitrail", displayed using a [[PageLists|pagelist]]:%0a(:markup:)%0a(:pagelist trail={$FullName}#trailstart#trailend fmt={$FullName}#traillist:)%0a(:markupend:)%0a%0a[[#observations]]%0a!!! Observations%0a%0a# In general, indentation levels in the page list don't matter -- trails are a linear sequence of pages.%0a# A page is part of the trail only if the page link immediately follows the list markup.%0a# The list itself can be [[#linksyntax|delineated]] by the use of [[#list#anchors|anchors]], allowing for multiple lists on a page, or for some list items to be excluded.%0a%0a[[#using]]%0a!! Using the trail%0a%0aWhat 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).%0a%0aTo build a trail, add ''trail markup'' like %25pmhlt%25[@%3c%3c|[[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. %0a%0aThe trail markup can be placed anywhere in a group header or footer, or on a page. 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 [[Group Headers | Group Header]] or Group Footer pages instead of on every individual page in your group.%0a%0a[[#pathtrail]]%0a!!! Path trail[[#path-trail]]%0a%0a%25pmhlt%25[@^|[[TrailIndexPage]]|^@] treats the list levels as a hierarchy and displays the "path" to reach the current page (i.e., a "breadcrumb" trail). %0a%0a* %25color=#0066CC%25TrailPage1 %0a* %25color=#0066CC%25TrailPage2 %0a** %25color=#0066CC%25TrailPage3%0a** %25color=#0066CC%25TrailPage4%0a%0aIn the example trail above, the markup %25pmhlt%25[@^|TrailIndexPage|^@] on [@TrailPage4@] would display "[=TrailIndexPage | TrailPage2 | TrailPage4=]".%0a%0aWiki administrators can change the trail separator of the "path" trail ( %25pmhlt%25[@^|[[TrailIndexPage]]|^@] ) from the default | by setting the variable @@$TrailPathSep@@ in the ''config.php'' file. For instance @@$TrailPathSep = ' > ';@@ will output "[=TrailIndexPage > TrailPage2 > TrailPage4=]".%0a%0a[[#circular-trails]]%0a!! Circular trails%0a%0aTypically, 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:%0a%0a->%25pmhlt%25[@%0a * [[TrailPage1]]%0a * [[TrailPage2]]%0a ...%0a * [[TrailPageN]]%0a * [[TrailPage1]]%0a@]%0a%0aIf the trail index page is intended to be read by others, the last item can be made invisible inside an [@(:if false:)@] block:%0a%0a->%25pmhlt%25[@%0a * [[TrailPage1]]%0a * [[TrailPage2]]%0a ...%0a * [[TrailPageN]]%0a (:if false:)%0a * [[TrailPage1]]%0a (:ifend:)%0a@]%0a%0a[[#crossgroup]]%0a!! Cross Group Trails%0aBefore version 2.2.1, if your trail contains pages in different groups, it should use full [=[[Group.Name]]=] links instead of just [=[[Name]]=].%0a%0a!! Other notes%0a* There is no space between @@[=%3c|=]@@ and @@[=[[link]]=]@@ and @@[=|>=]@@; same for the other trail markups.%0a* Note that non-existing pages will appear in the WikiTrail as links.%0a* [[Conditional markup]] supports the [[ConditionalMarkup#ontrail | ontrail]] query.%0a* [[Page lists]] provides the [[PageLists#pagelisttrail | trail=]] parameter.%0a%0a[[#trailstyle]]%0a!!! Trail style%0aPmWiki encapsulates the trail with a @@''wikitrail''@@ css class. %0aThis allows the wiki trail to be [[LocalCustomizations | customised]] by defining CSS for the ''wikitrail'' in the @@''local.css''@@ file.%0a%0a%0a[[#trailpagelists]]%0a!!! Trail in [[page lists]]%0aTrails from a single page can only be displayed using the pagelist [[PmWiki/PageLists#pagelisttrail|trail]] parameter. For example%0a(:markup:)%0a(:pagelist trail=PmWiki/WikiTrails#trailstart fmt=PmWiki.WikiTrails#traillist order=random,$Name count=3:)%0a(:markupend:)%0a%0a!!!A simple example of a WikiTrail%0a%0a1) On the TrailIndexPage:%0a%0a%25pmhlt%25[@%0a* [[MyTrailPage1]]%0a* [[MyTrailPage2]]%0a* [[MyTrailPage3]]%0a@]%0a%0a2) On the pages MyTrailPage1, 2, and 3:%0a%0a%25pmhlt%25[@%0a%3c%3c|[[TrailIndexPage]]|>>%0a@]%0a%0a>>comment%3c%3c%0a[[#traillist]]%0a%25font-size:small green%25> [[{=$FullName}|{=$Groupspaced}.{=$Namespaced}]] %3c%0a[[#traillistend]]%0a>>%3c%3c%0a%0a!! FAQ%0a[[#faq]]%0a>>faq%3c%3c%0aQ: What's the difference between a [[PmWiki/PageLists|PageList]] and a WikiTrail?%0aA: The pagelist directive dynamically generates a list of pages. There are many ways to generate the list, including using a WikiTrail as the source. \\%0aThe pagelist directive then displays the pages that match the criteria using an optional template - for example displaying each page name on a separate line as a link or including the entire content. \\%0aThe pagelist directive currently does not have built-in navigation markup that you can put on the pages in the list. \\%0aBy contrast, WikiTrails are simply specified via links on an "index" page and you ''can'' put previous-next navigation markup on each page. The two serve very different purposes. WikiTrails are useful for specifying the pages in [[PmWiki/WebFeeds|web feeds]], for creating a "tour" through a predefined set of pages, and many other things.
9 3281ec97 2023-03-06 jrmu time=1652170980
