Ember-key-manager NPM

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:

Name	Type	Required	Default	Description
`callback`	`Function`	Yes	`null`	A function to be called when the macro keys are matched, the `keyEvent` event is fired, and the scope defined by `element` is correct. When called, the `callback` is called with the keyboard `event` that triggered the macro.
`element`	`Element`	No	`document.body`	A DOM element by which to scope the macro. Events triggered on or within this element will fire the macro's callback.
`executionKey`	`String`	Yes	`''`	A case-insensitive 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. This can be a modifier key.
`isDisabledOnInput`	`Boolean`	No	`false`	A boolean to determine if a macro's the callback should be fired when a `contentEditable`, `input`, `textarea`, or `select` element is focused.
`modifierKeys`	`Array`	No	`[]`	An array of modifier key names of case-insensitive strings. Options are `Alt`, `Control`, `Meta`, `Shift`. A warning will be logged if trying to use modifierKeys on a keyup event since this keyEvent will never match.
`priority`	`Number`	No	`0`	An integer used to prioritize macros if there's more than one macro with the same `keys` listening at the same time. For example, you add a macro with the `escape` key on a route and the route's template renders a component that also binds a macro with the `escape` key. Highest priority takes precedence.
`keyEvent`	`String`	Yes	`null`	Dictates which key event is used for the macro. Options are: `keydown`, `keyup`.
`groupName`	`String`	No	`null`	Used with disabling and enabling a group of macros.
`isDisabled`	`String`	No	`false`	Determines whether the macro's callback will be triggered on keyEvent match.

`removeMacro(macro)`

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

Name	Type	Required	Default	Description
`macro`	`Object`	Yes	`undefined`	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().

Name	Type	Required	Default	Description
`macro`	`Object`	Yes (or `groupName`)	`undefined`	A macro object that is returned from calling `addMacro()`.
`groupName`	`String`	Yes (or `macro`)	`undefined`	A string that was used as a `groupName` on one or more of the macros added with `addMacro()`.

`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.

Name	Type	Required	Default	Description
`macro`	`Object`	Yes (or `groupName`)	`undefined`	A macro object that is returned from calling `addMacro()`.
`groupName`	`String`	Yes (or `macro`)	`undefined`	A string that was used as a `groupName` on one or more of the macros added with `addMacro()`.

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 {{key-down "A" this._redirectToLaLaLand modifiers=(array "Ctrl" "Shift") priority=7}}/>

//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');
  }
}