= TracNav Usage =
[[TracNav]]

To use !TracNav, you have to 
 * create an index page for your site and 
 * call the !TracNav macro on each page, where the navigation bar should be displayed.
Both steps are explained in detail in the following sections.

== Table of contents == 

The index page is a regular wiki page. This example uses the wiki page named [wiki:TracNav/TOC TracNav/TOC] to hold the table of contents for the !TracNav documentation. The page with the table of contents must include an unordered list of links that should be displayed in the navigation bar.

Here is an example of such table of contents. '''Note''': currently, you should only use the {{{[wiki:<Name> <Label>]}}} syntax for links that should be displayed in the navigation bar. CamelCase-style links are rendered correctly, but !TracNav itself doesn't recognize them as links, so e.g. [#Selection selection] will not work.

{{{
 * [wiki:TracNav TracNav]
   * [wiki:TracNav Overview]
   * [wiki:TracNav/Install Install]
   * [wiki:TracNav/Usage Usage]
   * [wiki:TracNav/Download Download TracNav]
 * See also
   * [wiki:JavaParty JavaParty]
   * [wiki:KaRMI KaRMI]
}}}

== Display the navigation bar == 

[[TracNav(TracNav/TOC)]]

To display the navigation bar on a page, you must call the !TracNav macro on that page and pass the name of your table of contents as argument. With this approach, you can create multiple separate table of contents on your site. By following the links in the "See also" section, you can explore the usage of !TracNav on the JavaParty home page.

In this example, the following macro call is used to bring the table of contents stored in [wiki:TracNav/TOC TracNav/TOC] to this page. Place such macro invocation somewhere at the head of your wiki page (preferably directly after the main headline). 

{{{
[[TracNav(TracNav/TOC)]]
}}}

This page contains even two calls to the !TracNav macro. The first call displays (at the top of the page) the main navigation bar for the JavaParty site, while the second (displayed directly to the right) refers to a TOC page containing the example shown above.

Since r3071 it is possible to have more than one index page for your TOC: Simply list them all separated by a bar like this:

{{{
[[TracNav(MyTOC|AnotherTOC)]]
}}}

The TOCs are appended to each other to form one navigation bar.

== Presentation rules == 

For each page that displays a navigation bar, a certain set of information is selected from the TOC page. This keeps the displayed navigation bar small, while allowing fast access to a large set of information. Anyway, you must consider these selection and presentation rules when design the TOC.

=== Selection ===

The TOC page consists of nested unordered lists of topic links as shown above. When the navigation bar is displayed on a page that is '''not''' linked from the TOC, no selection occurs and the completely "opened" navigation bar is displayed. An example for this is the main [wiki:TOC TOC] page itself. If the page is linked from the TOC page, selection occurs. In that case, only those topics are displayed that are either siblings, ancestors or siblings of ancestors of the currently displayed topic.

=== Headlines ===

A topic is displayed as headline in bold face, if it contains sub-topics. Examples are the lines "{{{* [wiki:TracNav TracNav]}}}" and "{{{* See also}}}" from the example TOC above. 

If a headline itself is a link, its sub-topics are collapsed, if it is not an ancestor of the currently displayed topic.

  When being '''collapsed''', the headline is rendered as link to the referenced topic with appended {{{...}}} characters. An example for this are the "{{{* [wiki:JavaParty JavaParty]}}}" and "{{{* [wiki:KaRMI KaRMI]}}}" lines from the main navigation bar displayed top on the current page. 

  It is a good idea to let a headline link point to one (normally the first) of its sub-topics (which is the overview page for that topic). This rule can also be observed in the example TOC above: Both links in "{{{* [wiki:TracNav TracNav]}}}" '''and''' "{{{* [wiki:TracNav Overview]}}}" point to the same page namely "{{{wiki:TracNav}}}".

If a headline is not a link, it's never collapsed. Instead, its direct child topics are always displayed (if the headline itself is displayed). An example for this is the "{{{* See also}}}" line in the example TOC seen above. This headline style can be used to add structure to the navigation bar by simultaneously restricting selection. If you remove the lines from all your headlines, always the completely opened navigation bar is displayed on each page. 

== Options ==

!TracNav also understands some options, passed as regular arguments when calling the macro:

 * '''nocollapse''': prevents any collapsing or reordering of toc entries, thus displaying the full toc.
 * '''noreorder''': prevents the top-level of the toc from being reordered, collapsing still takes place.
 * '''noedit''': hides the `edit` link that otherwise would be displayed if the current user has enough rights to edit to wiki page(s) used for the toc.
 * '''allowed_macros''': specify the list of macros that are expanded within TOC entries. Use with care. ''Default:'' `Image` (since [3266]) 

If multiple options should be specified, they must be separated by `|`. Example: `[[TracNav(MyTOC|noedit|noreorder)]]`.