Keymage is a small (1.6kb after Closure Compiler and gzip) library for handling key bindings in JavaScript. It supports nested application scopes, has a simple DSL for defining keys and can handle key chords.
- or check tests in browser
defmod
key which is command
on OS X and control
elsewhere)Include keymage.min.js
in your page:
<script src="https://github.com/piranha/keymage/raw/master/keymage.min.js"></script>
There are no dependencies. It is possible to use library as a simple JS module, as an AMD module or as CommonJS module.
It worth to note that Keymage is on cdnjs which enables you to use it without downloading.
Plus, of course, it's on NPM.
Keymage exposes a single function, keymage
:
// bind on 'a'
keymage('a', function() { alert("You pressed 'a'"); });
// returning false prevents default browser reaction (you can always use
// e.preventDefault(), of course)
keymage('ctrl-e', function() { return false; });
// binding on 'defmod' binds on Command key on OS X and on Control key in other
// systems
keymage('defmod-j', function() { alert("I am fired"); });
Handler function receives two arguments: the original event and the context so you can understand what and why was fired.
The context contains those properties:
shortcut
is a string you've originally provided for bindingscope
is a scope which is currently activedefinitionScope
is a scope where this shortcut was definedkeymage('alt-c', function(e, ctx) {
console.log(ctx.shortcut, ctx.scope, ctx.definitionScope);
});
// -> "alt-c", "", ""
Keymage supports key sequences:
keymage('ctrl-k j', function() { alert("Nice!"); });
For this to fire you have to first press both ctrl
and k
, and then
j
. This will fire an alert.
There is something to remember: browsers have their own shortcuts, for example
ctrl-j
in most browsers means "open downloads". And while you can always call
e.preventDefault()
in usual situation, if ctrl-j
is part of a sequence, it's
not that easy - you'll get control over what's happening only when the whole
sequence is pressed.
So keymage provides you with a means to support this use case. I do not
encourage you to override browser hotkeys, but let's imagine you want to do
that. For this, you can pass an option object as last parameter, having
preventDefault
property set to true
:
keymage('ctrl-t ctrl-j k',
function() { alert("wow"); },
{preventDefault: true});
This option will prevent default on every key press which is a valid part of a
bound sequence, including the one triggering your handler. Note that pressing
only ctrl-j
(without ctrl-t
) will still open downloads, keymage looks for
sequence of ctrl-t ctrl-j
.
Keymage support nested scopes. This means that your application can have few areas where you can gradually have more and more specific shortcuts. It works like this:
// You can skip scope argument if you want global work-always shortcut
keymage('ctrl-j q', function() { alert("Default scope"); });
// This will fire after "keymage.setScope('chat')"
keymage('chat', 'ctrl-j w', function() { alert("Chat scope"); });
// This will fire after "keymage.setScope('chat.input')"
keymage('chat.input', 'ctrl-j e', function() { alert("Chat.input scope"); });
You can control scopes with helpful pushScope
and popScope
methods. This way
your nested view (or whatever is enabling nested scope) doesn't need to know
about parent scope:
keymage.pushScope('chat') // scope is 'chat'
keymage.pushScope('input') // scope is 'chat.input'
keymage.popScope() // scope is 'chat'
keymage.pushScope('deep')
keymage.pushScope('deeper') // scope is 'chat.deep.deeper'
// way to jump out of deep scoping
keymage.popScope('chat') // scope is ''
pushScope
returns resulting scope and popScope
returns topmost scope it
removed (so with parameters it's the one you've asked to remove).
Note that calling popScope
with name of a scope which is repeated few times
will pop topmost one, i.e.:
keymage.setScope('this.scope.is.deep.scope')
keymage.popScope('scope') // scope is 'this'
Last and optional argument to keymage
function is an option object. Here is a
list of possible options:
preventDefault
: when true
, calls event.preventDefault()
on every key
press which looks like a part of defined sequence.
context
: binding handler will be called with provided object as a context.
And if you ever need to unbind a handler, use this:
keymage.unbind('ctrl-j k', your_handler_function);
Also, keymage(...)
returns a function, which unbinds this shortcut when called:
var unbinder = keymage('ctrl-j k', your_handler_function);
unbinder();