# SmartMenus Keyboard Addon

This demo includes the SmartMenus jQuery Keyboard Addon which you can optionally include on your pages in addition to the SmartMenus jQuery plugin. It brings advanced keyboard navigation for all menu trees you may have on your pages.

By default even without this addon the SmartMenus plugin includes basic keyboard navigation support - i.e. a user can use the `Tab` key to cycle through all main and sub menu links. This addon takes keyboard navigation to a more advanced level by allowing the use of the keyboard arrow and `Esc` keys to browse the menu tree conveniently. Additionally a hotkey can be set too if needed - i.e. a keyboard shortcut that will send focus to any menu tree.

## Example

Press `Shift` + `F12` to send focus to the first link in the main menu above (or press `Tab` as many times as need to focus some of the menu items). Then you can use the `←`, `→`, `↑`, `↓` and `Esc` keys to move the focus to other menu items. The script will automatically show/hide the sub menus as needed. If you hit `Esc` while a main menu link is focused and all sub menus are hidden, by default the script will focus the next focusable page element in the source after the menu tree. If you would like to set a custom element on the page to escape to, you can use the `keyboardSetEscapeFocus` API method.

## Methods

This addon introduces the following API methods:

keyboardSetHotkey
  Sets a hotkey combination that will send focus to the menu tree.
  Arguments:
  keyCode
    Type: Integer
    The key code for the hotkey (a good char code reference).
  modifiers
    Type: String, Array
    The hotkey modifier key. None, one or multiple of `'ctrlKey'`, `'shiftKey'`, `'altKey'`, `'metaKey'`.
  Code sample:

      // set Shift + F12 hotkey
      $('#main-menu').smartmenus('keyboardSetHotkey', 123, 'shiftKey');

      // set Ctrl + Alt + Shift + F12 hotkey
      $('#main-menu').smartmenus('keyboardSetHotkey', 123, ['ctrlKey', 'altKey', 'shiftKey']);

  Note: It is recommended to always use a combination (i.e. modifier + key) rather than use just a single key to avoid preventing important default browser features from working. `'shiftKey'` is best supported and probably the safest modifier you could use. `'ctrlKey'` and `'altKey'` generally work well too, there were just some issues with older Opera versions. `'metaKey'` is the Mac `Cmd` key and it only works on Macs so, unless you know what you are doing, you probably shouldn't use it.
keyboardSetEscapeFocus
  Sets a custom element on the page that would be focused if the user hits the `Esc` key while a main menu link is focused and all sub menus are hidden. By default the script will focus the next focusable page element in the source after the menu tree. Generally this should do the trick in most cases so setting a custom element is not needed by most users.
  Arguments:
  $elm
    Type: jQuery
    The jQuery wrapped element that should be focused.
  Code sample:

      // escape to a custom page link
      $('#main-menu').smartmenus('keyboardSetEscapeFocus', $('#myLink'));

      // escape to a custom page input field
      $('#main-menu').smartmenus('keyboardSetEscapeFocus', $('input[type=email]').eq(0));

« Back to main demo