Preferences
auto-hide
mono-section
tooltips
animation:

Creating the NavBar

This page discusses the scripts that create the NavBar in more detail than our “quick start install guide”.

First off, we will start from the HTML layout that your page should have. The very basic but strong requirement is that all pages using NavBar should declare a “strict doctype”, that is, they should start for instance with the following string:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

This informs the browser that it should render the page in the “standards compliant” mode. If you do not include the DOCTYPE, in new browsers (Mozilla, Firefox, Opera 7, Safari, Konqueror) the only downside will be that the fonts in the menu might look bigger than you'd expect. This can be easily fixed by writing direct font specification for NavBar elements in the CSS file. However, in old browsers (Internet Explorer 6) the NavBar layout will look completely broken and this can't be easily fixed. So for your own sake, please do include the DOCTYPE declaration. We do not support situations where the DOCTYPE is missing.

Contrary to popular beliefs, NavBar requires a DIV-based layout instead of a TABLE-based one. Your page content must be embedded in a DIV element whose ID you need to pass to the NavBar constructor, and our menu will take care of creating a navigation bar for that DIV, so to say.

In the HEAD section of your HTML, you should load the files as described in the previous section, and just right before ending the BODY tag (before </body>)--or, even better, upon the onload event for the BODY tag--you should call a script that configures the NavBar. Don't worry, we discuss all steps here.

The HTML document

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
  <head>

    <!-- We recommend you to encode your pages in UTF-8 -->
    <meta http-equiv="content-type" content="text/xml; charset=utf-8" />
    <title>Your page title</title>

    <!-- Declare the path to NavBar files -->
    <script type="text/javascript">
      _NavBar_url = "/navbar/";
    </script>

    <!-- Load the NavBar “stripped” JavaScript file -->
    <script type="text/javascript" src="/navbar/navbar.jss"></script>

    <!-- Load the NavBar CSS file -->
    <link rel="stylesheet" media="all" src="/navbar/navbar.css" />

  </head>
  <body>
    <div id="content">
      Your page content here.
    </div>
    <script type="text/javascript" src="/setupmenu.js"></script>
  </body>
</html>

So the above is the minimal skeleton for your HTML pages (except comments--you can exclude them). Note that right before closing the BODY tag we load the file “setupmenu.js”. That file will instantiate the NavBar object and create the NavBar sections, as discussed in the following lines.

“setupmenu.js”

Of course, you can name this file whatever you like. We called it “setupmenu.js” because that's also the name we are using in our documentation pages. If you want to see the file that defines the navigation bar that you see in this very documentation, it is in setupmenu.js from your NavBar archive.

Also, we should have in mind that this file will serve creation of NavBar for multiple pages. It is wise to write the code in a separate file because it will be cached.

Creating the NavBar

  // first thing, let's create the menu:
  var menu = new NavBar("content");

  // the following will “open” the menu (create the top control bar)
  menu.openMenu();

So far we have created the main menu bar and the top control buttons (containing expand all/collapse all buttons, etc.). The openMenu function accepts 2 optional arguments, both of boolean type (true or false). But we won't use them for now--they are described later. Further, let's define NavBar sections.

Creating sections

  // create menu sections
  var section1 = new NavSection(
      menu, // specify the parent NavBar where this section stands
      "Quick start", // the section title
      [ // and here's the array of menu items
        [ "License and index",  "index.html", "Index page", "icon.png" ],
        [ "Installation notes", "install.html", "How to install NavBar on your site", "icon.gif" ]
        // ...
      ]);

The above shows a simple invocation of the NavSection constructor. Though it seems long, it actually only receives 3 arguments. Here is the prototype of the constructor:

  var section = new NavSection(parent_bar, section_title, content);

parent_bar -- this is a reference to the NavBar object that will contain the section being defined. Thus, we pass “menu”.
section_title -- this is a string which will appear in the final bar as the section title.
content -- this can be an array of items or a string. If a string is passed here, it will be interpreted as the ID of a DIV element that will make the contents of that menu section. This provides an easy way for you to include plain HTML in NavBar sections.
- If this argument is an array of items, it should have the following format:
```
[ [ item 1 ], [ item 2 ], ..., [ item n ] ]
```
  So as you can see, it is actually an array of arrays. One “subarray” for each item. The array that defines a single item has this format:
