Software.ModestMenus
Last updated on Tue Dec 23, 2008 |

The following information is also available in the "documentation" and "examples" directories included in the complete ModestMenus downloadable archive.

Table of Contents

I. Download and Installation

II. Default Menu Use

III. Customizing Your Menus

IV. Troubleshooting and Support

I. Download and Installation

All of the files needed to use ModestMenus can be found in the zip and tar archives available at http://dave.caretcake.com/software/modest_menus_download.rhtml The complete package includes three source files, usage documentation, examples, and a license agreement.

The source files consist of two JavaScript files named modest_menus.js (the core program) and menu_defs.js (a suggested place to store your menu definitions), along with modest_menus.css (the required menu system style definitions). The only real "installation" required is that you must somehow include the contents of these three files in every page that is going to use the menus. Of course, there are as many ways to do this as there are ways of including JavaScript and CSS in any web page, but the default three file method may be the easiest way to manage the menus across an entire website. This is covered in more detail under Importing the Menu System Into Your Web Page.

Up to Table of Contents

II. Default Menu Use

ModestMenus was specifically written to be more free-form than many other menu systems. And, while there is a pretty big variety of ways you can implement your menus, there are also some default assumptions made about how you'll probably want to use them. This documentation takes you through basic installation and usage with those default assumptions in mind. However, the system is in no way limited to only what is described here.

Up to Table of Contents

A. Importing the Menu System Into Your Web Page

Because ModestMenus is nothing more than a collection of JavaScript and CSS, all you have to do to import the menus into any of your web pages is simply use any of the standard methods for adding JavaScript and CSS to an HTML document. Of course, there are many ways to do this. So, before we go any further, let's take a quick look at the three files that are included in the "sources" directory of a ModestMenus archive.

The modest_menus.js file is the core of the ModestMenus system. It contains all of the JavaScript that handles keeping track of and displaying the menus you create. Unless you plan to modify or extend the core installation, you shouldn't need to edit this file.

By default, the menu_defs.js file contains nothing more than the license agreement. That's because this file isn't technically required by the menu system at all. The assumption that ModestMenus makes, however, is that you're going to want to make your menus universally available to your whole website. So, the menu_defs.js file is the default location recommended for creating your menu objects and all of their contents.

Lastly, the modest_menus.css file contains the bare essential style definitions needed for ModestMenus to operate. Just like with the menu_defs.js file, the assumption is that you're going to want to make your menu styles universally uniform across an entire website. So, the style definitions have been moved to an external file.

In the case of all three files, you can ultimately include this content however you'd like in your HTML documents. However, the default three file method may be the easiest way to manage the menus across an entire website. And, for the purposes of this documentation, it's expected that you will include external references to modest_menus.css, modest_menus.js, and menu_defs.js in the head of every HTML document that uses the menus. Assuming that all three ModestMenus files are located in the same directory as the HTML document that is to use them, you would add the following three lines of code to the head of your HTML document:

<link rel="stylesheet" href="modest_menus.css" type="text/css" />
<script type="text/javascript" src="modest_menus.js"></script>
<script type="text/javascript" src="menu_defs.js"></script>

Simply by including the code above in your web page, you have a fully functioning instance of the menu system — you just don't have any actual menus to display yet.

Up to Table of Contents

B. Creating a Default Menu Object

The ModestMenus menu object is the starting place for all of your menu implementations. You create a new menu object with the "new" constructor. Let's start off with an example where we create a menu named "animals". To do that, you would scroll down past the license agreement in your menu_defs.js file and write the line:

menus.animals = new menu("animals", "primary");

Before we disect what this code is actually doing, let's take a second to talk about some ModestMenu concepts. In ModestMenus, a menu is a named collection of options (links and the text they are to display). The menu "name" has nothing to do with what your site visitors will see; instead, the name is the internal name that you will use to refer to your menu in your page code. The name is also how ModestMenus will keep track of what collection of links you're referring to. In a lot of other menuing systems, the menu name is what the end users see and click on or put their mouse over to make the options appear. In ModestMenus, we call that the menu trigger, and triggers (as explained in Attaching a Default Menu to a Trigger) actually exist outside of ModestMenus and can be virtually any HTML element that can accept an onMouseOver or onClick event. So, now that we know what a menu name in ModestMenu is and what it's used for, let's go back to our example above.

