WebBrancher Documentation

This section contains detailed information for getting WebBrancher working on your site. Also, please make sure you have read the readme.txt file - it contains important information about the use of WebBrancher.

Placement of the Script

Once you have un-archived the webbr10.zip file, locate the web-brancher.html file and load it into Netscape. Once this is done, you should see a very basic menu on the left of your browser, and a blank frame on the right.

The file that you have just loaded contains the core WebBrancher JavaScript code, and some simple menu definitions to start it off.

Try viewing the page source from the browser menus (in Communicator, select the View menu, then the Page Source option). You should see a rather large HTML file, full of JavaScript code. Right down the bottom are the frame definitions.

For WebBrancher to work correctly, the script itself must reside in your index/frame definitions file. In other words, this is the default file that will be loaded when someone types in your URL.

For example, if your URL is:

..you must place the script in your index.html file (your welcome file): ..and this index file must create some frames (remember that WebBrancher will not work without frames).



Frame Definitions

When you create your frames, you can have as many as you like for many purposes, but TWO frames must be defined for WebBrancher to work. These are MenuFrame and PageFrame.

Look at the source code of WebBrancher. Take notice in particular to the frame definitions at the bottom - they'll look something like this:

<FRAMESET COLS='180,*' BORDER=0 onLoad='startMenu()'>
        <FRAME NAME='MenuFrame' SRC='webbr-blank.html'>
        <FRAME NAME='PageFrame' SRC='test.html'>
</FRAMESET>
Remember, on your site, you can define the frames how you wish, but some constants must remain: If you stick to these simple rules, you should have no worries generating your own WebBrancher menu!



Setting Menu Variables

Ok, once the frames are defined, we can start concentrating on the script itself. Look at the source code again, only this time look right up at the top. You'll see that startMenu() function we were talking about just before. This is the function called when your frames have loaded, and the browser is ready to generate the menu.

Just under the line that reads:

..you should see five or so lines that set some variables:
imageDirectory = 'webbr/webbr-img';
backgroundDirectory = 'webbr/webbr-bkg';
backgroundImage = 'bkg-002.jpg';
backgroundColor = '#FFFFFF';
linkColor = '#000000';
It is these variables which we should now consider.

imageDirectory

This variable must point to the directory where the WebBrancher menu images are located. This is where you should keep all of the little GIF files that came with WebBrancher as well as all of your own custom icon GIFs.

backgroundDirectory

This variable points to the directory where you keep your background images. These are images loaded as a background of the menu itself. For example, the default WebBrancher has a pale-blue 'criss-cross' pattern JPEG for a background.

backgroundImage

This variable sets the name and extension of the image in the backgroundDirectory that you want to use as the menu background. If you want to use a new background image, copy it to the background directory, and set this variable to it's name.

backgroundColor

If the web site user has images turned off, set this variable to the desired color (either hexadecimal or Netscape color keyword) of the menu background. Alternatively, if you do not want to use an image as a background, set the backgroundImage variable to '', and use this color instead.

linkColor

This variable sets the color of the links in your menu. Sometimes it is nice to have a change from the boring standard deep blue!!

After setting these variables, you should probably ignore the rest of the code, except of course for the most important section, the menu definitions!



Creating your Menu Definition

Now we come to the most critical function in WebBrancher, the defineMenuItems() function. Have a look at the source code again, and scroll right to the bottom once more. You should see the function, and a whole lot of 'treeVariable' stuff - don't be overwhelmed by it, it's really quite easy, as you'll soon see.

The tree variable (treeVariable)

All of your menu items are defined and stored in what is basically an array (or collection) called treeVariable. Look at the code again. You may notice that the defineMenuItems() function takes the treeVariable, and continually reassigns the treeVariable to equal itself with more and more items added. This is how you pass your menu information into the WebBrancher program.

It doesn't matter what order you add items to the tree variable, because WebBrancher can work out the structure of your menu automatically, although it does help to have some basic order to help you when you want to add more items in later!

Without further ado, let's check out how to add items or nodes into your menu tree.



Menu items

You'll notice that every line of the defineMenuItems() function starts off the same way - this fact will remain. Every item in your menu definition will have a separate line, consisting of:

Where the dots (....) are is where you'll define the data for each menu item. Let's start by reviewing a bit of tree theory:

Menu Tree

A hierarchial tree consists of nodes. In WebBrancher, there are three types of nodes:

  1. the root node - the root node is the top-level parent of all nodes in the tree. Your menu can have only one root node, and WebBrancher will check to see if you have entered more than one in error. A root node does not have a parent node, since it is the highest in the hierarchy. It must have at least one child node.
  2. folder nodes - folder nodes function like the root node, and help to gather nodes into common groups. Folder nodes have a parent node (this can be the root node, or another folder node, but not a page node!), and folder nodes must have at least one child node.
  3. page nodes - page nodes are where most of your links will be. Page nodes do not have any children, and must have a parent node (which is a folder node or the root node).
Sounds complex? Well, it probably does at first - but once you get the hang of it, it's really pretty easy.



Menu Node Data (syntax)

Ok, now we are really getting to the basics of WebBrancher - the individual pieces of data required by WebBrancher for each menu node. There's not that much to it, really. Every menu node that you define has these same items of data, in this order:

Thus, a complete menu definition entry for one single node would have the format: If you are still a little confused, just examine the source code to see how it's done, and pretty soon it should become familiar to you.



Error Checking

As you may imagine, with data entry like the menu definitions, errors and mistakes are bound to show up eventually. Luckily, WebBrancher has a great deal of error-checking built-in, and can detect errors in your menu definitions such as:

This extra error-checking code, however, makes the script quite large. I recommend creating your definitions in a script with error-checking functions, and, when you and WebBrancher are certain that there are no errors present in your definitions, copy them (and also your variables from the top!) over to the web-brancher-nec.html script. The NEC stands for 'no error checking', and will not check your definitions for errors, thus saving script size and download times.

You should always use this script for your publicly-accessible page.

Be certain, however, that there are no errors present in the definitions, or the menu may not function at all or simply act strangely.



That's a wrap!

Hopefully, that should be all the information you need to get your customised WebBrancher menu underway. If you have any other questions, please don't hesitate to e-mail the author, Colin Tucker, at ctucke02@postoffice.csu.edu.au.

Thank you for reading - I hope that WebBrancher can revolutionise your site too!