ember-key-manager

A service for (un)binding keyboard up and down events.

Installation

ember install ember-key-manager

Usage

Bind key event anywhere services are available e.g., routes, models, controllers, components.

Config

Set global options in a keyManagerConfig object in your application's config/environment.js:

  keyManagerConfig: {
    disableOnInput: true,
  },

`disableOnInput`

Defaults to false. Set the global option to true to change the default. This can still be overridden by passing in the flag on the register method.

Public Methods

`register({keys, name, selector=$(document), downCallback, upCallback, priority=0, disableOnInput})`

Accepts an object with the following attributes:

Name	Type	Required	Default	Description
`keys`	array of strings	Yes	`<none>`	An array of keys that comprise the shortcut e.g., `['meta', 'enter']`. If `keys` contains multiple modifier keys, they still comprise one shortcut e.g., `['meta', 'shift', 'enter']` is a single shortcut that executes when all three of those keys are pressed.
`name`	string	Yes	`<none>`	A unique string by which you can identify – and `deregister` – the shortcut.
`selector`	jQuery selector	No	`$(document)`	A jQuery selector by which to scope the shortcut.
`downCallback`	function	No	`<none>`	A function to be called when the shortcut keys are matched and the keydown event is fired.
`upCallback`	function	No	`<none>`	A function to be called when the shortcut keys are matched and the keyup event is fired.
`priority`	integer	No	`0`	An integer used to prioritize shortcuts should the shortcuts with the same `keys` be bound at the same time. For example, you bind the `escape` key on a route and the route's template renders a component that also binds the `escape` key. Highest priority takes precedence.
`disableOnInput`	boolean	No	`false`	A boolean to determine whether the callback should be fired when an `input`, `textarea`, or `select` element is active.

`deregister({name})`

Accepts an object with the following attribute:

Name	Type	Required	Default	Description
`name`	string	Yes	`<none>`	The same string with which the shortcut was registered in the `register()` call.

Key Names

The full list of key names can be found here.

The modifier keys – those that don't trigger execution of a shortcut – can be found here.

Examples

Here's an example usage on a component:

import Ember from 'ember';

const {
  get,
  inject,
} = Ember;

export default Ember.Component.extend({
  keyManager: inject.service(),

  didInsertElement() {
    get(this, 'keyManager').register({
      keys: ['escape'],
      name: 'search-modal',
      downCallback: run.bind(this, function() {
        this.send('toggleModal');
      }),
      priority: 10,
    });
  },

  willDestroyElement() {
    get(this, 'keyManager').deregister({
      name: 'search-modal', // This name must match the name the binding was registered with above.
    });
  },

  actions: {
    toggleModal(){
      this.sendAction('toggleModalAction');
    },
  },
});

And an example on a route:

import Ember from 'ember';

const {
  get,
  inject,
} = Ember;

export default Ember.Route.extend({
  keyManager: inject.service(),

  actions: {
    didTransition() {
      this._super(...arguments);

      get(this, 'keyManager').register({
        keys: ['escape'],
        name: 'fancy-route',
        downCallback: run.bind(this, this._redirectToLaLaLand),
        priority: 100,
      });
    },

    willTransition() {
      this._super(...arguments);

      get(this, 'keyManager').deregister({
        name: 'fancy-route',
      });
    },
  },

  // The `event` that's returned as a parameter here is the JS keyboard event.
  _redirectToLaLaLand(event) {
    if (event) {
      event.preventDefault();
    }
    this.transitionTo('main.la-la-land');
  },
});

Developing

Running

ember serve
Visit your app at http://localhost:4200.

Running Tests

npm test (Runs ember try:each to test your addon against multiple Ember versions)
ember test
ember test --server

livfwd/ember-key-manager