Keys.js

Easy keybindings for browser applications!

View the Project on GitHub bitwalker/keys.js

Examples

Demo Application

The demo is a simulated web mail application with configurable keyboard shortcuts. View the source of mail.js to see how it was constructed. It should be noted that the architecture of the demo is simplistic and unscalable, but provides an easier environment to connect all the dots in one place. The code is fairly well documented, but if you have any questions, create an issue on GitHub and I will address it as soon as possible!

View Demo

Basic

View Demo

The following code demonstrates the most basic example of initializing Keys.js, adding a new binding, and defining behavior for that binding. It is assumed that for this, and all following examples, you have included the Keys.js script previously on the page.

(function() {
    window.Bindings = Keys.Bindings;
    window.Combo    = Keys.Combo;
    window.Key      = Keys.Key;

<span class="c1">// Initialize application-wide bindings manager</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">bindings</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Bindings</span><span class="p">();</span>

<span class="c1">// Add binding to display an alert</span>
<span class="nx">bindings</span><span class="p">.</span><span class="nx">add</span><span class="p">(</span><span class="s1">'displayAlert'</span><span class="p">,</span> <span class="k">new</span> <span class="nx">Combo</span><span class="p">(</span><span class="nx">Key</span><span class="p">.</span><span class="nx">A</span><span class="p">,</span> <span class="nx">Key</span><span class="p">.</span><span class="nx">SHIFT</span><span class="p">));</span>

<span class="c1">// Register display alert behavior using inferred name/eventType notation</span>
<span class="nx">bindings</span><span class="p">.</span><span class="nx">registerHandler</span><span class="p">(</span><span class="nx">displayAlert</span><span class="p">);</span>
<span class="cm">/**
 *  If you want to use a specific eventType (default is 'keydown'):
bindings.registerHandler('keyup', displayAlert);

 *  Or if you want to use a named function for a binding with a different name:
bindings.registerHandler('sayHello', displayAlert);

 *  Or if you want to use an anonymous function for the handler:
bindings.registerHandler('displayAlert', function() {
    alert('Hello!');
});

 *  Or if you want to specify everything at once:
bindings.registerHandler('displayAlert', 'keyup', displayAlert);

 */</span>
<span class="kd">function</span> <span class="nx">displayAlert</span><span class="p">()</span> <span class="p">{</span>
    <span class="nx">alert</span><span class="p">(</span><span class="s1">'Hello!'</span><span class="p">);</span>
<span class="p">}</span>

})();

Toggles

View Demo

This code demonstrates how to configure a basic toggle with behavior. I'm using jQuery syntax for DOM manipulation here, but it is not required by Keys.js and the basic concepts don't change.

(function() {
    window.Bindings = Keys.Bindings;
    window.Combo    = Keys.Combo;
    window.Key      = Keys.Key;

<span class="c1">// Initialize application-wide bindings manager</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">bindings</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Bindings</span><span class="p">();</span>

<span class="c1">// Add a binding to toggle the page background color</span>
<span class="nx">bindings</span><span class="p">.</span><span class="nx">add</span><span class="p">(</span><span class="s1">'toggleBackground'</span><span class="p">,</span> <span class="nx">Key</span><span class="p">.</span><span class="nx">B</span><span class="p">);</span>

<span class="cm">/**
 * Register background color toggle behavior
 * Toggles always fire on 'keydown'
 */</span>
<span class="nx">bindings</span><span class="p">.</span><span class="nx">registerToggle</span><span class="p">(</span><span class="s1">'toggleBackground'</span><span class="p">,</span> <span class="nx">toggleBlack</span><span class="p">,</span> <span class="nx">toggleWhite</span><span class="p">);</span>
<span class="kd">function</span> <span class="nx">toggleBlack</span><span class="p">()</span> <span class="p">{</span>
    <span class="nx">$</span><span class="p">(</span><span class="s1">'body'</span><span class="p">).</span><span class="nx">css</span><span class="p">(</span><span class="s1">'background-color'</span><span class="p">,</span> <span class="s1">'black'</span><span class="p">);</span>
    <span class="nx">$</span><span class="p">(</span><span class="s1">'h1'</span><span class="p">).</span><span class="nx">css</span><span class="p">(</span><span class="s1">'color'</span><span class="p">,</span> <span class="s1">'white'</span><span class="p">);</span>
<span class="p">}</span>
<span class="kd">function</span> <span class="nx">toggleWhite</span><span class="p">()</span> <span class="p">{</span>
    <span class="nx">$</span><span class="p">(</span><span class="s1">'body'</span><span class="p">).</span><span class="nx">css</span><span class="p">(</span><span class="s1">'background-color'</span><span class="p">,</span> <span class="s1">'white'</span><span class="p">);</span>
    <span class="nx">$</span><span class="p">(</span><span class="s1">'h1'</span><span class="p">).</span><span class="nx">css</span><span class="p">(</span><span class="s1">'color'</span><span class="p">,</span> <span class="s1">'black'</span><span class="p">);</span>
<span class="p">}</span>

})();