The first thing we see is that menus.animals = part. If you don't care about the underlying reason for why this looks like it does, then just remember that you've got to put the menus. in front of your menu name when you're first defining it. That's all you really need to know. If you care about the technical reason for this construct, please read on. One of the ways we gain some efficiency in ModestMenus is by storing all of the menu data in a simple array where each array index is a unique string — your menu name. (Which, of course, means that this line could also be re-written menus["animals"] = new menu("animals", "primary"); to stress the arrayishness.) No matter how it's written, the end result is that ModestMenus is left with the equivalent of a hash table, where the value of each element in the array is actually an instance of a ModestMenus menu object.

The second thing we see, new menu("animals", "primary");, completes our statment. Here, we're telling ModestMenus that we want to create a new menu named "animals" and that it should be a "primary" menu. The new constructor supports two types of menu — "primary" and "secondary". At this time, the menu type tells ModestMenus whether it should display the menu below the trigger (primary) or to the right of it (secondary). Future plans include having ability to create menus that appear above or to the left of the trigger. The second function of menu type has to do with secondary menus. A secondary menu is one that is spawned from a primary menu rather than a non-menu trigger. In other words, a secondary menu is a sub-menu of an option in a primary menu. That is covered in greated detail below.

With the code above, you would have a perfectly valid default, empty, primary menu object just waiting to be filled with menu options.

Up to Table of Contents

C. Populating a Default Menu Object

Menu objects can be populated with one of two things: menu options (typically links to web pages) or secondary menus (sub-menus spawned by an option in a primary menu). In ModestMenus, we call the option text that the end-user will see the "option title," and we call the result of clicking on an option title the "option target."

To populate a menu object with options (option titles and targets), we use the addOption method. In the example below, we first create a primary menu called "animals" in our menu_defs.js file, and then we populate it with three options.

menus.animals = new menu("animals", "primary"); menus.animals.addOption("The Dog Page", "dogs.html"); menus.animals.addOption("The Cat Page", "cats.html"); menus.animals.addOption("The Bird Page", "birds.html");

As you can see, we start by naming and creating our animals menu object. Next, we use the menu object's addOption property to create an option title that would display the words "The Dog Page" to the end user, which is a link to the "dogs.html" webpage. The same pattern is followed for the cats.html and birds.html examples. The order that you add options (from top to bottom) in the menu_defs.js page, is the order in which the options appear in the menu. And, that's all there is to it. If you stopped right there, you would have a menu with three options linking to three separate webpages.

While a list of links is great and will serve your purposes some of the time, being able to generate sub-menus off of one of your options is important too. In ModestMenus, sub-menus are referred to as "secondary" menus. They are created in almost exactly the same way as a primary menu, except that when you create a new instance of a secondary menu, you have to tell ModestMenus that the new menu is secondary rather than primary. Let's create a secondary menu for dogs that will hold options for standard breed divisions:

menus.dogTypes = new menu("dogTypes", "secondary"); menus.dogTypes.addOption("Working", "working_dogs.html"); menus.dogTypes.addOption("Toy", "toy_dogs.html");

As you can see, this is almost exactly how the primary "animals" menu was created. In this case, however, we've created a menu called "dogTypes" and we've indicated that it's type is secondary. The last step is to tell ModestMenus that when someone puts their mouse over "The Dog Page" option title in the animals menu, we want the "dogTypes" menu to appear just to the right of "The Dog Page" option, below is the complete code:

menus.animals = new menu("animals", "primary"); menus.animals.addOption("The Dog Page", "dogs.html", "dogTypes"); menus.animals.addOption("The Cat Page", "cats.html"); menus.animals.addOption("The Bird Page", "birds.html");

menus.dogTypes = new menu("dogTypes", "secondary"); menus.dogTypes.addOption("Working Group", "working_dogs.html"); menus.dogTypes.addOption("Toy Group", "toy_dogs.html");

