NAME
wml::des::navbar - Navigation Bar
SYNOPSIS
#use wml::des::navbar
# explicitly write javascript code now
<navbar:jsfuncs>
# define a navigation bar
<navbar:define name=<name> [<options>]>
<navbar:header>...</navbar:header>
<navbar:footer>...</navbar:footer>
<navbar:prolog [<options>]>...</navbar:prolog>
<navbar:epilog [<options>]>...</navbar:epilog>
<navbar:button id=<id1> txt=... [<options>]>
:
<navbar:button id=<idN> txt=... [<options>]>
<navbar:filter>...</navbar:filter>
</navbar:define>
# debug the internal structure
<navbar:debug name=<name>>
# render the navigation bar
<navbar:render name=<name> [options]>
DESCRIPTION
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:
navbar ::= HEADER{0,1}
PROLOG{0,3} BUTTON{1,N} EPILOG{0,3}
FOOTER{0,1}
FILTER{0,1}
HEADER ::= navbar:header
PROLOG ::= navbar:prolog (type=N)
| navbar:prolog (type=S)
| navbar:prolog (type=SS)
BUTTON ::= navbar:button
EPILOG ::= navbar:epilog (type=N)
| navbar:epilog (type=S)
| navbar:epilog (type=SS)
FOOTER ::= navbar:footer
FILTER ::= navbar:filter
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!
For complete examples see under "EXAMPLES" below.
OPTIONS
Options of "<navbar:define>":
This defines the navigation bar.
name=STR
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.
imgstar=SPEC
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.
Example:
<navbar:define imgstar=std:sel:ovr ...>
...
<navbar:button img=button-1-*.gif ...>
<navbar:button img=button-2-*.gif ...>
...
</navbar:define>
This is equivalent to the following:
<navbar:define ...>
...
<navbar:button img=button-1-std.gif:button-1-sel.gif:button-1-ovr.gif ...>
<navbar:button img=button-2-std.gif:button-2-sel.gif:button-2-ovr.gif ...>
...
</navbar:define>
imgbase=PATH
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.
urlbase=PATH
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.
target=STR
The target frame or window to which all hyperlinks are per default
redirected to. This can be overwritten by the "target" attribute of
"<navbar:button>".
Options of "<navbar:header>":
This defines the global header for the navigation bar. Currently there
are no attributes used.
Options of "<navbar:footer>":
This defines the global footer for the navigation bar. Currently there
are no attributes used.
Options of "<navbar:prolog>":
This defines the prolog of "<navbar:button>"s, i.e. the local header
for each navigation button.
pos=SPEC
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.
type=SPEC
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>".
Options of "<navbar:epilog>":
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>".
Options of "<navbar:button>":
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.
id=STR
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.
alias=STR
The former "id" attribute has to be unique. This tag allows you to
group buttons as if they had the same "id" attribute.
txt=STR
The textual representation of the button which is displayed. When
no "alt" attribute is specified, it defaults to the value of this
"txt" attribute.
alt=STR
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.
img=SPEC
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).
hint=STR
The text displayed in the browsers status bar when the mouse is
over the button.
url=PATH
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.
menu=STR
The name of a navigation bar to insert at this point.
:a:ATTR=STR :img:ATTR=STR
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.
Options of "<navbar:debug>":
Use this tag while developing your navigation bar definition. It dumps
the internal structure of this definition.
name=STR
The name of the navigation bar to dump. See the corresponding
"name" attribute of "<navbar:define>".
Options of "<navbar:render>":
name=STR
The name of the navigation bar definition to use when rendering.
select=ID
Select a particular button as selected.
subselected
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.
txtcol_select=#rrggbb
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.
txtcol_normal=#rrggbb
This is the corresponding tag to "txtcol_select" because we want to
have a homogen configuration style.
menumode=inner|outer
With menumode=inner (default), a selected sub-menu is inserted
before epilog of current entry, otherwise it is put after.
txtonly
Forces the rendering to ignore all defined images.
nohints
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
<navbar:render name=main :img:class=nav
:a.N:class=nav-n :a.S:class=nav-s :a.SS:class=nav-ss />
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"’’.
Options of "<navbar:filter>":
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:
<navbar:filter>
my ($mcode, $CFG, $select) = @_;
...
return $mcode;
</navbar:filter>
Options of "<navbar:jsfuncs>":
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
<en><navbar:render name=main></en>
<fr><navbar:render name=main></fr>
javascript code only appears in English version. The correct solution
is to put this tag outside of any slice:
<navbar:jsfuncs>
<en><navbar:render name=main></en>
<fr><navbar:render name=main></fr>
EXAMPLES
Classic Navigation bar
File: nb.inc
<navbar:define name=test
imgbase="img/" urlbase="$(ROOT)"
txtcol_normal="#000000" txtcol_select="#ffffff">
<navbar:header>
<table cellspacing=1 cellpadding=2 border=0>
<tr>
</navbar:header>
<navbar:prolog> <td bgcolor="#cccccc"> </navbar:prolog>
<navbar:prolog type=S> <td bgcolor="#cc3333"> </navbar:prolog>
<navbar:button id=foo txt="Foo" url="foo.html" hint="The Foo Page">
<navbar:button id=bar txt="Bar" url="bar.html" hint="The Bar Page">
<navbar:button id=baz txt="Baz" url="baz.html" hint="The Baz Page">
<navbar:epilog> </td> </navbar:epilog>
<navbar:footer>
</tr>
</table>
</navbar:footer>
</navbar:define>
<navbar:render name=$(name) select=$(select)>
File: .wmlrc
-DROOT~.
-I.
File: foo.wml
#use wml::std::page
#use wml::des::navbar
<page indent=2>
#include "nb.inc" name=test select=foo
<h1>The Foo Page</h1>
<p>
Foo...
File: bar.wml
#use wml::std::page
#use wml::des::navbar
<page indent=2>
#include "nb.inc" name=test select=bar
<h1>The Bar Page</h1>
<p>
Bar...
Nested Navigation bar
File: nb.inc
<navbar:define
name=test imgbase="img/"
txtcol_normal="#000000" txtcol_select="#ffffff">
<navbar:header>
<ul>
</navbar:header>
<navbar:prolog><li></navbar:prolog>
<navbar:button id=foo txt="Foo" url="foo.html">
<navbar:button id=bar txt="Bar" url="bar.html" menu="nb-bar">
<navbar:footer>
</ul>
</navbar:footer>
</navbar:define>
<navbar:define name="nb-bar">
<navbar:header>
<ul>
</navbar:header>
<navbar:prolog><li></navbar:prolog>
<navbar:button txt="First bar item">
<navbar:button txt="Second bar item">
<navbar:footer>
</ul>
</navbar:footer>
</navbar:define>
<navbar:render name=test select=$(select)>
File: foo.wml
#use wml::std::page
#use wml::des::navbar
<page indent=2>
#include 'nb.inc' select=foo
<h1>The Foo Page</h1>
<p>
Foo...
File: bar.wml
#use wml::std::page
#use wml::des::navbar
<page indent=2>
#include 'nb.inc' select=bar
<h1>The Bar Page</h1>
<p>
Bar...
AUTHORS
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
Denis Barbier
barbier@engelschall.com
REQUIRES
Internal: P1, P2, P3
External: --
SEE ALSO
wml(1)