Using Bindings.load

View Demo

This code demonstrates how you can use Bindings.load to bulk define bindings and their behavior with one API call.

(function() {
    window.Bindings = Keys.Bindings;
    window.Combo    = Keys.Combo;
    window.Key      = Keys.Key;

<span class="c1">// Initialize application-wide bindings manager</span>
<span class="nb">window</span><span class="p">.</span><span class="nx">bindings</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Bindings</span><span class="p">();</span>

<span class="nx">bindings</span><span class="p">.</span><span class="nx">load</span><span class="p">({</span>
    <span class="na">displayAlert</span><span class="p">:</span> <span class="p">{</span>
        <span class="na">bind</span><span class="p">:</span> <span class="k">new</span> <span class="nx">Combo</span><span class="p">(</span><span class="nx">Key</span><span class="p">.</span><span class="nx">A</span><span class="p">,</span> <span class="nx">Key</span><span class="p">.</span><span class="nx">SHIFT</span><span class="p">),</span>
        <span class="na">handler</span><span class="p">:</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
            <span class="nx">alert</span><span class="p">(</span><span class="s1">'Hello!'</span><span class="p">);</span>
        <span class="p">}</span>
    <span class="p">},</span>
    <span class="na">displayModal</span><span class="p">:</span> <span class="p">{</span>
        <span class="na">bind</span><span class="p">:</span> <span class="k">new</span> <span class="nx">Combo</span><span class="p">(</span><span class="nx">Key</span><span class="p">.</span><span class="nx">M</span><span class="p">,</span> <span class="nx">Key</span><span class="p">.</span><span class="nx">SHIFT</span><span class="p">),</span>
        <span class="na">handler</span><span class="p">:</span> <span class="nx">displayModal</span>
    <span class="p">},</span>
    <span class="na">hideModal</span><span class="p">:</span> <span class="p">{</span>
        <span class="na">bind</span><span class="p">:</span> <span class="k">new</span> <span class="nx">Combo</span><span class="p">(</span><span class="nx">Key</span><span class="p">.</span><span class="nx">X</span><span class="p">,</span> <span class="nx">Key</span><span class="p">.</span><span class="nx">SHIFT</span><span class="p">),</span>
        <span class="na">eventType</span><span class="p">:</span> <span class="s1">'keypress'</span><span class="p">,</span>
        <span class="na">handler</span><span class="p">:</span> <span class="nx">hideModal</span>
    <span class="p">}</span>
<span class="p">});</span>

<span class="kd">function</span> <span class="nx">displayModal</span><span class="p">()</span> <span class="p">{</span>
    <span class="nx">$</span><span class="p">(</span><span class="s1">'.modal'</span><span class="p">).</span><span class="nx">fadeIn</span><span class="p">(</span><span class="s1">'fast'</span><span class="p">);</span>
<span class="p">}</span>
<span class="kd">function</span> <span class="nx">hideModal</span><span class="p">()</span> <span class="p">{</span>
    <span class="nx">$</span><span class="p">(</span><span class="s1">'.modal'</span><span class="p">).</span><span class="nx">fadeOut</span><span class="p">(</span><span class="s1">'fast'</span><span class="p">);</span>
<span class="p">}</span>

})();