README.md

Mousetrap::Rails

Mousetrap is a javascript library for handling keyboard shortcuts in your web applications written by Craig Campbell.

The mousetrap-rails gem integrates Mousetrap javascript library with Rails asset pipeline.

Installation

Add mousetrap-rails gem to app

Add this line to your application's Gemfile:

gem 'mousetrap-rails'

And then execute:

$ bundle install

Run generator

$ rails generate mousetrap:install

It will create a sample keybindings.js.coffee file in app/assets/javascripts and insert mousetrap-rails files to manifests of asset pipeline

//= require mousetrap     # ---> application.js
*= require mousetrap      # ---> application.css

Voila!

Also you can use mousetrap plugins. Require them in your application.js file

//= require mousetrap/plugins       # To require all plugins
//= require mousetrap/dictionary    # To require dictionary plugin
//= require mousetrap/global        # To require global plugin
//= require mousetrap/pause         # To require pause plugin
//= require mousetrap/record        # To require record plugin

See plugin descriptions below.

Latest (may be unstable) version

Instead of gem 'mousetrap-rails' add to your Gemfile

gem 'mousetrap-rails', github: 'kugaevsky/mousetrap-rails'

Mousetrap-rails versioning use mousetrap.js library version number.

Usage

Via data-attributes

You can add keyboard navigation to your links by using data-keybinding attribute.

= link_to 'Homepage', root_path, data: { keybinding: 'h' }          # Press 'h' to navigate to homepage
= link_to 'About', about_path, data: { keybinding: '["a", "c"]' }   # Press 'a' or 'c' to navigate to about

You can jump to an input

= text_field_tag 'Username', nil, data: { keybinding: 'u' }         # Press 'u' to focus username input field

Via javascript

Any javascript function can be called with mousetrap

Mousetrap.bind 'f', (e) -> alert 'My perfect function called'       # Press 'f' to popup alert

More examples (from official guide)

# single keys
Mousetrap.bind '4', -> alert '4 pressed!'
Mousetrap.bind 'x', (-> alert 'x pressed!'), 'keyup'

# combinations
Mousetrap.bind 'command+shift+k', ->
  alert 'command+shift+k pressed!'
  false

Mousetrap.bind ['command+k', 'ctrl+k'], ->
  alert 'command+k or ctrl+k pressed!'
  false

# gmail style sequences
Mousetrap.bind 'g i', -> console.log 'g i sequence pressed!'
Mousetrap.bind '* a', -> console.log '* a sequence pressed!'

# konami code!
Mousetrap.bind 'up up down down left right left right b a enter', -> console.log 'You WIN!'

You can find full documentation on Mousetrap library page. Really, look there – there are plenty examples of using this awesome library.

Key binding hints (experimental)

You can display key binding hints near links with data-keybinding attribute by pressing Alt+Shift+h. Now it's just experimental feature for debugging purposes only.

Plugins

Global Bindings

//= require mousetrap/global        # ---> application.js

This extension allows you to specify keyboard events that will work anywhere including inside textarea/input fields.

Mousetrap.bindGlobal 'ctrl+s', -> _save()

This means that a keyboard event bound using Mousetrap.bind will only work outside of form input fields, but using Moustrap.bindGlobal will work in both places.

Bind dictionary

//= require mousetrap/dictionary        # ---> application.js

This extension overwrites the default bind behavior and allows you to bind multiple combinations in a single bind call.

Usage looks like:

Mousetrap.bind
    'a': -> console.log('a')
    'b': -> console.log('b')

You can optionally pass in keypress, keydown or keyup as a second argument.

Other bind calls work the same way as they do by default.

Pause/unpause

//= require mousetrap/pause             # ---> application.js

This extension allows Mousetrap to be paused and unpaused without having to reset keyboard shortcuts and rebind them.

# stop Mousetrap events from firing
Mousetrap.pause()

# allow Mousetrap events to fire again
Mousetrap.unpause()

Record

//= require mousetrap/record              # ---> application.js

This extension lets you use Mousetrap to record keyboard sequences and play them back:

button onclick="recordSequence()" Record

recordSequence = () ->
  Mousetrap.record (sequence) ->
    # sequence is an array like ['ctrl+k', 'c']
    alert('You pressed: ' + sequence.join(' '))

More detailed plugins description

Contributing

Please submit all pull requests against latest *.wip branch. If your pull request contains new features, you must include relevant tests.

You can easily update mousetrap.js library via rake tasks.

$ rake mousetrap:update          # Update main mousetrap javascript lib and its plugins
$ rake mousetrap:update:main     # Update main mousetrap javascript lib
$ rake mousetrap:update:plugins  # Update mousetrap javascript lib plugins

Thanks in advance!

Changelog

All changes could be found in CHANGELOG.md

License

Gosh! It's here.

Authors

• mousetrap-rails gem by Nick Kugaevsky and contributors
• original mousetrap library by Craig Campbell