[#38092] - [4.2] [GSoC 21] Keyboard-Shortcut Plugin
- Fixed in Code Base
- 22 Jun 2022
- Medium
- Build: 4.2-dev
- # 38092
- Diff
- fancyFranci:gsoc
User tests: Successful: Unsuccessful:
Summary of Changes
This is a new plugin, developed in the GSoC 21 Accessibility project.
It introduces keyboard shortcuts to the administrator site like pressing J + F to jump into the search field or J + S to save. Other extensions are able to add their shortcuts as well by hooking in on the onLoadShortcuts event. All(!) of them are listed in a modal window, which shows up by pressing J + X.
The current state is just the start. Further steps would be the editing of shortcuts, the possibility to disable them, changing the overview-text-hint to a button in the corner etc. The editing was there already but it had some flaws, so it will come later (without flaws) :)
Thanks to @Krshivam25 the student behind this GSoC project, @chmst, @bembelimen, and @brianteeman for alle the work and feedback!
Testing Instructions
Make sure the shortcut plugin is enabled and start by pressing J + X (in sequence, not at the same time!) for the overview. Have a look at the hint, which tells you the same at the bottom of the page. Then visit different pages and try out the shortcuts :)
If your motivated you can let your plugin add new shortcuts and test them! Add "onLoadShortcuts" to the getSubscribedEvents and write something like this:
public function onLoadShortcuts(EventInterface $event): void {
$shortcuts = $event->getArgument('shortcuts');
$testShortcuts = array('test' => (object)['shortcut' => 'J + T', 'title' => 'Great Test', 'selector' => '#menu-collapse']);
$event->setArgument('shortcuts', array_merge($shortcuts, $testShortcuts));
}
Actual result BEFORE applying this Pull Request
You needed to click on buttons to do something
Expected result AFTER applying this Pull Request
You can use your keyboard to do something (besides typing text)
Documentation Changes Required
Yes, I will create a page to describe the build up of the shortcuts, how extensions can add them and what the default joomla shortcuts are. Part of it would be:
The 3rd party plugin needs to provide an array of shortcuts which are objects:
{ shortcut: string, selector: string, title: string }
The shortcut needs to be a keyboard input, separated by a plus e.g. "J + Y" or "ALT + Z + 7" (currently there is really no filtering).
Selectors are like CSS selectors to target an element. When it is an input element, the shortcut gives focus, otherwise it will be clicked.
The Title will be displayed in the overview. It could be the name of the target.
| Status | New | ⇒ | Pending |
joomla-cms-bot
- | Category | ⇒ | Administration Language & Strings Repository JavaScript NPM Change SQL Installation Postgresql Front End Plugins |
Other extensions are able to add their shortcuts as well by hooking in on the onLoadShortcuts event.
Can you provide an example please
All of them are listed in a modal window, which shows up by pressing J + X.
Would that include these additional extension provided shortcuts
| Labels |
Added:
Language Change
NPM Resource Changed
?
|
||
| Category | Administration Language & Strings Repository JavaScript NPM Change SQL Installation Postgresql Front End Plugins | ⇒ | SQL Administration com_admin Postgresql Language & Strings Repository JavaScript NPM Change Installation Front End Plugins |
When the keyboard focus is on a select then the hotkeys do not work
I am sorry I made a big accessibility mistake when I suggested using J as the modifier key.
If you are unable to press or have difficulty pressing shortcut key combinations then (on windows) you can enable sticky keys.
However the only sticky keys are the traditional modifiers.
The way github does it using the G key is that they appear to use it as a keyboard sequence and not a modifier.
In other words I can press G followed by I to go to issues
In this PR I have to press and hold J while pressing the S to go to the Search bar
When the keyboard focus is on a select then the hotkeys do not work
From my side this is intended. Users should be able to jump to a select value with a character, depending on the available values. Like pressing "u" in the "-select featured-" select, I want to jump to "unfeatured". If there is a value starting with "j", I want to select that.
All of them are listed in a modal window, which shows up by pressing J + X.
Would that include these additional extension provided shortcuts
Yes, as long as the provided shortcuts have a title, they are added to the overview.
@brianteeman Like your screenshot displayed it shortcuts can trigger different things, depending on the context. I did not find a screen where the Search and the Save & Close button are both present, so I let them use the same shortcut. Same with New and Save & New. Do you have concerns or is it their presentation in the overview which is an issue?
Do you have concerns or is it their presentation in the overview which is an issue?
Both.
In other systems only the valid shortcuts are displayed (see github for examples)
It is not normal to use the same shortcut for two different things. It really makes memorising them very difficult.
When the keyboard focus is on a select then the hotkeys do not work
From my side this is intended. Users should be able to jump to a select value with a character, depending on the available values. Like pressing "u" in the "-select featured-" select, I want to jump to "unfeatured". If there is a value starting with "j", I want to select that.
you are correct that they should be able to find a value beginning with J. But you are using J as a modifier key. In other words press J on its own and it will find the word beginning with J. Press J in combination with another key and the shortcut should happen.
Please add the plugin to the list of core plugins
[...]
The way github does it using the G key is that they appear to use it as a keyboard sequence and not a modifier.In other words I can press G followed by I to go to issues In this PR I have to press and hold J while pressing the S to go to the Search bar
Ooh thats the reason github does that... I hoped we would not need that, as it means splitting up the shortcuts, adding a timeout, and so on.
Is this something we could add to the future-feature-list or is it stopping this PR?
Is this something we could add to the future-feature-list or is it stopping this PR?
Well we can't call it an accessibility feature if it is not usable by someone who cannot press more than one key at a time. it needs to be a key sequence and not a key combination.
I think you can do it by setting a scope of J. But I could be completely wrong.
Do you have concerns or is it their presentation in the overview which is an issue?
Both.
In other systems only the valid shortcuts are displayed (see github for examples)
It is not normal to use the same shortcut for two different things. It really makes memorising them very difficult.
Ok, the only reason for doubling them were the matching characters. Search => S, Save => S, but yes, it is not optimal. Then I need to set "random" chars or do you have another idea? :/
| Category | Administration Language & Strings Repository JavaScript NPM Change SQL Installation Postgresql Front End Plugins com_admin | ⇒ | SQL Administration com_admin Postgresql Language & Strings Repository JavaScript NPM Change Installation Libraries Front End Plugins |
Then I need to set "random" chars or do you have another idea? :/
well F (find) is usually used in browsers to prevent conflicts with S (save)
This might look better if the keys come before the text?
It works much better now with the scope and using the keys in sequence. Its finally accessible.
However this means that it can not be called a modifier key. A modifier key is a key thata you hold down to change another key. And it doesnt work if you try to do that. Not sure what the correct terminology is. Will check that in the morning.
Indeed, the other way around looks better! Happy testing everyone
Note to self (or anyone else) of additional things to test tomorrow
- English strings
- RTL
- non english keyboard
- accessibility with screen reader
- order the keys in the overview (and how to make that sensible in other languages?)
Can I request one additional ccore shortcut J D
takes you to the home dashboard
However this means that it can not be called a modifier key. A modifier key is a key thata you hold down to change another key. And it doesnt work if you try to do that.
This works for me, first pressing "J" and then "ALT + N" at the same time.
* [ ] accessibility with screen reader
I wonder if we should show some kind of modal/text when "J" was pressed with aria-attributes to make aware, that we're in the shortcut mode?
Can I request one additional ccore shortcut J D takes you to the home dashboard
- Create Article
- Goto articles
- [...] menus
- [...] users
From everywhere...
* [ ] accessibility with screen readerI wonder if we should show some kind of modal/text when "J" was pressed with aria-attributes to make aware, that we're in the shortcut mode?
I will check what screen readers do with their own keys
Example here: Key combination first: https://webaim.org/resources/shortcuts/nvda
Also on Visual studio Code.
What Screenreaders announce depends on screenreader and OS. Will build a test installation where more people can perform tests.
Grrrh.
Using a keyboard sequence doesnt seem to work as I expected. It doesnt work at all in NVDA or Windows Narrator.
In both cases the combination J + X tries to go to the next checkbox.
successfully tested in arabic that both the display in RTL is correct and that the shortcut keys work in chrome for windows when chrome and joomla are set to use arabic language for display and arabic language for keyboard
Can I request one additional ccore shortcut J D takes you to the home dashboard
* Create Article * Goto articles * [...] menus * [...] usersFrom everywhere...
I added the possibility in general and dashboard works. I can include more shortcuts of course, I only need details about urls and selectors.
Maybe sort in the same order as in the plugin and move text next to keys?
PLUGIN:
MODAL:
Instead of using .badge, maybe use <kbd>. https://getbootstrap.com/docs/5.2/content/reboot/#user-input
Instead of using
.badge, maybe use<kbd>. https://getbootstrap.com/docs/5.2/content/reboot/#user-input
Thanks for the hint, it makes the html much more readable.
[...] and move text next to keys?
Currently it is a dl and thats the default style of that kind of list. Previously it was a ul and all in line but wishes were to use a dl. Long story short I let the style like it is for now, but as more improvements are planned it could be part of them.
But I aligned the order at least :)
Ok guys, my target is to bring this feature into 4.2 beta-2 which will be released today in the evening. Otherwise shortcuts would need to wait until 4.3. So every further improvement will find its way into beta-3 and this PR here will get merged after 2 tests. I hope thats ok, @brianteeman ? :) Would be great when we can create a list of things needed to be finished before beta-3.
Make the legend less prominent?
<span class="icon-keyboard fa-keyboard me-2" aria-hidden="true"></span> <kbd>J</kbd>+<kbd>X</kbd> <small>Keyboard Shortcuts</small>
I have tested this item
This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/38092.
I have tested this item
Great!
This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/38092.
Grrrh. Using a keyboard sequence doesnt seem to work as I expected. It doesnt work at all in NVDA or Windows Narrator.
In both cases the combination J + X tries to go to the next checkbox.
Grrrh. Using a keyboard sequence doesnt seem to work as I expected. It doesnt work at all in NVDA or Windows Narrator.
In both cases the combination J + X tries to go to the next checkbox.
Sorry, that one got lost in all the comments. I'll have a look on that, maybe preventing defaults after J was pressed (not X alone) could be enough.
I find the legend in the footer a little distracting. My focus draws to it. It is useful in the beginning but I can see it becoming annoying after a while.
jx is a dl but the description in the plugin is a ul
I find the legend in the footer a little distracting. My focus draws to it. It is useful in the beginning but I can see it becoming annoying after a while.
Now the hint only appears on cpanel-pages like the home dashboard. As you said - its only useful at the beginning
Grrrh. Using a keyboard sequence doesnt seem to work as I expected. It doesnt work at all in NVDA or Windows Narrator.
In both cases the combination J + X tries to go to the next checkbox.
It seems like NVDA interrupt the keyboard input before js can do/prevent anything. Even when I change the shortcuts to something NVDA does not use, nothing happens besides making a sound. When we configure modifiers like ALT, they do not work in sequence because the browser interrupts (at least in my tests). What do you think @brianteeman ? :/
(not at my pc to test) what happens on github when you use nvda and the github shortcuts?
I tried out s for githubs search and I'm not jumping into the search field as long as nvda is running. Same with g and n, which should normally open notifications.
...but the command palette (which opens on ctrl+k) works with nvda
It looks like its a known issue with the nvda single character shortcuts
https://www.nvaccess.org/files/nvda/documentation/userGuide.html#SingleLetterNavigation
yes looks like this is one of those cases where a real screen reader user knows what to do.
"In browse mode, you can now toggle single letter navigation on and off by pressing NVDA+shift+space. When off, single letter keys are passed to the application, which is useful for some web applications such as Gmail, Twitter and Facebook."
or you switch from browse to focus mode.
Havng read the nvda manual link I am happy enough that the current code is ok to merge
| Status | Pending | ⇒ | Fixed in Code Base |
| Closed_Date | 0000-00-00 00:00:00 | ⇒ | 2022-06-22 14:42:55 |
| Closed_By | ⇒ | fancyFranci |
Thanks everybody! :)
thank you all.
Cant wait to read the docs how this can be extended by extensions
I wrote an example in the test instructions which I used myself to test added shortcuts. But yes, docs will follow.
You need to add update sql scripts