Getting Started with BDC DrillDown Menu

This page assumes that you know jQuery and CSS, which I think is a pretty reasonable requirement for using a jQuery user interface plugin.

DDMenu, as exhibited on the Examples page, is quite easy to use. A single line of code is all that's necessary to turn a list into a menu.

Both jQuery and jQuery Dimensions are required by DDMenu, so be sure that you add their script tags to your page prior to the script tag for DDMenu. (NOTE: If you are using version 1.2.6 or newer of jQuery, then Dimensions is included and you need not include it separately.) Also be sure that you link in a CSS file, whether it be the one that ships with DDMenu or one that you created yourself. (You can see all of the CSS options for creating your own file on the CSS Class Reference page.)

After that, there's only one function to call, and that call should be placed inside your jQuery ready callback for the page. For a default menu, it's as simple as this: 

$(function() {
    $('#nav > ul').ddMenu();
});

Of course, I'm not counting the ready call when I say that it takes one line of code, but clearly however you look at it, it's pretty simple.

Any options that you wish to specify for your menu should be passed to the ddMenu function. The available options are discussed on the Options Reference page.

The #nav > ul part is the root of the menu list, and it's what works for this page's navigation menu. You will, of course, need to replace it with some CSS3 expression that identifies your own list.

The HTML List

But what about that list? What form must it take to work with DDMenu?

In reality, the "list" need not be an HTML list. As long as the elements are structured according to a rather intuitive and logical set of rules. Almost all of the menus on this site are built from lists (simply because it's easier to cut and paste them into place), but the rightmost menu on the Overview page is built from <div>s instead.

Here are the rules that must be followed to create a DrillDown Menu (along with the way it would be used as a regular list):

  1. A single root element is the element upon which ddMenu() is called. For a list, this would be a <ul> or <ol> element.
  2. This root element's children are the items at the top level of the menu. For a list, these are <li> elements.
  3. Each of these items can have either one or two children. The first is the label and must be present. The second acts as the root of a sub-menu and acts exactly as the element in rule 1. (If your label consists of more than one tag, simply wrap all of them in a <div>; if it's a bare text node, just wrap it in <div> or <span>.)
  4. If there are two child elements from rule 3 and the first is a <a> tag with an href attribute, then the item will be a split branch. The link will be maintained, and a separate element will be created to serve as the trigger to drill down to the next menu. This is the only time that the options textHover and iconHover are used; if there is no split branch, the option labelHover serves instead (see the CSS Class Reference page).
  5. If the first child element from rule 3 is any other tag, then the entire item is built into a non-split branch. It will drill down to the next sub menu without having any other link added.
  6. If there is only one child from rule 3, the entire item becomes a leaf node. Presumably, this element would be a link or have an onclick action.

For an example of a properly formed list, see the one at the top of the Examples page, and view the source of the page if you need to see the particulars. For an example of a menu built without a list, see the second list of the Overview page. It's quite straight-forward.