```
[ "Label", "URL", "Title (tooltip)", "icon.gif", "target" ]
```
  Therefore, you can define several properties for a NavBar item. First and most obvious it's the label. Second it's the URL, which can be either an absolute URL (i.e. starting with “http://” or with “/”) or a relative URL. If it's a relative URL, it will be relative to the page containing the NavBar. Then you can pass the item's tooltip (pass ""--the empty string--if you want no tooltip), the item's icon which again, can be a relative or an absolute URL, and--optionally--a target frame to open this URL to. Here are some examples that you can find in our “setupmenu.js”:
  - The "License and index" item, opens in the same frame.
```
[ "License and index", "index.html", "Index page", "images/bullet.png" ]
```
  - The "A List Apart" external link, opens in a new window. Has no icon (note that null is passed in place of the icon).
```
[ "ALA", "http://www.alistapart.com", "A List Apart", null, "_blank" ]
```
  In order to include a separator between 2 NavBar items, pass a null values instead of an array in place of the separator item. Like this (and that's also a “complete” example about invoking the NavSection constructor):
```
new NavSection(menu, "Section title", [
    [ "License and index", "index.html", "Index page", "images/bullet.png" ],
    null, // here's the separator
    [ "ALA", "http://www.alistapart.com", "A List Apart", null, "_blank" ]
]);
```
- If an ID is passed, then the DIV element having that ID will be searched in the DOM tree, and if found, it will become the content of that NavBar section. If an element having that ID is not found then nothing happens (NavBar won't show an error). Here is an example:
```
new NavSection(menu, "HTML Inside", "html-section");
```
  And have the following in your HTML page:
```
<div id="html-section">This is <b>some</b> <i>HTML</i></div>
```
  The DIV may optionally define a “title” argument. If present it will replace the section title defined in setupmenu.js. This is useful if you want to have an HTML section in different pages and want it to have a different title for each page.

Closing and generating the menu

Closing the menu appends the second row of control buttons. You can achieve this by calling “menu.closeMenu()”. Then we call “menu.generate()” in order to make the NavBar effectively display in the page.

  menu.closeMenu();
  menu.generate();

If you don't call “menu.closeMenu()”, the generate() function will silently call it for you.

Including the “sticky” button

As well as openMenu(), the functions called above accept 2 optional, boolean arguments: “use_sticky” and “no_hide_arrow”. If you don't pass them, the defaults are false and false which mean that the control buttons row will not display the “auto-hide” (sticky) button and will display the left arrow that allows one to hide the menu. For instance, in order to include the sticky icon in the bottom control bar and not include the hide arrow, you need to:

menu.closeMenu(true, true);

For convenience, these parameters can be passed to generate() directly, and the call to “closeMenu()” can be missing.

How many sections?

You can define as many sections as you want. Just call new NavSection() for each one of them and pass as the first parameter a reference to the NavBar object, as you can see above.

What's the current section?

The menu implements a simple way of automatically determining the current section. Basically, if the label of some item starts with “!” (exclamation sign) then that item will be rendered as “active” (selected) and the menu will remember the section that defines that item as the “current” section. This has impact on operations like “sync”--closes all sections except the current one.

In order to define a menu easily and without hard-coding the active section--hard-coding isn't really possible since we want to create a setupmenu.js file able to handle many pages, not just one--we have created a very simple function that we include in our setupmenu.js:

function L(label) {
  if (_NavBar_pageID.toLowerCase() == label.toLowerCase())
    label = "!" + label;
  return label;
}

Note that this function references a variable called “_NavBar_pageID”. This variable must be externally defined (right in the page, not in setupmenu.js) and it's value should be the label of the item that activates the current page. Thus, after loading the “navbar.jss” file, you can:

<script type="text/javascript">
  _NavBar_pageID = "License and index";
</script>

so that the variable will be defined when the script is loaded. And now, using the L() function, we can define menu sections like this:

new NavSection
  (menu,
   "Quick start",
   [
     [ L("License and index"),  "index.html",     "Index page",                          "a.png" ],
     [ L("Installation notes"), "install.html",   "How to install NavBar on your site",  "a.png" ],
     [ L("Customization"),      "customize.html", "How to customize NavBar",             "a.png" ],
     [ L("Technical support"),  "support.html",   "Contact us for free tech support",    "a.png" ],
   ]
  );

So as you can see, we simply call the L() function in order to generate the label for the NavBar sections. If the item is defining the current page, then its label will start with a “!” sign, thanks to the L() function, and this way the item and its section will be active. This technique is used in our “setupmenu.js” for these documentation pages.

How about HTML sections?

The careful reader will notice that the above way doesn't work for sections containing plain HTML. That's because they have no items, so you can't instruct the menu by prepending an exclamation point to item's label, simply because there's no item. :-)

If the current section should be HTML-based, you need to set the current section “manually”, by remembering a reference to the NavSection object and passing it to the NavBar object:

var section = new NavSection(menu, ...);
menu.currentSection = section;

Different styles for different sections

So, let's say you have 3 sections and to make things easier for the end-user you want to assign different background colors to each section. This is easy to do by assigning a custom CSS class to each section and writing CSS declarations that define styles of those sections. Following there is an example for one section:

var section = new NavSection(menu, "Section title", ...);
section.setClass("my-custom-section");

The above shows how you set the "my-custom-section" class to a certain section. Now, you can customize it by including some code in your CSS area:

  .menubar .my-custom-section-title,
  .menubar .my-custom-section .body,
  .menubar .my-custom-section .body table {
    background-color: #fff;
  }

With the above code, the defined section and its title will always have a white background.

“Toggle tabs”

These are some images that are displayed in each section, on the right side, and with the proper layout they can remain visible even if the NavBar is hidden. We have a demo that shows toggle tabs.

It is easy to add these images, provided that you keep a reference to the section object:

  var section = new NavSection(...);
  section.addToggleTab("/path/to/image-1.gif", "/path/to/image-2.gif");

The first image will be displayed when the NavBar is visible, and the second will be displayed when the menu is hidden.