JavaScript Keyboard Shortcuts API
Reference
Register and remove keyboard shortcuts from JavaScript through the global shortcut object, which the skin loads on every page of the wiki and which drives the bundled Keypress JS library. Put the code in a JavaScript Skin Extension so it runs on the pages you want it on.
Members
| Member | Parameters | Returns | What it does |
|---|---|---|---|
| shortcut.add(combination, callback, options) | the key combination, the function to run, and an optional map of the options below | nothing | Registers a shortcut. |
| shortcut.remove(combination) | the key combination | nothing | Unregisters that combination from every listener. |
| shortcut.all_shortcuts() | none | an Array of the registered Keypress combos, each carrying a keys array | Lists every shortcut currently registered on the page. |
Options
| Option | Default | What it does |
|---|---|---|
| target | document | Listens for the shortcut inside that DOM element only. |
| disable_in_input | false | Ignores the shortcut while an input, a textarea, a [contenteditable=true] element or the syntax highlighter has the focus. |
| type | shortcut.type.SIMPLE | Picks how the combination is matched, from the values below. |
Any other option is ignored, and logs a deprecation warning to the browser console.
| Value | Matches |
|---|---|
| shortcut.type.SIMPLE | The keys pressed together, once. |
| shortcut.type.COUNTING | The keys pressed together, counting the repetitions. |
| shortcut.type.SEQUENCE | The keys pressed one after the other, as x x x a is. |
Key combinations
A combination is lowercased, and its + separators become spaces, before it reaches Keypress. So Ctrl+Alt+N and ctrl alt n register the same shortcut, and the + form is kept only for compatibility with the syntax XWiki used before Keypress.
The library itself is documented at Keypress JS.
Registering a shortcut
shortcut.add("Ctrl+Alt+N", function () {
new XWiki.widgets.Notification("Congratulations on typing this one!", "done");
}, { disable_in_input: true });Removing a shortcut
shortcut.remove("Ctrl+Alt+N");Removing every shortcut
Iterate the Array with for...of: for...in would walk its indexes instead of its combos, and keys would be undefined.
for (const binding of shortcut.all_shortcuts()) {
shortcut.remove(binding.keys.join(' '));
}FAQ
Where do I put the code?
In a JavaScript Skin Extension, whose "Use this extension" field decides which pages it loads on.
Can I change the shortcuts XWiki ships with?
Those come from translation keys rather than from this API, and an administrator rebinds them by overriding those keys.
Why does my shortcut fire while I am typing in the editor?
Register it with disable_in_input: true, which stops the listener while an input, a textarea or a content-editable element has the focus.
