:information_source: View this commit on Github
:busts_in_silhouette: Authored by Andreas Fernandez a.fernandez@scripting-base.de
:heavy_check_mark: Merged by Andreas Kienast a.fernandez@scripting-base.de
Commit message
[FEATURE] Add hotkey API to TYPO3 backend
TYPO3 provides a new API to let developers easily add keyboard
shortcuts to execute certain actions.
The following shortcuts are already in place:
Ctrl/Cmd + K: Open LiveSearch
Ctrl/Cmd + S: Save open FormEngine record
The API allows to register hotkeys in scoped maps, where the scope can
be changed during runtime. However, hotkeys registered in the all
scope are always executed, if found, to avoid overriding global
shortcuts.
13.0/Feature-101507-HotkeyAPI.rst
```rst
.. include:: /Includes.rst.txt
.. _feature-101507-1690808401:
=============================
Feature: #101507 - Hotkey API
=============================
See :issue:`101507`
Description
===========
TYPO3 provides the :js:`@typo3/backend/hotkeys.js` module that allows developers
to register custom keyboard shortcuts in the TYPO3 backend.
It is also possible and highly recommended to register hotkeys in a dedicated
scope to avoid conflicts with other hotkeys, perhaps registered by other
extensions.
The module provides an enum with common modifier keys (:kbd:`Ctrl`, :kbd:`Meta`,
:kbd:`Alt`, and :kbd:`Shift`), and also a public property describing the common
hotkey modifier based on the user's operating system: :kbd:`Cmd` (Meta) on macOS,
:kbd:`Ctrl` on anything else. Using any modifier is optional, but highly
recommended.
A hotkey is registered with the :js:`register()` method. The method takes three
arguments:
* :js:`hotkey` - An array defining the keys that must be pressed
* :js:`handler` - A callback that is executed when the hotkey is invoked
* :js:`options` - Object that configured a hotkey's behavior.
* :js:`scope` - The scope a hotkey is registered in
* :js:`allowOnEditables` - If :js:`false` (default), handlers are not executed when an editable element is focussed
* :js:`allowRepeat` - If :js:`false` (default), handlers are not executed when the hotkey is pressed for a long time
* :js:`bindElement` - If given, an `aria-keyshortcuts` attribute is added to the element. This is recommended for accessibility reasons.
.. code-block:: js
import { Hotkeys, ModifierKeys } from '@typo3/backend/hotkeys.js';
Hotkeys.register([Hotkeys.normalizedCtrlModifierKey, ModifierKeys.ALT, 'e'], function (keyboardEvent) => {
console.log('Triggered on Ctrl/Cmd+Alt+E');
}, { scope: 'my-extension/module', bindElement: document.querySelector('.some-element') });
// Get the currently active scope
const currentScope = Hotkeys.getScope();
// Make use of registered scope
Hotkeys.setScope('my-extension/module');
.. note::
TYPO3 specific hotkeys may be registered in the reserved `all` scope.
When invoking a hotkey from a different scope, the `all` scope is handled in
any case at first.
Impact
======
If properly used, common functionality is easier to access with hotkeys. The
following hotkeys are configured within TYPO3:
* :kbd:`Ctrl/Cmd` + :kbd:`K` - open LiveSearch
* :kbd:`Ctrl/Cmd` + :kbd:`S` - save current document opened in FormEngine
.. index:: Backend, JavaScript, ext:backend
```
brotkrueml
commented
9 months ago
:information_source: View this commit on Github :busts_in_silhouette: Authored by Andreas Fernandez a.fernandez@scripting-base.de :heavy_check_mark: Merged by Andreas Kienast a.fernandez@scripting-base.de
Commit message
[FEATURE] Add hotkey API to TYPO3 backend
TYPO3 provides a new API to let developers easily add keyboard shortcuts to execute certain actions.
The following shortcuts are already in place:
The API allows to register hotkeys in scoped maps, where the scope can be changed during runtime. However, hotkeys registered in the
allscope are always executed, if found, to avoid overriding global shortcuts.Resolves: #101507 Releases: main Change-Id: I201c063595a8274569691bbcaa243c858557ea07 Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/80266 Tested-by: core-ci typo3@b13.com Reviewed-by: Benni Mack benni@typo3.org Reviewed-by: Christian Kuhn lolli@schwarzbu.ch Tested-by: Andreas Kienast a.fernandez@scripting-base.de Tested-by: Christian Kuhn lolli@schwarzbu.ch Tested-by: Benni Mack benni@typo3.org Reviewed-by: Andreas Kienast a.fernandez@scripting-base.de
:heavy_plus_sign: Added files
13.0/Feature-101507-HotkeyAPI.rst
```rst .. include:: /Includes.rst.txt .. _feature-101507-1690808401: ============================= Feature: #101507 - Hotkey API ============================= See :issue:`101507` Description =========== TYPO3 provides the :js:`@typo3/backend/hotkeys.js` module that allows developers to register custom keyboard shortcuts in the TYPO3 backend. It is also possible and highly recommended to register hotkeys in a dedicated scope to avoid conflicts with other hotkeys, perhaps registered by other extensions. The module provides an enum with common modifier keys (:kbd:`Ctrl`, :kbd:`Meta`, :kbd:`Alt`, and :kbd:`Shift`), and also a public property describing the common hotkey modifier based on the user's operating system: :kbd:`Cmd` (Meta) on macOS, :kbd:`Ctrl` on anything else. Using any modifier is optional, but highly recommended. A hotkey is registered with the :js:`register()` method. The method takes three arguments: * :js:`hotkey` - An array defining the keys that must be pressed * :js:`handler` - A callback that is executed when the hotkey is invoked * :js:`options` - Object that configured a hotkey's behavior. * :js:`scope` - The scope a hotkey is registered in * :js:`allowOnEditables` - If :js:`false` (default), handlers are not executed when an editable element is focussed * :js:`allowRepeat` - If :js:`false` (default), handlers are not executed when the hotkey is pressed for a long time * :js:`bindElement` - If given, an `aria-keyshortcuts` attribute is added to the element. This is recommended for accessibility reasons. .. code-block:: js import { Hotkeys, ModifierKeys } from '@typo3/backend/hotkeys.js'; Hotkeys.register([Hotkeys.normalizedCtrlModifierKey, ModifierKeys.ALT, 'e'], function (keyboardEvent) => { console.log('Triggered on Ctrl/Cmd+Alt+E'); }, { scope: 'my-extension/module', bindElement: document.querySelector('.some-element') }); // Get the currently active scope const currentScope = Hotkeys.getScope(); // Make use of registered scope Hotkeys.setScope('my-extension/module'); .. note:: TYPO3 specific hotkeys may be registered in the reserved `all` scope. When invoking a hotkey from a different scope, the `all` scope is handled in any case at first. Impact ====== If properly used, common functionality is easier to access with hotkeys. The following hotkeys are configured within TYPO3: * :kbd:`Ctrl/Cmd` + :kbd:`K` - open LiveSearch * :kbd:`Ctrl/Cmd` + :kbd:`S` - save current document opened in FormEngine .. index:: Backend, JavaScript, ext:backend ```