pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedAdding visual clues that accesskey exists
5+ messages / 2 participants
[nested] [flat]
* Adding visual clues that accesskey exists
@ 2023-01-13 22:07 Corey Huinker <corey.huinker@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: Corey Huinker @ 2023-01-13 22:07 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
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?
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Adding visual clues that accesskey exists
@ 2023-01-18 11:09 Peter Eisentraut <peter.eisentraut@enterprisedb.com>
parent: Corey Huinker <corey.huinker@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: Peter Eisentraut @ 2023-01-18 11:09 UTC (permalink / raw)
To: Corey Huinker <corey.huinker@gmail.com>; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Adding visual clues that accesskey exists
@ 2023-01-18 21:49 Corey Huinker <corey.huinker@gmail.com>
parent: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
0 siblings, 1 reply; 5+ messages in thread
From: Corey Huinker @ 2023-01-18 21:49 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; +Cc: pgsql-docs@lists.postgresql.org
>
> 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:
[text/x-patch] v1-0001-Add-javascript-to-enable-up-next-previous-navigat.patch (3.1K, ../../CADkLM=ezbE6tpSZ=0O-1jqA2qDiQSJ2JUfteDx7hSASXm0o0rg@mail.gmail.com/3-v1-0001-Add-javascript-to-enable-up-next-previous-navigat.patch)
download | inline diff:
From c9a3d11cb8402c08b256adbc7b9ea1a3d3e7ff93 Mon Sep 17 00:00:00 2001
From: coreyhuinker <corey.huinker@gmail.com>
Date: Wed, 18 Jan 2023 16:00:10 -0500
Subject: [PATCH v1] Add javascript to enable up/next/previous navigation via
arrow keys
---
doc/src/sgml/stylesheet-speedup-xhtml.xsl | 6 ++++++
doc/src/sgml/stylesheet.xsl | 8 ++++----
2 files changed, 10 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/stylesheet-speedup-xhtml.xsl b/doc/src/sgml/stylesheet-speedup-xhtml.xsl
index da0f2b5a97..d7e63ab38f 100644
--- a/doc/src/sgml/stylesheet-speedup-xhtml.xsl
+++ b/doc/src/sgml/stylesheet-speedup-xhtml.xsl
@@ -339,6 +339,12 @@
</xsl:if>
<xsl:call-template name="user.head.content"/>
+
+ <script>document.addEventListener("keydown", function(event) { event.preventDefault();
+ if (event.key == "ArrowLeft") { document.getElementById('nav-prev').click(); }
+ else if (event.key == "ArrowRight") { document.getElementById('nav-next').click(); }
+ else if (event.key == "ArrowUp") { document.getElementById('nav-up').click(); } });
+ </script>
</head>
</xsl:template>
diff --git a/doc/src/sgml/stylesheet.xsl b/doc/src/sgml/stylesheet.xsl
index b6141303ab..6fe3c51e18 100644
--- a/doc/src/sgml/stylesheet.xsl
+++ b/doc/src/sgml/stylesheet.xsl
@@ -72,7 +72,7 @@ Customization of header
<tr>
<td width="10%" align="{$direction.align.start}">
<xsl:if test="count($prev)>0">
- <a accesskey="p">
+ <a accesskey="p" id="nav-prev">
<xsl:attribute name="href">
<xsl:call-template name="href.target">
<xsl:with-param name="object" select="$prev"/>
@@ -91,7 +91,7 @@ Customization of header
<td width="10%" align="{$direction.align.start}">
<xsl:choose>
<xsl:when test="count($up)>0">
- <a accesskey="u">
+ <a accesskey="u" id="nav-up">
<xsl:attribute name="href">
<xsl:call-template name="href.target">
<xsl:with-param name="object" select="$up"/>
@@ -120,7 +120,7 @@ Customization of header
<td width="10%" align="{$direction.align.end}">
<xsl:choose>
<xsl:when test="$home != . or $nav.context = 'toc'">
- <a accesskey="h">
+ <a accesskey="h" id="nav-home">
<xsl:attribute name="href">
<xsl:call-template name="href.target">
<xsl:with-param name="object" select="$home"/>
@@ -143,7 +143,7 @@ Customization of header
<td width="10%" align="{$direction.align.end}">
<xsl:text> </xsl:text>
<xsl:if test="count($next)>0">
- <a accesskey="n">
+ <a accesskey="n" id="nav-next">
<xsl:attribute name="href">
<xsl:call-template name="href.target">
<xsl:with-param name="object" select="$next"/>
--
2.39.0
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Adding visual clues that accesskey exists
@ 2023-01-20 11:07 Peter Eisentraut <peter.eisentraut@enterprisedb.com>
parent: Corey Huinker <corey.huinker@gmail.com>
0 siblings, 1 reply; 5+ messages in thread
From: Peter Eisentraut @ 2023-01-20 11:07 UTC (permalink / raw)
To: Corey Huinker <corey.huinker@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Adding visual clues that accesskey exists
@ 2023-01-20 21:35 Corey Huinker <corey.huinker@gmail.com>
parent: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
0 siblings, 0 replies; 5+ messages in thread
From: Corey Huinker @ 2023-01-20 21:35 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; +Cc: pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2023-01-20 21:35 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-01-13 22:07 Adding visual clues that accesskey exists Corey Huinker <corey.huinker@gmail.com>
2023-01-18 11:09 ` Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-01-18 21:49 ` Corey Huinker <corey.huinker@gmail.com>
2023-01-20 11:07 ` Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-01-20 21:35 ` Corey Huinker <corey.huinker@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox