Keyboard events

Handling keyboard events can enhance the user experience of your application. Think of shortcuts for menu items, F1 for help, arrow keys for data navigation...

Introduction

Within desktop applications, power users are often familiar with keyboard shortcuts that allow them to be more productive. Sircl allows you to add similar behaviour in web applications easily.

Scoped

Using the onkeyenter-click and onkeyescape-click attributes on an element allow you to define a default button (that is clicked when pressing the Enter key in an INPUT element) and a cancel button (that is clicked when pressing the Escape key in an INPUT element) within the scope of that element. The value of these attributes is a CSS selector refering to the element to be clicked:

<form onkeyenter-click="#btnOk" onkeyescape-click="#btnCancel" >
  <input type="text" name="Name" autocomplete="off" />
  <button id="btnOk" type="submit"> OK </button>
  <a id="btnCancel" href="history:back" onclick-confirm="Quit?"> Cancel </a>
</form>

In this example, the default cancel button is a hyperlink. The default submit and default cancel buttons can be any element on which a click event can be sent.

Page-wide

To handle key events anywhere on the page (not within form controls), use the onkeydown-click attribute. This attribute takes the key(combination) that should trigger a click on the current element.

It handles key events on BODY, A and BUTTON elements. This means that as long as the focus is not on another element type such as a form control, the keydown event will be captured.

An exception is made for the F1 to F12 keys, as well as combinations with the Control and/or the Alt key, which are always captured.

In the following example we define a submit button that can be activated by click or by pressing the + keyboard key (line 2 - the Font Awesome icon - is merely decorative and can be removed):

<button type="submit" onkeydown-click="+">
  <i class="fas fa-plus spinner"></i>
  Add
</button>

Key codes

The value of the attribute, is the key to be pressed. This is whatever key is pressed, for instance: "a", "b", "c", "0", "1", "2", "+", "-", "*", "/", etc. This can also be function keys as "F1", "F2", "F3", etc. or other special keys including "Enter", "Escape", "ArrowUp", "ArrowDown", "ArrowLeft", ArrowRight", "Home", "End", "PageUp", "PageDown", "Insert" and "Delete".

Combinations with Alt, Control and Shift keys can be tested for by adding the prefixes "Alt+", "Ctrl+" or "Shift+" respectively, as in:

<a href="alert:Hello" onkeydown-click="Alt+F1"></a>

You can also combine Alt, Control and Shift keys but their prefixes must appear in that order. For instance, "Alt+Shift+F1" is valid, but "Shift+Alt+F1" is not.

Key codes are threated case-insensitively by Sircl on most browsers. This means "Ctrl+A" will be treated the same as "Ctrl+a". If you need support for older or limited browsers such as Internet Explorer, use the variant with lowercase letter-keys ("Ctrl+a") for best support.

The "F1" key (with or without Alt/Ctrl/Shift) has the additional feature that it will write to the browser console the key(combination) pressed, as well as the element that raised the event. This can be used to debug why some key events are nog captured.

Default action

When the key event was captured by an onkeydown-click handler, the default action well be prevented. For instance: by default a browser shows its help page when F1 is pressed. If you capture the F1 key, the browser will not show its help page anymore.
Note that older browsers may not honor this behavior. For instance, Internet Explorer will still show its help page.

Chaining click event-actions

The onkeydown-click event-action always performs a click action. But what if you want another action, for instance a focus action to happen ?

You can chain event-actions to obtain the desired result. For instance, suppose you want the / key to assign the focus to a search text box.

Using the onkeydown-click event-action is not going to work as raising a click event does not set the focus. So the following will not work:

<input type="text" name="search" onkeydown-click="/" />

Instead, you can create another element that will receive the click event and forward it as a focus action to the input:

<span onkeydown-click="/" onclick-focus="#searchbox"></span>
<input id="searchbox" type="text" name="search" />