@mysigmail/menu-aim

What's this?

This is an ES6 re-implementation of jQuery-menu-aim by Ben Kamens - it has been written so that it can be used/imported as a regular ES6 module (see the example below).

Additional bonus is that, this one doesn't use jQuery ... in fact it has no dependencies.

Here's an example (a more detailed example can be found at the end of this document):

import { MenuAim } from 'es6-menu-aim';

let menu_root = document.getElementById('menuRoot');

let menu_aim_config = {
    clickRow:function (mouseEvent, targetRow) {
        console.log('menu item was clicked!');
    }
};

let menu_aim = new MenuAim(menuRoot, menu_aim_config);

Why would I want use this?

The use case for menu aim is best described in README of the original jQuery-menu-aim.

You might want to use this implementation instead of the original if you want the benefit ES6 import and also if you use TypeScript (typings are included in the build).

How to install?

Simply open up a terminal, go to your project directory and run:

npm i --save es6-menu-aim

Documentation

MenuAim

Main class of MenuAim

Kind: global class

• MenuAim
  • new MenuAim(menu, opts)
  • .attach()
  • .mouseleaveMenu(ev)
  • .forceExit()
  • .commitExit()
  • .mouseenterRow(ev)
  • .clickRow(ev)
  • .activate(row)
  • .possiblyActivate(row)
  • .activationDelay()
  • .hookUp()
  • .setActiveRow(row)
  • .deactivateRow()
  • .detach()

new MenuAim(menu, opts)

Constructor function

Param	Description
menu	root menu HTML element
opts	(optional) config options (see Options)

menuAim.attach()

This method is called initially and each time a menu is re-activated

Kind: instance method of MenuAim

menuAim.mouseleaveMenu(ev)

Cancel possible row activations when leaving the menu entirely

Kind: instance method of MenuAim

Param	Description
ev	Mouse Event

menuAim.forceExit()

Hides all the sub-menus and the menu. It can be called externally

Kind: instance method of MenuAim

menuAim.commitExit()

Closes the menu

Kind: instance method of MenuAim

menuAim.mouseenterRow(ev)

Trigger a possible row activation whenever entering a new row.

Kind: instance method of MenuAim

Param	Description
ev	Mouse event

menuAim.clickRow(ev)

Immediately activate a row if the user clicks on it.

Kind: instance method of MenuAim

Param	Description
ev	Mouse Event

menuAim.activate(row)

Activate a menu row.

Kind: instance method of MenuAim

Param	Description
row	menu row which should be activated

menuAim.possiblyActivate(row)

Possibly activate a menu row. If mouse movement indicates that we shouldn't activate yet because user may be trying to enter a submenu's content, then delay and check again later.

Kind: instance method of MenuAim

Param	Description
row	menu row to be activated

menuAim.activationDelay()

Return the amount of time that should be used as a delay before the currently hovered row is activated.

Returns 0 if the activation should happen immediately. Otherwise, returns the number of milliseconds that should be delayed before checking again to see if the row should be activated.

Kind: instance method of MenuAim

menuAim.hookUp()

Hook up menu item events. This method allows menu items to be added externaly

Kind: instance method of MenuAim

menuAim.setActiveRow(row)

Sets a DOM node as currently active menu item. This is to be used form external code in case menu item list can dynamically change

Kind: instance method of MenuAim

Param	Description
row	DOM node to be set active

menuAim.deactivateRow()

Deactivate menu item which is currently marked as active

Kind: instance method of MenuAim

menuAim.detach()

Detaches MenuAim from DOM containser ... to be used while disposing the menu

Kind: instance method of MenuAim

Options

MenuAim constructor as the second parameter excepts an object containing options.

The following snippet show these options (this is a modified version of original snippet found at jQuery-menu-aim):

import { MenuAim } from 'es6-menu-aim';

let menu_aim_options = {

    /** Function to call when a row is purposefully activated.
     *  Use this to show a submenu's content for the activated row.*/ 
    activate:function (targetRow) { ... },

    /** Function to call when a row is deactivated */
    deactivate:function (targetRow) { ... },

    /** Function to call when mouse enters a menu row.
     * Entering a row does not mean the row has been
     * activated, as the user may be mousing over to a submenu. */
    enter:function (targetRow) { ... },

    /** Function to call when mouse exits a menu row. */
    exit:function (targetRow) { ... },

    /** Function to call when mouse exits the entire menu. If this
     *  returns true, the current row's deactivation event and
     *  callback function will be fired. Otherwise, if this isn't
     *  supplied or it returns false, the currently activated row
     *  will stay activated when the mouse leaves the menu entirely. */
    exitMenu:function (menu_aim_instance) { ... },

    /** Function to call when a menu row is clicked */
    clickRow:function (mouseEvent, targetRow) { ... },

    /** Selector for identifying which elements in the menu are rows
     *  that can trigger the above events. Defaults to "> li". */
    rowSelector:"> li",

    /** You may have some menu rows that aren't submenus and therefore
     *  shouldn't ever need to "activate." If so, filter submenu rows
     *  w/ this selector. Defaults to "*" (all elements). */
    submenuSelector: "*",

    /** Direction the submenu opens relative to the main menu.
     *  This controls which direction is "forgiving" as the user
     *  moves their cursor from the main menu into the submenu.
     *  Can be one of "right", "left", "above", or "below".
     *  Defaults to "right". */
    submenuDirection:"right",

    /** for how long should menu remain displayed after the mouse has left it */
    exitDelay:null,

    /** bigger = more forgiving when entering submenu */
    tolerance:75,

    /** set it to TRUE if the menu is not nested within another menu */
    isRoot:false
};

let menuRoot = document.getElementById('menuRoot');

let menu_aim = new MenuAim(menuRoot, menu_aim_options);

License

MIT License, http://www.opensource.org/licenses/MIT