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