This way screen reader users will hear the name of the file before
hearing about the link to destroy it. We were already displaying it this
way visually by having the file name on the left and the destroy link on
the right.
Thanks to this change we can also simplify the code which dynamically
changed the layout.
Using `dom_id` means generating `new_document` as ID for new documents.
Since there might be more than one new document in the form, that means
duplicate IDs, which is invalid HTML.
Even though this issue doesn't affect image fields (because we don't
have many images on the same form), we're removing the ID there as well
for consistency.
These labels weren't associated with any fields, which is invalid HTML.
We're using a legend inside a fieldset instead, which is the natural way
to group form fields together.
The imageable/documentable object is always the object the form builder
is based on; since we're already passing the form builder, we don't have
to pass the object as well.
The only exception are the poll answers. In this case, we're passing a
new answer as the object. That's OK; the same hack that we're using to
send the data to the answer URL without displaying existing attachments
causes the form to keep working the same way.
We were using long, unique names because these methods used to be helper
methods. Helper methods should have unique names because otherwise one
method would overwrite the other.
Now that we're using components, we can omit the `image_` and
`document_` prefixes.
So we don't add the same lines to pretty much every stylesheet we
create.
Eventually we'll remove this code and add a padding to every <main>
element, or (even better) to the <body> element itself.
We don't need any row classes anymore because the <body> already has a
maximum width. As for columns, we only have one column in this form, so
we don't need them either. Besides, the form's parent element already
has a padding.
Since now categories are loaded in both the investment form component
and proposal form component, and their controllers are the only
"commentable" controllers using the `@categories` instance variable, we
can remove the `load_categories` call in `CommentableActions` affecting
the create and update actions.
We don't need any row classes anymore because the <body> already has a
maximum width. As for columns, we only have one column in this form, so
we don't need them either. Besides, the form's parent element already
has a padding.
Although most CONSUL installation don't enable the translation
interface, we're adding some code to take this case into account.
These element had no columns inside and the row classes had only been
added to give them a maximum width. That's no longer necessary since now
the body has that maximum width.
As mentioned in commit 5214d89c8, using the `change` event of a `select`
field to automatically change location is really annoying for keyboard
users, since the event will trigger when pressing the down key to
navigate through the options or when typing a key to start searching for
an option. This might cause a lot of frustration.
Most multilanguage CONSUL sites enable between 2 and 4 languages. In
these cases, it's easier to just display the list of languages to
simplify the selection.
This way in this situation we also make it clear which languages are
available. If we use a `<select>` tag, users will have to open it in
order to check whether the site is available in their preferred
language.
This is also useful when the current language uses characters users
don't recognize; users will recognize their own language in the list of
available languages, while it might be harder to recognize the language
selector allows them to switch to a different language.
In this case, we're also hiding the label because a list of links with
language names is usually self explanatory for sighted users. We're
still providing it for screen reader users so they immediately know the
list allows them to change the language and if they don't need to do so
they can quickly skip it.
I'm not sure screen readers recognize this attribute inside `<option>`
tags, but if they do, it'll probably be helpful. And if they don't, no
harm will be done.
Note that in order to simplify the component tests (which for some
reason seem to be whitespace-sensitive), we have to omit whitespace
characters inside the `<option>` tags.
Also note we're simplifying the test with a missing language name; since
a component test doesn't involve a whole request, we don't need a
complex setup (I'm not sure we even need it in system tests).
Since we're simplifying the main method, we can use a view file instead
of the `call` method. This way we make the code more consistent with the
rest of our components, since we always use a separate file.
Doing so generates an extra newline at the end of the generated HTML, so
we need to change a couple of tests a little bit.
This way it's easier to refactor it and/or change it.
Back in commit c156621a4 I wrote:
> Generally speaking, I'm not a big fan of helpers, but there are
> methods which IMHO qualify as helpers when (...) many Rails helpers,
> like `tag`, follow these principles.
It's time to modify these criteria a little bit. In some situations,
it's great to have a helper method so it can be easily used in view
(like `link_to`). However, from the maintenance point of view, helper
methods are usually messy because extracting methods requires making
sure there isn't another helper method with that name.
So we can use the best part of these worlds and provide a helper so it
can be easily called from the view, but internally make that helper
render a component and enjoy the advantages associated with using an
isolated Ruby class.
As mentioned in commit 5214d89c8, using a `<select>` tag which
automatically submits a form on change has a few accessibility issues,
particularly for keyboard users who might accidentally submit the form
while browsing the options.
So we're adding a submit button and removing the "submit on change"
behavior.
Note that, while `<select>` tags have their own usability issues,
alternatives in this case are not obvious because the number of existing
polls could be very low (zero, for instance) or very high (dozens, if
the application has been used for years).
I thought of using a `<datalist>` tag with a regular text input. The
problem here is we don't want to send the name of the poll to the server
(as we would with a `<datalist>` tag); we want to send the ID of the
poll.
Maybe we could add an automplete field instead, providing a similar
funcionality. However, for now we're keeping it simple. This poll
questions page isn't even accessible through the admin menu since commit
83e8d603, so right now anything we change here will be pretty much
useless.
When we see a list of, let's say, banners, and each one has a link to
edit them, the word "banner" in the text "edit banner" is redundant and
adds noise; even for users with cognitive disabilities, it's obvious
that the "edit" link refers to the banner.
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.
