wml::des::navbar(3)

💖 wml::des::navbar(3) 💖

EN Tools — bestie, this is the manual page for wml::des::navbar(3), and it's literally all about the Navigation Bar include file. We're in part 1, so buckle up. 💅✨

---

🌸 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 💅

okay so real talk: 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 then 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: a 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. iykyk 💅

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 than 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.). slay. ✨

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. no cap. 🫶

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 underlying 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 ✨

okay bestie, this is the big one — every single knob, dial, and secret handshake for these navbar tags. We're going section by section and no detail is getting left behind. periodt. 💅

---

💖 Options of <navbar:define> 💖

This defines the navigation bar. Main character energy, fr fr. 👑

• name=STR — This sets the name of the navigation bar which is used both for internal data representation 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. Do not skip this one, bestie.
• 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. It's giving "shortcut magic". ✨

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. No prefix unless you say so.
• 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. It is useful that PATH itself contains an WML adjustable path variable. WML path variables go hard here.
• 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>. Override-able, iykyk.

💖 Options of <navbar:header> 💖

This defines the global header for the navigation bar. Currently there are no attributes used. Just vibes, no knobs.

💖 Options of <navbar:footer> 💖

This defines the global footer for the navigation bar. Currently there are no attributes used. Same energy as header, bestie.

💖 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. Positional slay.
• 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). N, S, SS — the holy trinity of button states.

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 are the same as for <navbar:prolog>. Copy-paste energy, but make it valid.

💖 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. Iconic behavior, honestly. 🦋

• 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. Unique or it's a problem.
• 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. Grouping hack, lowkey genius.
• 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. Text fallback, periodt.
• 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. Accessibility-ish vibes, we love to see it.
• 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). Normal, selected, hover — the trio. 💅
• hint=STR — The text displayed in the browsers status bar when the mouse is over the button. Status bar tea.
• 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. Special URLs ate.
• target=STR — A target frame or window where the hyperlink is redirected to. Window redirect, slay.
• menu=STR — The name of a navigation bar to insert at this point. Nested navbar moment.
• :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. Custom attributes go crazy.

💖 Options of <navbar:debug> 💖

Use this tag while developing your navigation bar definition. It dumps the internal structure of this definition. Debugging era.

• name=STR — The name of the navigation bar to dump. See the corresponding name attribute of <navbar:define>. Point it at the right name, bestie.

💖 Options of <navbar:render> 💖

• name=STR — The name of the navigation bar definition to use when rendering. Pick your navbar.
• select=ID — Select a particular button as selected. Highlight that button.
• 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. Deeper level, subselected vibe.
• 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. It's a hack, but it works.
• txtcol_normal=#rrggbb — This is the corresponding tag to txtcol_select because we want to have a homogen configuration style. Matching color config, periodt.
• menumode=inner|outer — With menumode=inner (default), a selected sub-menu is inserted before epilog of current entry, otherwise it is put after. Inner vs outer, choose your fighter.
• txtonly — Forces the rendering to ignore all defined images. Text only, no pics.
• nohints — Do not create Javascript hints for navigation buttons. No hints, keep it mysterious.
• :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". Class injection, but make it fashion.

💖 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>

Perl filter bestie, do your thing.

💖 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>

One-time print, no cap.

💖 EXAMPLES 💖

okay bestie, this is the part where the vibes become functional. no cap, these are the blueprints for making the navbar actually appear. she's giving copy-paste and slay. 💅

🎀 Classic Navigation bar

first up: the classic one. it's simple, it's clean, it's lowkey iconic. here's what goes in nb.inc:

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)>

then your .wmlrc is literally just this tiny thing:

File: .wmlrc

         -DROOT~.
         -I.

and the pages that use it? they're just vibing with #use and #include. like:

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

now for the nested one, aka the navbar that has a whole other navbar as a little treat. it's giving matryoshka doll energy. here's nb.inc:

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)>

and the pages are basically the same deal, just with single quotes on the #include this time:

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 👑

the icons who made this happen:

• Ralf S. Engelschall — rse@engelschall.com — www.engelschall.com
• Denis Barbier — barbier@engelschall.com

🧚 REQUIRES 🧚

• Internal: P1, P2, P3
• External: --

🌈 SEE ALSO 🌈

• wml(1)

---

that's the whole page, bestie. this lil manual page came from EN Tools and is dated 2020-11-29, and it's for wml::des::navbar(3). go forth and make navbars that ate. 💖✨