The above code is just the "animals" menu code combined with the "dogTypes" menu code with one exception — after "The Dog Page" option target, we've added one more piece of information, the name of our "dogTypes" menu. Simply by adding the name of a secondary menu after an option target, we've told ModestMenus to display the secondary menu off of the primary menu's option.

Ultimately, there is no limit on how many secondary menus can be displayed starting from a single primary menu. Simply follow the same construction, but continue creating more secondary menu objects. Here is one final example showing you what would happen if you wanted to create a third menu of specific toy breeds to be displayed when someone puts their mouse over the "Toy Group" option title:

menus.animals = new menu("animals", "primary"); menus.animals.addOption("The Dog Page", "dogs.html", "dogTypes"); menus.animals.addOption("The Cat Page", "cats.html"); menus.animals.addOption("The Bird Page", "birds.html");

menus.dogTypes = new menu("dogTypes", "secondary"); menus.dogTypes.addOption("Working Group", "working_dogs.html"); menus.dogTypes.addOption("Toy Group", "toy_dogs.html", "toyGroup");

menus.toyGroup = new menu("toyGroup", "secondary"); menus.toyGroup.addOption("Miniature Poodle", "miniature_poodle.html"); menus.toyGroup.addOption("Yorkshire Terrier", "yorkshire_terrier.html"); menus.toyGroup.addOption("Shih Tzu", "shih_tzu.html");

Up to Table of Contents

D. Attaching a Default Menu to a Trigger

What does it mean to attach a menu to a trigger? In ModestMenus, menus are defined by a small set of JavaScript commands, and they exist as separate named objects defined (by default) in the menu_defs.js file. A trigger is the element that the menu users either put their mouse over or click on to cause a menu to appear. So, what types of "elements" are these? They are any standard HTML element that support the onMouseOver and/or onClick events. This includes, but is not limited to: <a>, <applet;>, <button>, <div>, <img>, <input>, <li>, <object>, and <p>. (For a complete listing, please consult the WC3.) ModestMenus then provides you with two functions to handle the displaying and hiding your menus: showMenu() and hideMenus().

showMenu(), as the name implies, is responsible for making a menu visible. It must be called with one argument — the name of an already defined menu object. So, assuming you had a completely defined menu called "animals," you could trigger it's display with the following code:

<a id="animals" class="menu_container" href="animals.html" onMouseOver="showMenu('animals')">Animals</a>

Here we see a completely standard HTML link to a page called "animals.html" somewhere on our site. But, by adding the onMouseOver="showMenu('animals')" part, we're telling ModestMenus that when someone puts their mouse over this link, the menu named "animals" should be displayed directly below the link. (NOTE: While the href= part really doesn't have to point to anything, it is courteous to provide people using non-JavaScript enabled browsers a way to see what everyone with JavaScript enabled would have seen. That is, in this example, "animals.html" would presumably be a list of all the same links as would have been found in the "animals" menu itself.) The other thing that we notice is the id="animals" class="menu_container". You must assign an id to your trigger that is the same as the menu you'd like it to display via showMenu(). You must also assign the menu_container class to it. It's important to note that it is the trigger that must be given the id and class. That is, you can wrap your link or other element in a <span> or <div> tag if you'd like, and then assign the id and class to that element. For example:

<div id="animals" class="menu_container">
<a href="animals.html" onMouseOver="showMenu('animals')">Animals</a>
</div>

This method would allow you to have greater control of the styling of your trigger itself.

Displaying a menu is only half of the solution. If your website visitors decide that they really don't want any of the options displayed in the menu and they move their mouse to a different part of the screen, then the menu should disappear all on its own. That's where hideMenus() comes in. hideMenus(), which accepts no arguments when it's called, tells ModestMenus to hide any currently displayed menus. In general, it should be considered the compliment to any showMenu() call. The revised code below demonstrates its usage:

<a id="animals" class="menu_container" href="animals.html" onMouseOver="showMenu('animals')" onMouseOut="hideMenus()">Animals</a>

