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>".
This defines the global header for the navigation bar. Currently there are no
attributes used.
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>".
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)