ember-key-manager

Compatibility

Ember Octane ready

• Ember.js v3.16 or above
• Ember CLI v2.13 or above
• Node.js v10 or above

Installation

A service for (un)binding keyboard keyup and keydown events.

• ember install ember-key-manager

Usage

Bind key event anywhere services are available e.g., routes, models, controllers, components, or use the modifiers in a template.

Config

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

  keyManagerConfig: {
    isDisabledOnInput: true,
  },

isDisabledOnInput

Defaults to false. Set the global option to true to change the default. The isDisabledOnInput option available on each macro takes precedence over this global config option.

Public Methods

addMacro({callback, element=document.body, executionKey, isDisabledOnInput, modifierKeys, priority=0, keyEvent})

A 'macro' is made of a combination of: zero or more modifierKeys, one executionKey, a callback function to execute when the macro is matched, the type of keyEvent, and a few optional attributes described below. addMacro() sets up this binding between keys and callback. When the exact combination of the executionKey, modifierKeys, and eventType are matched, the callback is triggered.

addMacro() accepts an object with the following attributes:

removeMacro(macro)

Accepts a macro object that is returned from calling addMacro().

disable(macro or groupName)

Accepts a macro object that is returned from calling addMacro() or a string as a group name. If a macro, it disables the callback for that individual macro from being called on match. If it is a group name, it looks for all macros with a matching group name and disables them. When a macro is disabled, it will remain disabled till you call enable().

enable(macro or groupName)

Accepts a macro object that is returned from calling addMacro() or a string as a group name. If a macro, it enables the callback for that individual macro, ensuring that the callback is called on match. If it is a group name, it looks for all macros with a matching group name and enables them.

Key Names

A string that's the value of the key that triggers the macro's callback e.g., to make letter A the execution key, set executionKey to a. If unsure of a key's value, use this tool to it test out.

Allowed modifier key names are: Alt, Control, Meta, Shift.

Examples

Here's an example usage on a component:

import Component from '@ember/component';
import {
  get,
  set,
} from '@ember/object';
import { inject as injectService } from '@ember/service';
import {
  bind,
} from '@ember/runloop';

export default Component.extend({
  keyManager: injectService(),

  didInsertElement() {
    const closeModalMacro = get(this, 'keyManager').addMacro({
      callback: bind(this, function() {
        this.send('toggleModal');
      }),
      executionKey: 'Escape',
      priority: 10,
      keyEvent: 'keydown',
    });
    set(this, 'closeModalMacro', closeModalMacro);
  },

  willDestroyElement() {
    const closeModalMacro = get(this, 'closeModalMacro');
    get(this, 'keyManager').removeMacro(closeModalMacro);
  },

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

And an example on a route:

import Route from '@ember/routing/route';
import { inject as injectService } from '@ember/service';
import { get, set } from '@ember/object';

export default Route.extend({
  keyManager: injectService(),

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

      const redirectMacro = get(this, 'keyManager').addMacro({
        callback: bind(this, this._redirectToLaLaLand),
        executionKey: 'Escape',
        priority: 100,
        keyEvent: 'keydown',
      });
      set(this, 'redirectMacro', redirectMacro);
    },

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

      const redirectMacro = get(this, 'redirectMacro');
      get(this, 'keyManager').removeMacro(redirectMacro);
    },
  },

  // The `callback` is called with the KeyboardEvent `event`.
  _redirectToLaLaLand(event) {
    if (event) {
      event.preventDefault();
    }
    this.transitionTo('main.la-la-land');
  },
});

And an example in a template:

{{!-- components/my-component/template.hbs --}}
{{!-- use the key-down or key-up modifier --}}
{{!-- 
  Everything is optional except the callback and the execution key.
  Use the same options as on the key manager service addMacro() 
--}}

<div>

//components/my-component/component.js
import Component from '@ember/component';
import { action } from '@ember/object';

export default class MyComponent extends Component {
  @action
  _redirectToLaLaLand(event) {
    if (event) {
      event.preventDefault();
    }
    this.transitionTo('main.la-la-land');
  }
}

Developing

Running

Running Tests

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

Installation

ember install ember-key-manager

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.