angular-hotkeys

angular-hotkeys

Configuration-centric keyboard shortcuts for your Angular apps.

Features:

• Define hotkeys on an entire route, automatically binding and unbinding them as you navigate
• Automatic listing of shortcuts when users hit the ? key
• Super duper unit tests

Installation:

via bower:

$ bower install chieffancypants/angular-hotkeys

via npm:

$ npm install angular-hotkeys

Why I made this:

Other projects out there rely too heavily on HTML markup for keyboard shortcuts. For example:

<div class="player">
  <div class="playPause-btn" shortcut="{space: playPause}"></div>
  <div class="mute-btn" shortcut="{'ctrl+down': mute}"></div>
</div>

While this is a great approach for many Angular apps, some applications do not have a 1 to 1 relationship between DOM elements and controller methods. In my case, many methods on the controller were only accessible through the keyboard.

Additionally, this only allows you to pass a function reference, you can't pass arguments to the function you intend to call. So instead of simply calling seek(currentTime + 30) and seek(currentTime + 60), I needed to create a ton of helper functions on the scope (such as forward30 and forward60), and litter my HTML like this:

<div class="player" shortcut="{space: playPause,
                              'alt+right': forward30,
                              'ctrl+right': forward60,
                              'left': back30,
                              'ctrl+left': back60,
                              up: volumeUp,
                              down: volumeDown,
                              'ctrl+down': mute,
                              'ctrl+up': unmute,
                              f: fullscreen,
                              h: showHelp}">
  <div class="playPause-btn"></div>
  <div class="mute-btn"></div>
</div>

With a few dozen shortcuts, this left the DOM really messy, and with multiple views and directive templates, it was next to impossible to remember where all the different shortcuts were. This became a maintenance nightmare.

Usage:

You can either define hotkeys in your Controller, or in your Route configuration (or both). To start, though, require the lib as a dependency for your angular app:

angular.module('myApp', ['ngRoute', 'cfp.hotkeys']);

Behind the scenes, I'm using the Mousetrap library to manage the key bindings. Check out the docs there for more information on what kind of key combinations can be used.

Binding hotkeys in controllers:

angular.module('myApp').controller('NavbarCtrl', function($scope, hotkeys) {
  $scope.vol = 5;

  // Pass it an object:
  hotkeys.add({
    combo: 'ctrl+up',
    description: 'This one goes to 11',
    callback: function() {
      $scope.volume += 1;
    }
  });

  // or pass it arguments:
  hotkeys.add('ctrl+down', 'Turn the volume down on this hotness', function() {
    $scope.volume -= 1;
  });

});

Binding hotkeys in routes:

You can also define hotkeys on an entire route, and this lib will bind and unbind them as you navigate the app.

angular.module('myApp').config(function ($routeProvider) {
  $routeProvider.when('/', {
    controller: 'RestaurantsController',
    templateUrl: 'views/restaurants.html',
    hotkeys: [
      ['p', 'Sort by price', 'sort(price)']
    ]
  });
});

Binding hotkeys in directives:

Lastly, even though binding hotkeys in your templates/html tends to be a bad idea, it can be super useful for simple shortcuts. Think along the lines of a modal directive where you simply want to bind to the escape key or something equally simple. Accomplishing this within a controller is too much overhead, and it may lead to code-reuse.

Example of how directive-based hotkeys works:

<modal title="Modal Title" hotkeys="{esc: close}">

API

hotkeys.add(combo, description, callback)

• combo: They keyboard combo (shortcut) you want to bind to
• description: [OPTIONAL] The description for what the combo does and is only used for the Cheat Sheet. If it is not supplied, it will not show up, and in effect, allows you to have unlisted hotkeys.
• callback: The function to execute when the key(s) are pressed. Passes along two arguments, event and hotkey

hotkeys.add('ctrl+w', 'Description goes here', function (event, hotkey) {
  event.preventDefault();
});

// this hotkey will not show up on the cheat sheet:
hotkeys.add('ctrl+y', function (event, hotkey) {
  event.preventDefault();
});

hotkeys.add(object)

• object: An object version of the above parameters.

hotkeys.add({
  combo: 'ctrl+w',
  description: 'Description goes here',
  callback: function(event, hotkey) {
    event.preventDefault();
  }
});

hotkeys.get(key)

Returns the Hotkey object

hotkeys.get('ctrl+w');
// -> Hotkey { combo: 'ctrl+w', description: 'Description goes here', callback: function (event, hotkey) }

hotkeys.del(key)

Removes and unbinds a hotkey

hotkeys.del('ctrl+w');