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

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.