type: widget

release: 0.0

status: in development

documentation: TBD

tests: TBD

demo: http://jquery-ui.googlecode.com/svn/branches/dev/tests/visual/menu/default.html

 

menus in labs:

http://jquery-ui.googlecode.com/svn/branches/labs/fg-menu/index.html

http://jquery-ui.googlecode.com/svn/branches/labs/menu/demos/menu/default.html

 

 

---

 

1 - Description:

 

Attaches a menu to any element, either as dropdown, context or statically rendered menu, takes well-formed markup -- an unordered list or select form control -- or JSON and converts it into a menu which takes one of several forms (either determined automatically by the structure or via options [the option is called 'type']):

 

NOTE: numbers in brackets reference visual designs.

 

Flat, non-hierarchical list (default when there are no nested lists)

 

• simple menu [D1] appears/acts like a customized dropdown list.
• popup menu [D8] appears/acts like a native Mac OS select list, where the the selected option appears boxed to the left of the trigger button, and the user can click either the selected option or button to open the menu.  The menu is positioned so that the selected option always appears at the same place in the list; when the menu is open, if the selected option is third from the top, you'll see the first two options above the selection, and the rest below.

 

Hierarchical list:

 

• fly-out [D2 and D3], if the option is explicitly set or, as a best practice, if number of sub-levels limited to 2 or 3 (when 3+ submenus are showing,  collision detection can become unwieldy depending on the available space in the viewport).  Behaves similarly to Apple's OS menus where the main menu appears on click and sub-menus on hover; the current sub-menu remains open as long as the user's mouse is over it, otherwise it (and any other sub-menus) closes after a short delay.  The user's path through the menu is marked with an "on" state.

    

• ipod-style/drilldown [D6 and D7], if the number of sub-levels is larger or unknown or if the option has been explicitely set.  Mimics its namesake by showing a main menu, and as you choose options that navigate to deeper levels, the next menu slides to the left into view.  By default a "back" link appears at the bottom of the menu, and when clicked, the visible menu slides to the right out of view.  Options allow the user to:
  • show a full breadcrumb in place of the back link
  • change the location of the back link (above vs. below the menu)
  • change the default back text (from "Back" to something else)
  • set default breadcrumb text (i.e., "Choose an option:")
  • select wether the menu should be context loaded, drop down or statically rendered

     

• menubar [E2], if the option is explicitly set (not automatic detection): the top-level menu options are arranged either horizontally or vertically in a row, and sub-menus appear either below or beside them, respectively.  Sub-menus can be formatted as flat, ipod-style, or flyout.  This menu could be used as standard global navigation, or as part of a toolbar.  (The toolbar is a separate widget that groups navigation and form controls.)

 

 

Split buttons

Users should have the option to create split-buttons for any menu option, where the left button selects the node and the right button opens a sub-menu.  The original design only spec'd split buttons for ipod style menu, but this could be useful to show link affordance in fly-outs as well.

 

Check and radio options

• a check or radio option is always a leaf node, never has a child menu
• check options can be toggled on/off one at a time; multiple check options can be selected/on in a single menu
• radio options are like their namesake in that you can choose one from a group.  Example: EXT toolbar, "button with menu:" http://extjs.com/deploy/dev/examples/menu/menus.html
• radio options must be visually grouped together, either in a stand-alone menu or sub-menu, or set apart from other list items with a divider
• when one or more options has an check, radio, or custom icon, the entire menu -- parent menu plus all sub-menus -- is indented left so that the icons are easily scannable in a left "column"

 

Custom icons [D5]

Users could also specify unique icons that appear next to particular menu options.

 

Dividers

• dividers could be specified in the original (pre-menu widget) markup as:
  • an empty list item.  The menu widget could insert a horizontal rule for vertical menus, or a vertical rule for horizontal menus (menubars)
  • a list item containing text (not linked) could be converted to a horizontal rule followed by a text label
• dividers/labels are not clickable

 

Sub-menu indicator arrows and icon alignment [D4]

• for vertical menus:  Arrow icons which indicate sub-menus always appear in the right column.  It may be problematic to flip the location of the arrows to the left side of the menu; doing so would only work when there are no left column check/radio icons, otherwise it may be visually noisy.  Keeping the arrow icons on the right but flipping their direction to point left may also be confusing, as the arrow would be pointing back to the list item -- has anyone seen a menu behave this way?  Using the Mac OS default behavior as a guide, it may be a safer bet to never flip the location or direction of the arrows and have them always stay in the right column and point right, which is the default direction of the menu, and reserve the left column for icons.
• for horizontal menus (top-level menubar buttons):  An option could be set whether to show a "down" arrow to indicate sub-menus.

 

As decribed in the first paragraph, the behaviour/mode of the menu can be set to the following (the option for this is called 'mode'):

 