These two simple functions make up all that there is to do to display and hide menus in ModestMenus. However, their apparent simplicity is also their strength. Because menus exist as named objects on their own, and because a trigger can be anything that calls the showMenu() and hideMenus() functions, the combination of ways that you can implement displaying your menus is almost limitless. On a very long webpage, you could have a trigger for a menu at the top of the screen with a second at the bottom of the screen. Both menus would be controlled by the same menu object, so updating multiple trigger points is a snap. Plus, you have complete control over what and where your triggers are. The triggers themselves can be made up of multiple types of HTML elements (images, anchor tags, etc.) located independently of each other anywhere on the screen. The controls have been moved out of the menu system and into the designer/developer's hands.

Up to Table of Contents

III. Customizing Your Menus

By default, ModestMenus provides you with a simple way to create and display menus on your web pages. And, while the overall system works based on certain assumptions about how the menus will be used, there are ways available to override the default look and behaivor of ModestMenus menus.

Up to Table of Contents

A. Customizing Through CSS

While a thorough explanation of CSS is well beyond the scope of this documentation, it is important to understand the default CSS classes that come with ModestMenus. You can also refer to the examples that come with ModestMenus to see some suggestions in use.

.menuContainer
The menuContainer class defines the element (internally an HTML div tag) that holds a collection of menu options under a single menu name. It is the outermost level of a menu, and it can be stylized with any CSS attributes applicable to a standard div element. It is important to note, however, that there are three attributes that should not be altered from their default state: position, z-index, and visibility. These three attributes come specifically pre-defined to make ModestMenus work. If they are changed, your menus may no longer work correctly.

