Adding visual clues that accesskey exists
Today I discovered that we already have accesskey support for navigation of
our documentation. And it's been there since at least 2007, according to
the mailing list archives.
I discovered this accidentally, because I was researching something and
just instinctively hit the right arrow in the vain hope that it was somehow
linked to the "Next" link.
Doing a view source on the page, I found the access keys: h = home, u = up,
n = next, p = previous. That's great, and easy to remember for English
speakers, everyone else less so. Accesskeys are primarily discovered via
screen readers, so this isn't a huge problem, but having something language
independent would be a nice touch. As far as I know, accesskeys cannot be
the arrow keys.
Accesskeys seem to have universal support (at least: Chrome, Edge, Firefox,
Safari, Opera) now according to
https://www.w3schools.com/tags/att_global_accesskey.asp but, as the page
says, they are not recommended largely because desktops and browsers tend
to reuse these keys.
I would like to make this feature more discoverable and useful. Some ideas,
in increasing order of complexity, are:
1. Add static hints to each link, so "Next" becomes "Next [n]". Fairly
simple, but visually clumsy, and it might not actually clue the user that
they need to hit ALT+n, not just "n". This chrome extension is an example
of how it might look
https://chrome.google.com/webstore/detail/display-access-keys/gpicedcgegaokienkdbbcagodgacpbpd?hl=en
. The extension itself seems stale if not completely abandoned, but the
screenshot gives a good visual representation.
2. Add the hint to the hovertext of the link. So, for example on
https://www.postgresql.org/docs/current/libpq-exec.html the Hovertext for
the "Next" link would become: "34.4 Asynchronous Command Processing
[ALT+n]". This would lead to more accidental discovery, but wouldn't alter
the existing static page appearance.
3. Add hotkey that launches an overlay which displays all available
keyboard shortcuts. A common example of this is typing '?' in gmail or any
other google web app.
4. Actually implement arrow keys with javascript, but leave the
accesskeys as-is. I'm not a front-end programmer of any great skill, but it
should be easy to capture the keydown event, filter for
ArrowUp/ArrowLeft/ArrowRight, and then either search the DOM for the anchor
with the corresponding accesskey, or rely on element ids (example:
"nav-left", "nav-up", "nav-right") to find the anchor and invoke a .click()
on it. Currently the navigation anchors do not have IDs, but adding them
for this purpose might close us off from a future use.
Thoughts?
On 13.01.23 23:07, Corey Huinker wrote:
1. Add static hints to each link, so "Next" becomes "Next [n]". Fairly
simple, but visually clumsy, and it might not actually clue the user
that they need to hit ALT+n, not just "n". This chrome extension is an
example of how it might look
https://chrome.google.com/webstore/detail/display-access-keys/gpicedcgegaokienkdbbcagodgacpbpd?hl=en <https://chrome.google.com/webstore/detail/display-access-keys/gpicedcgegaokienkdbbcagodgacpbpd?hl=en> . The extension itself seems stale if not completely abandoned, but the screenshot gives a good visual representation.2. Add the hint to the hovertext of the link. So, for example on
https://www.postgresql.org/docs/current/libpq-exec.html
<https://www.postgresql.org/docs/current/libpq-exec.html> the Hovertext
for the "Next" link would become: "34.4 Asynchronous Command Processing
[ALT+n]". This would lead to more accidental discovery, but wouldn't
alter the existing static page appearance.3. Add hotkey that launches an overlay which displays all available
keyboard shortcuts. A common example of this is typing '?' in gmail or
any other google web app.4. Actually implement arrow keys with javascript, but leave the
accesskeys as-is. I'm not a front-end programmer of any great skill, but
it should be easy to capture the keydown event, filter for
ArrowUp/ArrowLeft/ArrowRight, and then either search the DOM for the
anchor with the corresponding accesskey, or rely on element ids
(example: "nav-left", "nav-up", "nav-right") to find the anchor and
invoke a .click() on it. Currently the navigation anchors do not have
IDs, but adding them for this purpose might close us off from a future use.
I agree that hot key discoverability could be better, but I don't think
this is an issue in the PostgreSQL documentation; it's something the
browser should handle. The job of the HTML markup is to declare the key
-- then it's up to the browser how to present it. Otherwise, every
single web page in the world (well, those with hot keys) would have to
repeat this analysis, which seems on the wrong level to me.
I agree that hot key discoverability could be better, but I don't think
this is an issue in the PostgreSQL documentation; it's something the
browser should handle. The job of the HTML markup is to declare the key
-- then it's up to the browser how to present it. Otherwise, every
single web page in the world (well, those with hot keys) would have to
repeat this analysis, which seems on the wrong level to me.
I agree that that's a thing that browsers *should* be doing, but presently
none are (as far as I know), and the history of web development has many
examples of websites having to write crutches for deficient browsers so
that their users can have a decent experience, with the definition of
decent experience shifting over time.
Attached is a patch to add the nav- tags to the header (could just as
easily have done the footer) for up/down/left/right and the javascript to
find those ids and simulate a click. I've tested this on chrome (where
accesskeys work with alt+ ) and firefox (where accesskeys don't seem to
work at all) and it works as expected in both places. The javascript itself
is rather naive, but serves as a starting point for discussion.
In researching accesskey, I've noticed that the accesskey="t" stylesheet
section doesn't get rendered in our html anywhere. Was "t" = "table of
contents"? Seems like something we could delete until we need it again.
Attachments:
v1-0001-Add-javascript-to-enable-up-next-previous-navigat.patchtext/x-patch; charset=US-ASCII; name=v1-0001-Add-javascript-to-enable-up-next-previous-navigat.patchDownload+10-5
On 18.01.23 22:49, Corey Huinker wrote:
Attached is a patch to add the nav- tags to the header (could just as
easily have done the footer) for up/down/left/right and the javascript
to find those ids and simulate a click. I've tested this on
chrome (where accesskeys work with alt+ ) and firefox (where
accesskeys don't seem to work at all) and it works as expected in both
places. The javascript itself is rather naive, but serves as a starting
point for discussion.
This breaks the use of the arrow keys for scrolling. That doesn't seem
good.
On Fri, Jan 20, 2023 at 6:07 AM Peter Eisentraut <
peter.eisentraut@enterprisedb.com> wrote:
On 18.01.23 22:49, Corey Huinker wrote:
Attached is a patch to add the nav- tags to the header (could just as
easily have done the footer) for up/down/left/right and the javascript
to find those ids and simulate a click. I've tested this on
chrome (where accesskeys work with alt+ ) and firefox (where
accesskeys don't seem to work at all) and it works as expected in both
places. The javascript itself is rather naive, but serves as a starting
point for discussion.This breaks the use of the arrow keys for scrolling. That doesn't seem
good.
Fair enough. Most desktops overload the shift/cmd/alt combinations of arrow
keys, so there's not a lot of room to find an alternative.