This include file defines a complex navigation bar container tag named
<navbar:define>. It can be used to define navigation bars of any
optical style by specifying its parts in general and individually and letting
the <navbar:render> tag create the complete particular HTML code.
Creating a navigation bar is a two step process. First you define it according
to this grammar:
or in other words: navigation bar consists of an optional header and
footer, up to three different (according to type) prologs and epilogs for
the navigation buttons and at least one actual navigation button.
Additionally a filter can be applied. The navbar:XXXX names in the above
grammar directly correspond to the existing tags you have to use.
After you have defined such a navigation bar (which is usually done inside an
include file) you can create the corresponding HTML markup code by placing
<navbar:render> at the point where this markup code should occur.
This tag can be used more then once when you want (for instance inside a page
header and its footer or once with graphics and once with the txtonly
attribute for the textual version, etc.).
Always notice that <navbar:render> has no internal built-in
knowledge of your navigation bar except its structure according to the above
grammar. So, you only receive nice results when you define a nice grammar
instance with the available navbar:XXXX tags. The
<navbar:render> tag is not there to create nice things you usually
couldn't do yourself. It is there to avoid the nasty compilation of one
million prologs and epilogs for each button where each of these consists of
similar HTML code. So, <navbar:render> is your workhorse, the
intelligence is yours.
But how do we actually get navigation bars? Haven't we forgot something which
is essential to navigation bars? Yes, we have. Navigation bars feature is that
we can define them at one point for the underlaying hyperlink structure and
use them at any point inside this structure while the hyperlinks are
automatically aligned for the current location. But this feature the core of
WML already provides through its adjustable path variables. So, this include
file is useless without this feature. Or in other words: You really have to
define some root-variable of your structure in a .wmlrc file and then use
this variable when defining the hyperlinks inside the <navbar:button>'s
url attribute. Never forget this point!
This sets the name of the navigation bar which is used both for internal data
respresentation and for referencing in <navbar:debug> and
<navbar:render>. Always use this attribute (or you risk other
navigation bars to be overwritten) and always use a unique name here when
using more then one navigation bar.
This contains a colon-separated list of three strings. They are used for
substitution of asterisks in the <navbar:button>'s img attribute
when this attribute only contains one image filename and this filename
contains an asterisk. In other words: this single image filename is expanded
to a colon-separated list of three image filenames while for each filename the
asterisk is substituted with the corresponding string from the imgstar
attribute.
Defines a common image base directory, i.e. all non-absolute pathnames in
<navbar:button>'s img attributes are prefixed with PATH. Per
default there is no such prefix.
Defines a common navigation base directory, i.e. all non-absolute pathnames in
<navbar:button>'s url attributes are prefixed with PATH. Per
default there is no such prefix. Is is useful that PATH itself contains an
WML adjustable path variable.
This sets the button position where to apply this prolog, i.e. the number of
the button starting with the number 1. Use this to apply a special prolog to a
particular button only. The default is any for SPEC which means: apply
this prolog to any button as long as there is no specially defined one for it.
There are three important special values for SPEC: first (=1), last
(=number of used <navbar:button>'s) and next which
applies to the next button only.
This sets the type of application of this button. There are three possible
values for SPEC: ``N'' (normal: used for buttons in normal state),
``S'' (selected: used for selected buttons) and ``SS'' (sub-selected:
used for selected buttons but level is deeper).
This type is triggered by the select=ID and subselected attributes of
<navbar:render>.
This defines the epilog of <navbar:button>s, i.e. the local footer
for each navigation button. The available attributes or the same as for
<navbar:prolog>.
This defines a particular navigation button, i.e. a text or image surrounded
by a hyperlink plus a few special features like status bar hints and a
rollover effect for images.
The identification string for this button. This has to be a unique identifier
which later is used with <navbar:render>'s select attribute to
mark this button as selected.
The alt attribute for the created <img> tags. When images are
not displayed this is used instead by most browsers. If images are displayed
this is ignored by most browsers. It defaults to the value of the txt
attribute.
The image(s) to display for this button. This can be a single image file or a
colon-separated list of three images. The first one is the normal button, the
second one is the selected button variant and the third one is the variant
which is displayed when the mouse is over the button (but only if the button
is not a selected one).
The hyperlink URL which is activated when the button is pressed. There
are three special URLs: #UP#, #PREV# and #NEXT#, which refer
to the node one level up, the previous or the next node.
target=STR
A target frame or window where the hyperlink is redirected to.
The ``ATTR=STR'' pairs are passed along to the desired HTML tags.
It is also possible to add a prefix to tag name to select only normal
(.N), selected (.S) or subselected (.SS) buttons.
Marks the selected button as a subselected one, i.e. the current page for
which the button is selected is deeper than the original page for which
this button stands.
This is a hack because of the HTML rendering of typical browsers on anchors.
You have to use this attribute when you want to create textual
navigations bars with specific colors, this can not be performed with
prologs and epilogs when defining navbars.
Do not create Javascript hints for navigation buttons.
:a:ATTR=STR :img:ATTR=STR
The ``ATTR=STR'' pairs are passed along to all the desired HTML
tags found in this navbar. It is also possible to add a prefix to tag
name to select only normal (.N), selected (.S) or subselected
(.SS) buttons. For instance with
attribute ``class=``nav'''' is added to all images, ``class=``nav-s'''' is
added to anchor when button is selected (this is a dummy example, since
when button is selected, there is no such anchor), ``class=``nav-ss'''' is
added when button is subselected, and normal links have ``class=``nav-n''''.
This defines the body of a Perl filtering function which can be used to
post-process the generated HTML markup code before it is written out.
Currently there are no attributes used.
When no <navbar:filter> tag is specified, no such
filtering occurs. When
<navbar:filter> BODY </navbar:filter>
is specified, internally an anonymous Perl function is created
and the HTML markup code is filtered through this function
as follows:
$func = sub { BODY };
$markup_code = &{$func}($markup_code, $CFG, $select);
where $CFG is the internal configuration structure as seen with
<navbar:debug> and $markup_code is a literal string holding the
HTML markup code. In other words, when you want to apply a filter, you have to
do it with the following skeleton:
This prints Javascript functions used for rollover effects on images.
This macro discards itself after first invocation so that definitions
are printed only once. It is automatically called by
<navbar:render>, so it could looks useless. But if you
consider