• dropdown,  makes the element the menu is bound to to act like a button, therefore drops down the menu to one side of the original element (default is below, configurable via option 'direction')
• context, appears on right-click in a specified region by default, or the user can optionally make it appear on left click or a key + click combination [any suggestions for this option?]. The direction option can be used to set how it pops up, the default is "right below".
• static (default), simply takes the list or JSON and renders the menu statically (always visible) into the original element. If you don't specify the items option, it will search for the first ul that is a child of the selected element and transforms it automatically (this is specific to the selected mode).

 

 

One thing to consider for the grid (and many other future UI plugins) is that HTML 5 provides detailed specs for these widgets that we should seriously consider using as a blueprint for our plugins. If we shared similiar naming and conventions, it will provide a cleaner interface in the future when we all have to support both the HTML 5 version (where available) and the JS-based UI plugin verison on the same site (i.e. use the native HTML 5 if availble, fall back to JS if not supported).  The other benefit is that these specs have been refined by a large group of people so they are fairly mature and there may be no need to reinvent the wheel. There is a menu spec here:

http://www.whatwg.org/specs/web-apps/current-work/multipage/interactive-elements.html#menus

 

Many, many jQuery menu plugins already exist that we may be able to mine for ideas, or use as the basis for the jQuery widget.  Several are listed below, but there may be others that look as/more promising (feel free to add to or edit this list):

 

Single or multi-level menus (dropdown, flyout, ipod-style)

• http://jdsharp.us/jQuery/plugins/jdMenu/
• http://onehackoranother.com/projects/jquery/droppy/
• http://www.filamentgroup.com/examples/menus/index.html
• http://www.brothercake.com/dropdown/
• http://www.opencube.com/

 

Context menu

• http://www.trendskitchens.co.nz/jquery/contextmenu/
• http://abeautifulsite.net/notebook/80

 

Enhance standard <select> into menu

http://www.givainc.com/labs/linkselect_jquery_plugin.htm

 

Filament flyout and iPod menus with ARIA and CSS framework support:

http://www.filamentgroup.com/lab/jquery_ipod_style_and_flyout_menus/

http://www.filamentgroup.com/examples/menus/index.html

 

Themeroller-based drilldown menu: http://www.matthewfeerick.com/jquery_menu/

 

For a very detailed description of menu design best practices and behavior, please review the Apple's UI guidelines for menus or Microsoft's Vista UI guide for menus.

---

 

2 - Visual Design:

 

 

 

---

 

3 - Functional Specifications/Requirements:

 

Options:

• TODO specify menu options

Methods:

• refresh
  • Renders all non-menu-items as menu-items, called once by _create
  • Call whenever adding or replacing items in the menu via DOM operations, eg. via menu.append("<li><a href='#'>new item</a></li>").menu("refresh")
• TODO specify other menu methods

Events:

• focus
  • Triggered when a menu item gets mouse (on hover) or keyboard (navigation with cursor keys) focus
  • ui.item refers to a jQuery object containing the focused menu item (a li-element)
• selected
  • Triggered when a menu item was selected
  • ui.item refers to a jQuery object containing the selected menu item (a li-element)
• TODO specify other menu events

 

 

---

 

4 - Markup & Style:

 

     4.1 Initial markup examples 

     For navigation menus, any unordered list:

          <ul>

              <li><a href="http://google.com">Google</a></li>

              <li><a href="http://yahoo.com">Yahoo</a></li>

              <li><a href="http://msn.com">MSN</a>

                    <ul>

                         <li><a href="htp://sub1.example.com">sub-level</a></li>

                        <li><a href="http://sub2.example.com">sub-level</a></li>

                    </ul>

               </li>

              <li><a href="http://ask.com">Ask</a></li>

              <li><a href="http://aol.com">AOL</a></li>

</ul>

 

 

     4.2 Recommended transformed HTML markup

 

     4.3 Accessibility recommendations

     TODO specify use of ARIA attributes like role="menu" and active-descendent=...

 

     4.4 CSS & Theme

     TODO

 

 

---

 

5 - Latest version of plugin:

Currently embedded in Autocomplete. Previous work, covering iPod-style and flyout menus can be found in labs: http://jquery-ui.googlecode.com/svn/branches/labs/menu/tests/visual/menu/menu.html

 

---

 

6 - Open issues being discussed

 

Move standard key handling to base menu plugin:

- up moves to the previous item, triggers focus event

- up on first item triggers underflow event, does nothing

- down moves to the next item, triggers focus event

- down on last item triggers overflow event, does nothing

- right triggers overflow event, does nothing

- left triggers underflow event, does nothing

 

Looping:

- up underflow focuses last item

- down overflow focuses first item

 

Nested menu:

- right on item with submenu opens submenu

- right on item with no subment triggers overflow

- left on submenu triggers focus on parent menu

- left on top menu triggers underflow

 

Autocomplete:

- up underflow focuses text field

- down overflow focuses text field

 

Menu bar:

- right overflow focuses next menu bar item

- left underflow focuses previous menu bar item

 

Prove extensibiility by building examples of:

- autocomplete

- nested menu

- combobox

- menu bar

 

---