In commit 9794ffbbf, we replaced "buttons" with icons in order to make
the admin interface consistent with the planned budget investments
redesign.
However, using icons has some issues. For once, icons like a trash for
the "delete" action might be obvious, but other icons like "confirm
moderation" or "send pending" might be a bit confusing.
It's true that we were adding tooltips on hover. We tried two
approaches: using Foundation's tooltips and using CSS tooltips.
Foundation tooltips are not activated on focus (only on hover), while
CSS tooltips always appear below the icon, which might be a problem when
the icons are at the bottom of the screen (one of our milestone tests
was failing because of that and we can now run it with JavaScript
enabled).
Both Foundation and CSS tooltips have other issues:
* They force users to make an extra step and move the mouse over the
link just to know what the link is about
* They aren't available on touch screens, so these users will have to
memorize what each icon does
* They are not hoverable, and making them hoverable would cause a
different issue because the tooltip might cover links below it, making
it impossible to click these links without moving the mouse away
first
* They are not dismissable, which is considered an accessibility issue
and a requirement in the Web Content Accessibility Guidelines [1]
For all these reasons, we're using both texts and icons. As Thomas
Byttebier said "The best icon is a text label [2]". Heydon Pickering
also makes a point towards providing text alongside icons in his book
"Inclusive Components" [3].
Note that, since we're now adding text and some of the colors we use for
actions are hard to read against a white/gray background, we're making a
few colors darker.
With these changes, actions take more space in the admin table compared
to the space they took in version 1.3, but they are more usable and
accessible while they still take less space than they did in version
1.2.
[1] https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus
[2] https://thomasbyttebier.be/blog/the-best-icon-is-a-text-label
[3] https://inclusive-components.design/tooltips-toggletips/
As mentioned in commit 5214d89c8, there are several issues with
submitting a form when a `<select>` tag changes. In particular, keyboard
users might accidentally fire the event while browsing the options, and
screen reader users will find a form with no obvious way to submit it.
In this case, there's an extra problem: in commit be8a0dbe8 we added a
second `<select>` field to this form, which also submitted on change.
Sometimes users changed one of the values and wanted to change the other
value as well before submitting the form. However, it wasn't possible,
because we would submit it before they had a chance to change the second
value.
So now we don't submit the form on change and add a submit button. This
is similar to what we do in the "Advanced filters" we use in several
places.
Since forms are landmarks, screen reader users might navigate to the
form. But then they were going to find an empty form with no way to
toggle it.
Moving the button inside the form means screen reader users navigating
to the form will find the button to toggle it.
It also helps us simplifying the code; there's no need to use
data-attributes to communicate whether the form should be visible since
now we can easily use the button `aria-expanded` attribute.
We could further simplify the JavaScript if we used a CSS rule to
show/hide the form fields based on the toggle button `aria-expanded`
attribute. However, implementing the "slide" animation we use when
toggling the form with CSS is difficult and unreliable.
We were using the form and then showing it with JavaScript when advanced
search terms were present. Now we hide it with JavaScript when no
advanced search are present. This means users without JavaScript
(including users with JavaScript enabled but bad internet connections
preventing the JavaScript to load) can now access the form.
The other main difference between the two versions is the way the form
flashes while JavaScript is loading.
Previously, the form would always be hidden when no terms had been
introduced. However, when these terms were present, after submitting the
form it would briefly be hidden and then shown again.
Now the opposite happens. When advanced search terms are present, the
form is shown at all times. However, when they aren't, the form is
briefly shown before it disappears.
Here the previous behavior is arguably better because most of the time
these terms will not be present.
So basically we're significantly improving the experience of some users
at the cost of slightly worsen the experience of other users.
We're also hiding the button to show the form when JavaScript is
disabled, since in this scenario it's useless. We're using the `hidden`
attribute so hidden buttons can be detected in CSS.
Users (particularly, screen reader users) usually identify links with
things that take you somewhere, and buttons with things that either send
forms or change things on the page.
Using a button we can also use the `aria-expanded` attribute, meaning
screen reader users will know that the button has two states ("expanded"
and "collapsed"), the current state of the button, and will get
immediate feedback when clicking the button because the new state of the
button will be announced.
Thanks to this change, we can also slightly simplify the code; we
obviously have to remove the (useless) `href` attribute, and we don't
have to prevent the default event in JavaScript since there's no default
event for buttons with `type="button"`.
Add link_url presence validation only when link_text is provided only for header cards.
In this case it makes sense to allow creating a "header card" without link_url, since
we can show the header without link text and without link url and it still does its
function.
Currently it is not necessary to include the link_url field.
When we display these cards without link_url, they create an empty link that
redirects to the same page. I understand that this is not a desired behavior, so I
think it is better to add a validation in this case and force administrators to add a
link_url when creating a card.
As mentioned in the previous commits, a `<select>` field which submits
its form on change causes many accessibility and usability issues, so
we're replacing it with the order links we use everywhere else.
Since the links "Id" and "Title" by themselves don't have enough
information to let users know they're used to sort by ID or title, we
have to update them somehow. We could add a "Sort by:" prefix before the
list of links (and associate it with the `aria-labelledby` attribute);
however, we don't do this anywhere else and might look weird depending
on the screen size.
So we're simply adding "Sort by" before each link.
Now that we don't use the `wide_order_selector` partial anymore, we can
remove it alongside the styles for the `select-order` class.
A `<select>` tag here might make more sense than in other similar places
since there are 5 options to choose among, and using links might take
too much screen space.
However, as mentioned in the previous commits, `<select>` tags which
automatically submit a form have many accessibility and usability
issues.
An alternative would be to create a dropdown menu with a button and a
list of links (similar to what Foundation does). I'm keeping the links
for simplicity and because the interface looks a bit more consistent
with the rest of the sections. Before these changes, we had a heading,
then a `<select>` field to choose the filter, and then a button to print
the page. We never use a similar interface, and some people might think
the "Print" button is related to the same form as the `<select>` field.
Now that we don't use the `order_selector` partial anywhere anymore, we
can remove it.
Using order links in this case causes an unusual interface, where we
show filter links, then information about the number of results, and
then order links.
Whether or not this makes sense needs to be confirmed with usability
tests. In any case, this is still way better than using `<select>`
fields which automatically change to a new page, since they cause
problems to keyboard users, are harder to select for touchscreen users,
might confuse screen reader users who will notice a form but no way to
submit it, and are not elements we generally use to let users choose the
order of the records.
For a more detailed explanation of these issues, check the commit
message in the commit "Use order links to sort comments and topics"
(just a few commits ago).
It was a bit frustrating to click on one of the order elements or the
link to the next page and having to scroll down again until reaching the
comments.
We use order links in many places in the web. However, in the comments
section and the list of community topics, we were displaying a
`<select>` element, and changing the location when users select an
option.
This has several disadvantages.
First, and most important, it's terrible for keyboard users. `<select>`
fields allow using the arrow keys to navigate through their options, and
typing a letter will select the first option starting with that letter.
This will trigger the "change" event and so users will navigate through
a new page while they were probably just checking the available options
[1]. For these reasons, WCAG Success Criterion 3.2.2 [2] states:
> Changing the setting of any user interface component does not
> automatically cause a change of context unless the user has been
> advised of the behavior before using the component.
Second, the form didn't have a submit button. This might confuse screen
reader users, who might not know how that form is supposed to be
submitted.
Finally, dropdowns have usability issues of their own [3], particularly
on mobile phones [4]
The easiest solution is to use the same links we generally use to allow
users select an order, so using them here we make the user experience
more consistent. They offer one disadvantage, though; on small screens
and certain languages, these links might take too much space and not
look that great. This issue affects pretty much every place where we use
order or filter links, so we might revisit it in the future.
Note we're moving the links to order comments after the form to add a
new comment. In my opinion, having an element such as a form to add a
new comment between the element to select the desired order of the
comments and the comments themselves is a bit confusing.
[1] https://webaim.org/techniques/forms/controls#javascript
[2] https://www.w3.org/WAI/WCAG21/Understanding/on-input.html
[3] https://www.youtube.com/watch?v=CUkMCQR4TpY
[4] https://www.lukew.com/ff/entry.asp?1950
It looks like this bug was introduced in commit 7ca55c4. Before that
commit, a message saying "You added a new related content" was shown,
but (as expected) the related content wasn't added twice.
We now check this case and add a slightly clearer message.
We've had an accessibility error reported by the Spanish "Portal
Administración electrónica" (PAe). While I can't find any accessibility
rule saying empty lists should be avoided, it looks like some screen
readers report finding lists with 0 items, which is annoying.
We've had an accessibility error reported by the Spanish "Portal
Administración electrónica" (PAe). While I can't find any accessibility
rule saying empty lists should be avoided, it looks like some screen
readers report finding lists with 0 items, which is annoying.
We could also do it with CSS using `ul:empty { display: none}`. However,
at the time of writing no browser supports this rule when the tag
contains whitespace.
Some CONSUL installations might want to customize their URLs. For
instance, Spanish institutions might want to use "/propuestas" instead
of "/proposals". In that case, it would be impossible to add proposals
as related content because the related contents controller assumed the
name of the model was part of the URL.
Using `recognize_path` instead of manually analyzing the URL solves the
issue.
Now that we don't call the `constantize` method on an empty string as we
previously did, we can be more specific in the `rescue` block and point
out that the only exception we expect is the one where users enter a
route which isn't recognized.
Although it wasn't a real security concern because we were only calling
a `find_by` method based on the user input, it's a good practice to
avoid using constants based on user parameters.
Since we don't use the `find_by` method anymore but we still need to
check the associated record exists, we're changing the validations in
the `RelatedContent` model to do exactly that.
We were manually checking validation rules (like both relationable
objects are present, or they're both the same object) in the controller
and then using the `save!` method.
However, we usually use the `save` method (which checks all validations)
in a condition, and proceed depending on the result.
Now we're taking the same approach here. This means introducing a new
validation rule in the model to check whether both relationable objects
are the same, which is more robust than checking a condition in the
controller.
We were only showing these actions to users with small screens and to
mouse users on hover. Keyboard users or users with a touch screen of a
medium or large size could never find out the actions were there.
It didn't have a `for` attribute and so it wasn't correctly associated
with its input. That means clicking on / touching the label didn't have
the effect of focusing on the field, and screen readers wouldn't
announce the label.
The button was announced as expanded when the form was hidden and as
collapsed when the form was shown.
This is because Foundation sets the expanded attribute based on whether
the class to toggle already exists. Since initially the form had the
"hide" class and the button toggled that class, Foundation checked that
the class was already present and so set the button as expanded.
So we're changing the toggler class for a class we don't use at all,
just so Foundation initiall sets `aria-expanded=false` and then changes
it to `aria-expanded=true` after the button is clicked. Then we're
ignoring this class completely and are styling this form with CSS
instead.
We could also use a toggler class like "visible" and write something
like:
```
.add-related-content + form:not(.visible) {
display: none;
}
```
However, using ARIA attributes is more robust as it guarantees the
styles will always be in sync with what screen reader users experience.
And we could also remove all the Foundation toggler functionality and
use our own JavaScript to handle the button state. We might do so in the
future.
We're removing the parenthesis after page expectations (as we do almost
everywhere) and we're replacing `have_selector` with `have_css`, since
on that file we were using `have_css` everywhere except in one place.
Using placeholders having similar (or identical) text as already present
as a label has a few issues.
First, it's a distraction. Reading the same information twice is
useless, requires an extra effort, and might even frustrate users.
Second, if users start typing before reading the placeholder and see it
disappear, they might think they're missing relevant information,
delete what they typed, and read the placeholder. That will get them
nowhere.
Finally, we display placeholders using a text offering very low contrast
against the background, so users don't think the placeholder is an
actual value entered in the field. Using such low contrast makes the
text hard to read, particularly for users with visual impairments.
So we're removing these placeholders.
This commit only deals with placeholder texts with similar (or
identical) texts as the label text. There might be other places where we
should replace placeholder texts with labels, but that's a different
topic.
A button cannot be inside an anchor tag, and it might confuse some
browsers or screen readers.
We're also making it clear in the tests that the intention is to use a
button there by using `click_button` instead of `click_on` since the
latter also clicks on links.
This test will fail if the ID of the created record is the same as the
ID of the first user we create in the test. The chance is very low due
to the `rand(9999999)` which causes the test to fail just once every ten
million times. However, why assigning the ID in the first place? Without
it, the test will never fail due to conflicting IDs.
The test "updates officer_assignment_id_log if amount changes" failed
when the ID we assigned when creating the records was the same as the ID
of the first officer assignment created during that test. It's recently
happened while running our test suite [1] with the following error:
```
1) Poll::Recount logging changes updates officer_assignment_id_log if
amount changes
Failure/Error: poll_recount.officer_assignment =
create(:poll_officer_assignment, id: 101)
ActiveRecord::RecordNotUnique:
PG::UniqueViolation: ERROR: duplicate key value violates unique
constraint "poll_officer_assignments_pkey"
DETAIL: Key (id)=(101) already exists.
```
We're also removing the IDs in the "updates officer_assignment_id_log if
amount changes" test to avoid any possible issues, even if in this test
I think no other officer assignments are created and so there can't be
another record with the same ID.
[1] https://github.com/consul/consul/runs/2818889296
When administrators disabled features and users tried to access them
with the browser, we were responding with a 500 "Internal Server Error"
page, which in my humble opinion was incorrect. There was no error at
all; the server worked exactly as expected.
I think a 403 "Forbidden" code is better; since that feature is
disabled, we're refusing to let users access it.
We could also respond with a 404 "Not found", although I wonder whether
that'll be confusing when administrators temporarily or accidentally
disable a feature.
A similar thing might happen if we responded with a 410 "Gone" code.
Actually this case might be more confusing since users aren't that
familiar with this code.
In any case, all these options are better than the 500 error.
Note we don't cast negative votes when users remove their support. That
way we provide compatibility for institutions who have implemented real
negative votes (in case there are / will be any), and we also keep the
database meaningful: it's not that users downvoted something; they
simply removed their upvote.
Co-Authored-By: Javi Martín <javim@elretirao.net>
Co-Authored-By: Julian Nicolas Herrero <microweb10@gmail.com>
Since we're going to add an action to remove supports, having a separate
controller makes things easier.
Note there was a strange piece of code which assumed users were not
verified if they couldn't vote investments. Now the code is also
strange, since it assumes users are not verified if they can't create
votes. We might need to revisit these conditions if our logic changes in
the future.
It was hard to notice what was going on when supporting one investment
which was at the bottom of the investment index page.
I wonder whether we should add the title of the investment to this text;
I'm not doing so because we don't do that anywhere else.
If I'm right, the `investment_votes` instance variable only exists to
avoid several database queries to get whether the current user has
supported each of the investments.
However, that doesn't make much sense when only one investment is shown.
In this case, the number of queries stays the same, and so we can
simplify the code by rendering the component with an optional parameter.
Using links combined with JavaScript to generate POST requests to the
browser has a few issues.
An obvious one is that it doesn't work for users without JavaScript
enabled (which lately I've noticed are more common than I thought, even
though I've been one of them for years). These users will reach a 404
page.
Since CONSUL isn't currently designed to work without JavaScript
enabled, let's ignore this one for now.
A not so obvious issue is screen reader users might expect the link to
take them somewhere instead of performing an action (in this case,
sending a form to the server).
There might be more issues I'm unaware of. Quoting DHH [1]:
"Turning ahrefs into POSTs is a bit of an anti-pattern, especially for
a11y reasons. Better to use button_to with a styling."
So we're using a button instead. This way we can also simplify the code
and make the button disabled for unidentified users, which automatically
makes it impossible to focus it using the keyboard.
A possible disadvantage of using `button_to` is it will create a form
tag which will be announced to screen readers as a form landmark. I've
tested it with my screen reader and everything worked fine for me, but
some screen reader users might interact with these forms in a different
way and find it confusing, particularly in the case where the button is
disabled.
With this change, we're only changing links for buttons in one place.
There are other places where we should do similar changes.
[1] See issue 33 in https://github.com/hotwired/turbo-rails/
We meant to check that the link to support a different investment didn't
have an alert dialog. However, we were testing by trying to support the
same investment twice, and here there was no link at all, so the
assertion "there's no link with a dialog" always passed even when the
application didn't behave properly.
Now we check there's a link there, and that link doesn't have an
associated alert dialog.
In regular system tests, we prefer testing against the text of the link
because it's easier to recognize which link we're talking about.
I was wondering whether we should remove the `title` attribute
completely and use just the `aria-label` attribute. Quoting The Paciello
Group blog [1]:
"If you want to hide content from mobile and tablet users as well as
assistive tech users and keyboard only users, use the title attribute."
However, there's a case where mouse users might find the title attribute
useful. When visiting an investment page, the connection between the
"Support" link and the investment is not as clear as it is in the
investments index page, so it might not be clear what you're supporting.
As mentioned, though, this information will only be relevant for mouse
users, who nowadays represent less than half of our users.
[1] https://www.tpgi.com/using-the-html-title-attribute-updated/
This way blind screen reader users will know which project they're
supporting. In a list of investments, context might not be clear when a
link saying "Support" or "Support this project" is announced, but a link
saying "Support Renovate sidewalks in Main Street" is less ambiguous.
When identified users accessed the investments page, we were using the
`aria-hidden` attribute to hide this link from screen readers since
unidentified users can't support investments.
However, the link was still focusable using keyboard navigation. This
resulted in screen reader users reaching the link and being able to
click it, but getting no feedback at all about where they were or what
they were clicking on.
This is why the fourth ARIA rule says: "Do not use role="presentation" or
aria-hidden="true" on a focusable element" [1].
So we're replacing the link with a non-interactive element instead, like
we do in other places like proposals.
The accessibility of this part of the page for unidentified users still
has some issues; here we're only improving it up to a certain point.
[1] https://www.w3.org/TR/using-aria/#4thrule
The `js-` prefix (which I admit I'm not fond of) is usually used to
indicate the class is used by JavaScript files, not for using it in test
files. And in all the other similar tests, we're using the `in-favor`
class instead of the `js-in-favor` class.
This reverts commit 83fe74d53.
When supporting an investment in the management section through the
investment view, we were accessing an action in the public investments
controller. This meant the manager was the one supporting the investment
(as they'd be the `current_user` in this controller) and not the managed
user.
In the case of groups with many headings, voting the first time requires
a confirmation and then a regular (non-AJAX) request takes place. In
this case, users were redirected to the public area instead of remaining
in the management area.
Using the proper URL to vote solves the problem.
Note there was a comment about one of these tests failing in Travis.
Most probably the test failed because there was no expectation after
clicking the link with the investment title, so the "Support" button
(which is also present in the index page) was clicked before the
investment view was loaded.
