When render the investment list component with the link "see all
investments", now we redirect to groups index page when a budget has
multiple headings.
In general, slow system tests requiring no interaction from the user are
good candidates to be moved to component tests because component tests
are much faster.
In this case, the system tests were also updating the database after
starting the browser, which might cause concurrency issues. We could
split the test and have one system test per phase, but IMHO there's no
need.
We're still having a couple of system tests for the happy path, in order
to make sure users actually see the list of investments.
While we use Pronto to detect offenses in the lines changed in our pull
request, sometimes our changes introduce offenses in other lines, and we
don't detect them.
In commit 0488b3735, we removed the only usage of the `heading` method
in a test, which caused a `RSpec/LetSetup` offense.
In commit 287c48873, we changed some lines from `fill_in` to
`fill_in_ckeditor`. Some of these lines were aligned with the following
ones, which after that change had extra spacing for no reason.
Finally, in commit 8d38ed58c we added a line before two lines which had
their equals signs aligned. Since, after adding this line, the block was
no longer aligned, there was no reason for the extra space in one of the
lines.
Our previous system to delete cached attachments didn't work for
documents because the `custom_hash_data` is different for files created
from a file and files created from cached attachments.
When creating a document attachment, the name of the file is taken into
account to calculate the hash. Let's say the original file name is
"logo.pdf", and the generated hash is "123456". The cached attachment
will be "123456.pdf", so the generated hash using the cached attachment
will be something different, like "28af3". So the file that will be
removed will be "28af3.pdf", and not "123456.pdf", which will still be
present.
Furthermore, there are times where users choose a file and then they
close the browser or go to a different page. In those cases, we weren't
deleting the cached attachments either.
So we're adding a rake task to delete these files once a day. This way
we can simplify the logic we were using to destroy cached attachments.
Note there's related a bug in documents: when editing a record (for
example, a proposal), if the title of the document changes, its hash
changes, and so it will be impossible to generate a link to that
document. Changing the way this hash is generated is not an option
because it would break links to existing files. We'll try to fix it when
moving to Active Storage.
We introduced a bug in commit acbd1b023.
When editing a record and removing an existing image, we don't remove
the HTML fields associated with that image but simply hide them, and
then we add fields to create a new image when clicking on "Add image".
This is standard cocoon behavior. However, since in the case of images
there's a `has_one` relation, cocoon doesn't add unique identifiers to
the new fields, generating duplicate IDs, which is invalid HTML.
Since there's a duplicate file input ID, clicking on the "Choose image"
label we aren't clicking on the new input but on the old one. This means
we aren't correctly attaching an image. The tests passed because
Capybara uses the equivalent of a keyboard to select the field, and in
this case everything worked properly.
So we need to delete the existing elements before inserting new ones.
We're adding a test to check there aren't duplicate IDs.
We were hiding the file input and styling the label as a button instead.
Since clicking on a label has the same effect as clicking on the input,
the input worked properly for mouse and touch screen users.
However, hiding the input makes it inaccessible for keyboard users,
since labels don't get keyboard focus, but inputs do.
So we must not hide the input but make it invisible instead. But we
still need to hide the input (alongside the label) after a file has been
attached.
We could add some extra JavaScript to hide the input when we hide the
label. Since the JavaScript is already quite complex and my first few
attempts at changing it failed, I've opted to assume that the input (and
its label) must be hidden whenever there's already a file name, and
implement that rule with CSS.
Note we're using the `:focus-within` pseudoclass to style a label when
focus is on the input. This rule (at the time of writing) is only
supported by 93.5% of the browsers. Keyboard users without a screen
reader and using the other 6.5% of the browsers will still be able to
focus on the field but might not notice the field has received focus.
Since the percentage of affected users will decrease over time and until
now 100% of keyboard users were completely unable to focus on these
fields, for now we think this is a good-enough solution.
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.
Instead of adding the padding to each individual element inside the
container, why not adding padding to the container itself? The answer is
"because we want the background of the children elements to take the
width of the whole screen". But this generates either HTML cluttered
with elements to add padding or repetitive padding definitions in the
CSS.
So now we only define the padding once, and when an element requires a
full width background or border, we use the `full-width-background`
mixin.
In this case the code is a bit more complex because the header is also
used in the dashboard and admin layouts:
* In the public layout, the body has a margin, so we include the mixin
to take margin into account
* In the dashboard layout, the header itself has a margin, so we include
the same mixin
* In the admin layout, the headet doesn't have a margin but gets the
whole width, so in this case we include the mixin which dosen't take
the margin into account
In the future, the idea is to apply this principle to the <body>
element and remove the `@include grid-column-gutter` in the CSS as well
as the `small-12 column` classes in the HTML.
Note we use the `calc()` function inside the mixin instead of using it
in the `$full-width-margin` variable. That way we avoid nested `calc()`
operations, which don't work in Internet Explorer.
Also note we're using `flex-grow: 1` to make one element appear on the
left of the screen and the other one on the right. It would be easier to
use `justify-content: space-between` (which is actually the default for
the top-bar element). However, there's a bug in Internet Explorer and
old versions of Firefox; they include the absolutely-positioned
`::before` element we use to set the full width background when
calculating where to position the elements. The bug was fixed in Firefox
52 (released in 2017).
Finally, we're removing the padding from our logo. In order to allow
logos like the new one and at the same time provide backwards
compatibility to logos in existing CONSUL installations, we're relaxing
the validation rule for the logo width.
Using `flex` instead of a fixed width for the navigation, the elements
take all the available space when the search form isn't present. That
wasn't the case before and produced a strange effect on medium-sized
screens.
This way we also align the search to the right.
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.
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.
We were defining campaigns with `let`. That meant they weren't created
until these methods were used in the tests.
For the test "Do not track erroneous track_ids", that meant the line
`expect(page).not_to have_content campaign2.name.to_s` wasn't really
testing anything, since before this line is executed, the campaign2
wasn't in the database at all, and so obviously its name wouldn't be on
the stats page.
For the test "Track email templates", it meant we were creating the
campaign2 record after visiting the campaign1 page with the browser.
Creating records in the tests after starting the browser might be the
reason why this test has recenty failed in our CI [1]:
1) Email campaigns Track email templates
Failure/Error: ds.add params[:event].titleize, Ahoy::Event.where(
name: params[:event]).group_by_day(:time).count
ActiveRecord::StatementInvalid:
PG::ProtocolViolation: ERROR: bind message supplies 0
parameters, but prepared statement "" requires 1
# ./app/controllers/admin/api/stats_controller.rb:13:in `show'
Using `let!` to create the campaings before the browser starts improves
the situation.
[1] https://github.com/consul/consul/runs/2952333023
The word "budget" in the "Preview budget" link is redundant.
On the other hand, the words "Manage", Edit" and "Admin" are not
really necessary in my humble opinion. Just like in the admin
navigation menu we use "Participatory budgets" instead of "Manage
Participatory budgets", the fact that we're going to manage or
admin or edit something can be deduced from the fact that we're in
the admin section.
Besides, it isn't clear to me why we use "Manage" for projects,
"Edit" for heading groups and "Admin" for ballots. The differences
between these three concepts might be too subtle for me.
The previous paragraphs haven't been corroborated with real users,
though, so I might be mistaken and we might need to revisit these
links in the future.
These actions still take quite a lot of space. Maybe in the future we
could remove the "delete" icon, at least on budgets which cannot be
deleted.
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.
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.
