Hotkey
======

== ABOUT

Plugin to add easy support for javascript hotkeys to a Rails application.

== INSTALLATION

The hotkey.js file should be copied to public/javascripts upon plugin installation.  If it's not been installed, run the 
available rake task to update:

  rake hotkey:update

The hotkey.js file is automatically added to the javascript include defaults, so if you're using 
javascript_include_tag(:defaults), inclusion of the necessary javascript will be handled automatically.  If you're not 
using :defaults, you can include the necessary JavaScript manually using javascript_include_tag('hotkey'). Please note 
that Prototype is a dependency.

IMPORTANT: To activate hotkeys for a given layout, you must add the following to the _body_ tag:

  onkeydown="Hotkey.process(event)"
  
Note: You could also attach Hotkey.process in an onload handler unobtrusively. I'd recommend you do this if you have the 
javascript chops.

== USAGE

While it's recommended that your hotkey definitions are made in a .js vs directly in a view whenever possible, the 
plugin includes a number of helpers to help you define hotkeys dynamically from Ruby.

Please note that the all hotkeys defined require the pressing of a modifier key as well; due to the spotty nature of 
javascript character code handling, the modifier key that it is bound may differ from platform-to-platform and 
browser-to-browser.

Note: If you'd like to define hotkeys directly in your javascript files, look at the provided helpers for examples of 
how to use Hotkey.add in the javascript API.  The 

=== Binding a function

Use hotkey_to_function similar to how you'd use link_to_function (without html options, obviously):

  <%= hotkey_to_function(:h, "$('help-sidebar').show();") %>

This will bind 'h' (with a modifier key)

=== Binding a remote function (AJAX)

Use hotkey_to_remote similar to how you'd use link_to_remote (without html options, obviously)

  <%= hotkey_to_remote(:s, :url => {:controller=>'foo', :action => 'bar'})

This will bind 's' (with a modifier key)

== CREDITS

MIT License
Copyright (c) 2006 - 2008 Bruce Williams (http://codefluency.com)

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sub-license, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.