Skip to content
This repository

Rails gem for handling keyboard shortcuts via mousetrap javascript library

README.md

Mousetrap::Rails

Flattr this endorse Dependency Status Code Climate Build Status Coverage Status

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

Bitdeli Badge

Something went wrong with that request. Please try again.