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:")

     

• 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

 

---

 

2 - Visual Design:

 

 

 

---

 

3 - Functional Specifications/Requirements:

 

Sample Object for menu structure creation:

 

{

    'Menu Item 1': {

        items: {

            'Sub Item 1': {},

            'Sub Item 2': {

                items: function(ready, ui) {

                    window.setTimeout(function() {

                        ready({

                            'Ajax Item 1': {},

                            'Ajax Item 2': {}

                        });

                    }, 1000);

                },

                cache: false

            }

        },

        icon: null,

        choose: function() {

             alert(1);

        }

    },

    'Menu Item 2': {},

    'Menu Item 3': {},

    'Menu Item 4': {}

}

 

Each menu item is a key value pair, where the key is the text shown as menu item and the value is another object with optional configuration values and sub structures. Please note that this syntax currently has one very important flaw: It's not possible to have two menu entries with the same name in the same subtree. We might want to change it to an array of objects therefore.

 

Each menu item can have the following options:

 

• items (Object/Function)

  A substructure of items as Object, or a anonymous Function that has two arguments: 'ready' and 'ui'. The 'ready' argument itself is a function that takes one argument, which is the actual structure to be added. The menu waits until this very function is called, allowing for asynchroneous loading of new structures.

• cache (Boolean, default: true)

  Defines if in the case of 'items' being a function, it should be recalled each time the item is hovered/clicked, or wether it should do it one time only.

• icon

  The icon to be used.

• choose

  A function that gets fired if the item is choosen (clicked). A bit like a nested event.

   

 

Options/Methods/Callbacks

• options:
  • type ('flyout', 'drilldown', 'toolbar' | default: 'flyout')

    Determines the style and behaviour of the menu.

  • mode ('static', 'context', 'dropdown' | default: 'static')

    The way the menu is opened. 'static' means that the menu is simply rendered into the selected element, 'context' opens the menu when you right click on the selected element, and dropdown opens the menu below on click.

  • items (Selector/Object | default: '> ul')

    Determines what the menu structure should look like. Either, generic nested markup from the inner of the selected element is taken and transformed, or instead, a structured javascript object (i.e. converted from JSON) can be specified.

  • appendTo (Selector | default: 'body')

    Only applies if mode has been set to context/dropdown. Defines where to append the newly opened menu.

  • exclusive (Boolean | default: true)

    If set to true, all other closable menus are closed once this one shows.

  • width (Selector/Object | default: '> ul')

    Determines what the menu structure should look like. Either, generic nested markup from the inner of the selected element is taken and transformed, or instead, a structured javascript object (i.e. converted from JSON) can be specified.

  • width (Integer | default: 180)

    The default width of the menu.

  • maxHeight (Integer | default: 200)

    If specified, the menu cannot surpass this height and scrollbars show up if the structure get's bigger.

  • hoverClass (String | default: 'ui-hover-state')

    tbd

  • hoverClassSecondary (String | default: 'ui-component-content')

    tbd

  • nextMenuClass (String | default: 'ui-arrow-right-default')

    tbd

  • flyoutDelay (Integer | default: 300)

    Only for type flyout. Defines how many milliseconds to wait when hovered until the sub structure opens.

• methods:
  • menu('close')

    Closes the menu. Only works for flyout menus.

  • menu('closeAll')

    Closes all flyout menus on the page.

  • menu('open')

    Opens the menu. Only works for flyout menus.

  • menu('toggle')

    Toggles the menu visibility. Only works for flyout menus.

  • menu('add', items, position, type)

    Adds one or more items to the current menu. Where item is a structure described in options.items, position is a selector matching on the current menu structure and type is either 'after', 'before' or 'append'.

  • menu('replace', items, position)

    Replaces one item with one or more items on the current menu. Where item is a structure described in options.items, position is a selector matching on the current menu structure.

  • menu('remove', position)

    Removes a menu substructure that matches the position.

• callbacks/events:
  • browse (event: click, mouseover)
  • open
  • close
  • choose
• 'ui' object:
  • item (object[jQuery])

    The item that was choosen (if applicable).

 

 

• Show / Hide behaviour
  • The menu is shown on click (left click for dropdown, right click for context, with the exception of the static mode)
  • It's being hidden when the user selects an option out of the menu, clicks anywhere on the page or opens another menu (if the user wants to have multiple menus open at the same time, a menu can have a option set to false called 'exclusive'. This means if the option is set to false, the other menus will not be closed if that menu is being opened)
• Collision detection
  • The menu opens to the other side if it doesn't have enough space at the set direction in its container (default is window) (uses Position).
  • If the menu changes direction, any directional arrows associated with the direction should change with it. For example, if a fly out has to go left, the padding should reverse so that the arrow can be on the left side of the menu item and pointing left.
  • It can be overidden by setting the option 'forceDirection' to true
• Default rendering
  • To make it possible to create a menu without having to specify any of the options, the default menu will render as statically rendered flat/flyout menu. The items are automatically determined by using the selector '> ul', it therefore takes the first direct list in finds in the original element.
• the script tests the content -- an unordered list to see if it contains nested lists, or a select to see if it contains opt-groups -- and renders the menu accordingly; can also accept options to configure menu type
• Events
  • select is triggered when a list item has been clicked
  • browse is triggered when a sub list was opened, or in the case if drilldown, if a sublist has been closed as well (since you're browsing the old list again then)
  • open - is triggered when the menu is opened (not applicable in case of mode 'static')
  • close - is triggered when the menu is closed (not applicable in case of mode 'static')

 

To be structured:

 

• ability to update content for sub-menus on the fly
• customizable open/close effects
• ARIA attributes
• keyboard navigation

 

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.

 

---

 

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>

 

     For application controls:

          <select>

               <optgroup label="Search engines">

                    <option>Google</option>

                    <option>Yahoo</option>

                    <option>MSN</option>

                    <option>Ask</option>

                    <option>AOL</option>

               </optgroup>

               <optgroup label="Computers">

                    <option>Apple</option>

                    <option>Dell</option>

                    <option>HP</option>

               </optgroup>

          </select>

 

     4.2 Recommended transformed HTML markup

 

     4.3 Accessibility recommendations

     Because the menu widget is really just a transformed unordered list or select, we'd recommend that it only be used as an enhancement to well-formed markup when the device supports JS and advanced CSS to ensure that the content remains accessible.

 

     4.4 CSS & Theme

     Themeroller classes should be set as defaults that can be overridden by passing in options.  These classes cover:

• the appearance of the menu and sub-menus (border, background-color)
• item hover states - the list item is given a border color and the link a background color/image on hover.  We split the styles this way so that the split-buttons in the ipod menu are bound/connected by the list item's border, and each link can have a separate hover state (one each for choosing a node and navigating).
• item "on" state for fly-out menu

 

 

---

 

5 - Latest version of plugin:

 

Paul has done a lot of work on this already and has a demo of the iPod and flyout menus working. This uses older styles but it's a solid start.

http://jquery-ui.googlecode.com/svn/branches/labs/menu/tests/visual/menu/menu.html

 

---

 

6 - Open issues being discussed

 

(Use this area to place things that we're hashing out like featuresand options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)

 

---