.menuOptionContainer
The menuOptionContainer class defines the area immediately surrounding an individual option. This area is an HTML div element and can, therefore, be stylized in anyway that a standard div element can. (If you're used to thinking about HTML documents as a collection of HTML elements, then it may be helpful to think of a menu as a collection of menuOptionContainer div elements grouped together in a single menuContainer div element.

.menuOption
The menuOption class (and its subsequent pseudo-classes) define the anchor elements that are used to create menu option titles and targets. As such, they can be stylized with any CSS attributes applicable to standard anchor tags.

Up to Table of Contents

B. Customizing Through the "properties" Methods

While the CSS definitions in the modest_menus.css file should be where all (or almost all) of your menu stylizing is done, there may be some cases where you'd like to do some fine-tuning on an individual basis. That's where the properties method comes in. Currently, the properties method allows you to override three styles on a per menu basis: width, padding-left, and padding-top. Future versions of ModestMenus will provide more options.

Up to Table of Contents

1. Overriding Menu Width

You can use the properties to override the width setting applied to all menus as defined in modest_menus.css. The syntax is as follows:

menus.animals = new menu("animals", "primary");
menus.animals.properties(width(500));

In the example above, we first create a new instance of a menu named "animals." Then, we call its properties method and reset the width of just this menu to 500 pixels. Width is always defined by the properties method in terms of pixels.

Up to Table of Contents

2. Adding Left-hand Padding

In the current version of ModestMenus, primary and secondary menu horizontal positions are defined solely in terms of a left position. By default, a secondary menu appears to the right of its parent, at the right-hand edge of the parent. This can be adjusted on a site wide basis through the modest_menus.css file, but it can also be defined on a per-menu basis through the properties method.

menus.animals = new menu("animals", "primary");
menus.animals.properties(paddingLeft(10));

In the example above, we first create a new instance of a menu named "animals." Then, we call its properties method and tell ModestMenus to display this menu 10 pixels to the right of where it would be displayed either by default or as defined in modest_menus.css. Do not be confused by the paddingLeft name. This tells ModestMenus to add the requested number of pixels to the left-hand side of your menu as padding — by adding padding to the left-hand side of your menu, you actually move it to the right on the screen.

Up to Table of Contents

3. Adding Top Padding

In the current version of ModestMenus, primary and secondary menu vertical positions are defined solely in terms of a top position. By default, the top of a secondary menu is vertically alligned to the top of its trigger. This can be adjusted on a site wide basis through the modest_menus.css file, but it can also be defined on a per-menu basis through the properties method.

menus.animals = new menu("animals", "primary");
menus.animals.properties(paddingTop(10));

In the example above, we first create a new instance of a menu named "animals." Then, we call its properties method and tell ModestMenus to display this menu 10 pixels lower than where it would be displayed either by default or as defined in modest_menus.css. Similar to paddingLeft, paddingTop tells ModestMenus to add the requested number of pixels to the top of your menu as padding — by adding padding to the top of your menu, you actually move it lower on the screen.

Up to Table of Contents

C. Advanced Customization of Menu Options

The final (and most complicated) type of customization you can do outside of the modest_menus.css file has to do with the menu options themselves. This type of customization requires a little bit of background information about ModestMenu's inner-workings and, in some cases, may only be suitable for people with at least moderate knowledge of JavaScript.

To take advantage of these advanced techniques, we should first take a quick look at what really happens when you use a menu's addOption method. First, let's see an example where we create a new menu object and then add one option to it:

menus.animals = new menu("animals", "primary"); menus.animals.addOption("The Dog Page", "dogs.html");

So, as we already know, the first argument passed to addOption tells ModestMenus what to display to the web site visitors as the option title. In reality, ModestMenus just wraps an anchor tag around whatever is passed to it as the first argument. That is, ModestMenus generates HTML based on the first and second argument in the format:

<a href="[SECOND ARGUMENT]">[FIRST ARGUMENT]</a>

This can be useful in many ways. What follows are only a few of the many possibilities.

Based on this understanding, one thing you can do is add valid HTML into your first argument. Using the example above, let's say you wanted your option title broken up over two lines. You could achieve this with the following code:

menus.animals = new menu("animals", "primary"); menus.animals.addOption("The Dog<br />Page", "dogs.html");

Notice that all we did was to add <br /> directly into our first argument. More advanced effects could be achieved by adding tags like <i>, <b>, or even <span>. You could even further define your style by adding a style attribute as in:

menus.animals = new menu("animals", "primary"); menus.animals.addOption("<span style='font-weight: bold;'>The Dog Page</span>", "dogs.html");

As you can see, adding standard HTML into your first argument can go a long way in achieving many specialized affects. Just be sure to enclose any values in single quotes (like above) or to escape double-quotes, by preceding them with a backslash, as in \".

In the same way that you can extend the text that is encompassed by the anchor tag, you can also extend what happens inside the anchor tag itself.

For example, let's say you wanted to display a menu option, but you weren't ready for people to be able to click on it yet. You could achieve this by the following code:

menus.animals = new menu("animals", "primary"); menus.animals.addOption("The Dog Page", "javascript:;");

This will result in a tag that looks like:

<a href="javascript:;">The Dog Page</a>

In other words, an option that is displayed but goes nowhere.

You could even trick ModestMenus into executing extra JavaScript with something like this:

menus.animals = new menu("animals", "primary"); menus.animals.addOption("The Dog Page", "dogs.html\" onClick=\"foo()");

Although this may look strange, the resulting HTML would look like this:

<a href="dogs.html" onClick="foo()">The Dog Page</a>

In other words, clicking on this option would also call a function named foo.

In short, ModestMenus was designed to provide a simple and easy way to implement something that is pretty good at providing a basic menu system for most occassions. However, it's also built on design principles that make it flexible and extendable so that some bells and whistles can actually be added to your menus without tremendous difficulty and through a knowledge of standard HTML, JavaScript, and CSS.

Up to Table of Contents

IV. Troubleshooting and Support

Some support for ModestMenus can be attained by emailing me directly at dave@caretcake.com. I try to respond to all messages as quickly as possible, but I can't guarantee an immediate response. If the site that you're having a problem with is publicly available online, please include the URL of the site along with a detailed description of the problem you're encountering.

Because ModestMenus is predominantly managed through CSS with only a little bit of JavaScript necessary to define your menus and menu options, most problems tend to be related to either malformed CSS definitions or syntax errors in the JavaScript defining the menus. If you're using a Mozilla-based web browser, you can enter javascript: in the location bar at the top of your browser and press the enter key to see any error messages your browser encountered when trying to render your page. In many cases, these messages will point directly to the problem you're having.

Up to Table of Contents