Provided by: wml_2.32.0~ds1-1_all bug

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)