smfoote / kkjjhlhlba

Easy keyboard shortcuts on any website.

##kkjjhlhlba

kkjjhlhlba is a dependency-free tool that makes building keyboard shortcuts as easy as the Konami code. You define what shortcuts you want and kkjjhlhlba will make them work (and add a shortcut cheatsheet for you as a free added bonus!).

###Getting started

1. Add kkjjhlhlba.js to your page.
2. kkjjhlhlba.js creates a global object kkjjhlhlba.
3. Add your own JavaScript file to define your shortcuts.
4. Use the kkjjhlhlba API to define your shortcuts.

The example below shows how to implement two simple keyboard shortcuts:

kkjjhlhlba.start({
  shortcuts: {
    '/': {
      description: 'Search',
      method: function() {
      	document.getElementById('search-box').focus();
      }
    }
    'g,h': {
      description: 'Go to the homepage',
      method: 'https://www.example.com'
    }
  }
});

###API ####kkjjhlhlba.start(options) kkjjhlhlba.start registers the keyboard shortcuts defined in the options object. The kkjjhlhlba.start method may be called several times on a single page. If multiple shortcuts with the same signature are defined in the different calls to kkjjhlhlba.start, the shortcut defined in the last call wins. This can be useful when creating global shortcuts and page-specific shortcuts.

kkjjhlhlba.start({
  noCheatsheet: true,
  shortcuts: {
    '/': {
      description: 'Search',
      method: function() {
      	document.getElementById('search-box').focus();
      }
    }
    'g,h': {
      description: 'Go to the homepage',
      method: 'https://www.example.com'
    },
    'Q': {
      description: 'Quit',
      method: function() {
      	exampleGame.quit();
      }
    },
    'ctrl+k': {
      method: function() {
        console.log('This is a hidden shortcut. It works, but it doesn't show up in the cheatsheet.');
      }
    }
  }
});

#####options

• shortcuts is a required object within the options object. The shortcuts object contains the shortcut objects (see below).
• noCheatsheet is an optional boolean that determines whether a cheatsheet will be created. If noCheatsheet is set to true in any call to kkjjhlhlba.start, no cheatsheet will be created.

#####shortcut A keyboard shortcut is defined by a shortcut object. The object key of the shortcut object defines the keypress sequence that will fire the shortcut code. The shortcut object contains a required method attribute, and an optional description attribute.

• method can be a function or a string. If a string is used, kkjjhlhlba assumes the string is a valid URL, and redirects the page to that URL. If a function is used, that function is called when the keyboard shortcut is fired.
• description is a string used when building the shortcut cheatsheet to describe what the shortcut does. If the description attribute is absent, the shortcut is not included in the cheatsheet.

Keys pressed in sequence are separated by commas (e.g. g,h means press g, then press h), keys pressed at the same time are separated by the plus symbol (e.g. ctrl+k means press ctrl and k at the same time), and keys are case sensitive (e.g. s is not the same as S, but shift+s is the same as S).

####kkjjhlhlba.getShortcuts() kkjjhlhlba.getShortcuts returns an object of all the shortcuts that have been registered using kkjjhlhlba.start.

###How it works kkjjhlhlba adds a keydown and keyup event listener on the body of the HTML page. It converts the pressed key's keycode into the key's value, and builds a string based on the keys that have been pressed. On each keyup, it checks if the string corresponds to a registered shortcut.

###What's with the name? Think Vim and 80's video games.

kkjjhlhlba's Issues

Cheatsheet styles

Cheatsheet styles should be more specific, so the cheatsheet looks consistent on all sites.

Allow for overlapping inputs in certain cases

A command that is g then h can fail if the person types g-h very fast where they overlap for a very short amount of time.

There should be a small grace period where overlapping keys are accepted as separate keys.

Add tests

If a shortcut doesn't have a description, don't add it to the cheatsheet

Feature request: automatically scrape Nav links, h2's etc.

would be nice to automatically bootstrap the hotkeys by scraping pages for navigation links or h2's

Create a release process

Prefer grunt

indexOf needs a polyfill for IE <= 8

Allow custom cheatsheet markup

This should probably be achieved through the use of a templating engine.

i18n support

The cheatsheet is English only. English can remain as the default, but translations should be made possible.

Shift key stuck

Occasionally when switching between tabs or windows using the keyboard, the shift key is pressed on a kkjjhlhlba page, and is not released until the OS focus is no longer on the page. The keyup event never fires on the page. In these cases, kkjjhlhlba thinks that the shift key is still pressed. When the user returns to the page, keyboard shortcuts appear to be ignored because the shift key is "pressed"

Should ignore keyboard when select is in focus

'?' can only be overwritten the second time kkjjhlhlba.start is called

If a consumer of kkjjhlhlba does not want the default shortcut for '?', this should be possible from the first time kkjjhlhlba.start is called.

Shortcuts should be avaliable on some inputs

We shouldn't be ignoring keystrokes when the focus is on checkboxes and radio buttons.