Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Rails gem for handling keyboard shortcuts via mousetrap javascript library
Ruby CSS HTML CoffeeScript JavaScript

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
app/assets/stylesheets
lib
spec
vendor/assets/javascripts
.gitignore
.travis.yml
CHANGELOG.md
Gemfile
LICENSE.md
README.md
Rakefile
gem-public_cert.pem
mousetrap-rails.gemspec

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!

Latest (may be unstable) version

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

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

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.

TODO

  • Add moustrap extensions generator

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 task.

$ rake mousetrap:update

Thanks in advance!

Changelog

All changes could be found in CHANGELOG.md

License

Gosh! It's here.

Authors

Something went wrong with that request. Please try again.