Name

Navigation Bar — Left margin navigation for HTML

Synopsis

package require htmlgen

::htmlgen::sidenav::sidenav pathvar url tree \
   ?attr=value ...? ?control? ?body ...?

Description

The command sidenav is a markup macro which creates a navigation bar on the left side of the page and puts the body information into the right side of the page. The navigation bar's width, background color and so an can be controlled by attributes as if it were a normal html markup command.

The pathvar is the name of the variable which selects a certain node within the given tree. The url is used to construct href-links in the page. The details are described below.

The tree parameter

The tree parameter of sidenav must be a list of 3*n elements

{ name title subtree name title subtree ... }

An Example:

set Navtree {
  oview "Overview" .
  xmlgen "XML generator" .
  htmlgen "HTML generator" {
    tab "Notebook Tabs" .
    nav "Sidebar Navigation" .
  }
}

The first element of every triple is a shortcut name. Consider it as an identifier for the node. It will be used programmatically and will be passed around in URLs. The 2nd element is a text which will show up on the HTML page as a link. Each of the subtrees must have the same multiple-triple structure again or must be a single dot indicating that the respective node is a leaf node.

The pathvar and the url parameter

The pathvar parameter must contain the name of a variable. It servers two purposes. First, the name will be in URL construction and second, the variable itself must contain a path into the tree. As an example, consider the following call to sidenav which makes use of tcllib's package ::ncgi.

set Path [::ncgi::value Path [list oview]]
set url [::ncgi:urlStub]
sidenav Path $url $Navtree ! { ... }

We use ::ncgi::value to retrieve the selected path into the tree from the calling URL. Just in case the URL was typed in by hand or does not contain the variable Path for other reasons, we specify [list oview] as the default path. With ::ncgi::urlStub the URL which called our script is retrieved. All links created in the navigation bar will look like

${url}?Path=[cgiset $pathForTheLink]

If such a link is followed, the flow of control will arrive again in the script, ::ncgi::value will set Path to the value of pathForTheLink and that path will be marked as selected in the navigation bar.

The control and body parameters

These parameters work like for normal markup commands as described in xmlgen. Within the body, you will most likely want to use the content of the variable passed by pathvar to switch between different contents depending on the selected node.

Syntactically they behave exactly like for normal markup commands as described in xmlgen. However, since sidenav creates an elaborate HTML structure, they end up distributed over several HTML tags.

To understand their meaning, it is necessary to know that sidenav create a <table> with two columns. The left column contains the navigation bar and the right one is filled by the body parameter. Arbitrary attributes can be placed into the <table> tag as well as into the <td> tags of the left and the right column. This is done by prefixing the attributes with main., nav. or txt. respectively.

For example passing nav.width=200 and nav.bgcolor=gray to sidenav will result in a gray navigation bar with a width of 200 pixels. Note that no sanity check is performed on those attributes. They are just pasted into the respective HTML tags.

The curColor attribute

There is currently one attribute which is not just pasted into one of the table tags, namely curColor (no prefix necessary). It should be an acceptable color value and determines the text color for the selected branch of the navigation tree.

See Also

Overview, Xmlgen, Htmlgen, Notebook Tabs