⁠19.3. <rich:hotKey>

The <rich:hotKey> component allows one to register hot keys for the page or particular elements and to define client-side processing functions for these keys.

⁠19.3.1. Basic usage

There are two ways to register <rich:hotKey>:
  • place it anywhere on the page. In this case the <rich:hotKey> component is attached to the whole page. This is the default scenario.
  • attach it to specific elements by defining the selector attribute. This attribute uses the syntax of the jQuery Selectors (a superset of CSS selectors defined by W3C consortium) and additionally it expands JSF component IDs to client-side IDs (see the VDL documentation for the selector attribute).
The key attribute defines the hot key itself, which is processed by the component.
The key sequences can be defined using a "+" key separator. The key sequence modifiers needs to be defined in alphabetical order, e.g. alt+ctrl+shift.
Hot key processing can be disabled by setting rendered to false.
⁠

Example 19.5. <rich:hotKey> basic usage

​<rich:hotKey key="ctrl+z">
​    <rich:componentControl target="popup" operation="show" />
​</rich:hotKey>
​
​<rich:popupPanel id="popup">
​	...
​</rich:popupPanel>
The example contains <rich:hotKey> which handles the Ctrl+Z key sequence on the whole page. When the key sequence is pressed, the <rich:popupPanel> is displayed.

⁠19.3.2. Event processing

The enabledInInput attribute enables the hot key event processing when form inputs are focused. This attribute is false by default.
The preventDefault attribute specifies whether the hot key binding should prevent default browser-specific actions to be taken (e.g. Ctrl+A hot key selecting all available text, Ctrl+B opening bookmarks bar, etc.). This attribute has a default value of true.

Note

Even though RichFaces instructs the browser to prevent the default action, browser implementations do not support preventing browser's native actions for selected key combinations.
Although the inability to prevent default action is not usual, you may experience that both the programatically-defined action and the browser's native action are triggered (e.g. native popup appears).
To keep an application accessible, it is convenient to not depend on hot keys or hot key combinations heavily. Best practice is using a hot key only as shortcut for a given action.

⁠19.3.3. Event handlers

The following event handlers could be used to trigger client-side behaviors or to invoke javascript directly:
  • keydown (default event) is fired when the hot key sequence is initiated (the keys are down)
  • keyup is fired when the hot key sequence is finished (the keys are up)
⁠

Example 19.6. <rich:hotKey> event handlers

​<rich:hotKey key="ctrl+a" onkeyup="alert('Ctrl+A was pressed')" />

Note

The <rich:editor> uses <iframe> for the editable area.
The <iframe> doesn't allow one to propagate events outside of the <rich:editor>, making <rich:hotKey> unusable for handling events from <rich:editor>.
The CKEditor specific event handling mechanism should be used instead.

⁠19.3.4. Reference data

  • component-type: org.richfaces.HotKey
  • component-class: org.richfaces.component.UIHotKey
  • component-family: org.richfaces.HotKey
  • renderer-type: org.richfaces.HotKeyRenderer