Version 2.2.x seems to cause some issues with Ruby 2.6, as mentioned in
the comments of issue 146 in the sassc-ruby repository.
Due to these issues, our test suite was failing sometimes when running
on GitHub Actions.
Using GitHub Actions has a few advantages over using Travis CI:
* More jobs can be run in parallel
* All CONSUL repositories on GitHub will be configured automatically
Besides, Travis have recently changed their policy twice. First, they
announced their site for free software projects would be shut down but
free software projects could still use their site for private projects.
And then, they limited the usage of their services for free software
projects.
Just like we used to do with Travis, we're enabling builds for pull
requests but not for pushed branches.
We're also building the master branch. Even if we never push to the
master branch directly, we're aware other CONSUL repositories do, so
we're running the tests for this case.
Combining the max-width and the white-space property resulted in the
text exceeding its bounds if the text was longer than what the max-width
property allowed.
The `width: max-content` property, on the other hand, is compatible with
the max-width property.
Originally we were using Foundation's sticky, which wasn't entirely
compatible with our way to open/close the Table of Contents because its
width would not automatically be updated when the TOC was opened/closed
but when users scrolled the page.
Using CSS, which is now supported in most browsers, simplifies the
matter. On browsers like Internet Explorer, where it's not supported,
the content will not stick but other than that it'll work fine.
We're also adding `scroll: auto` so when the TOC's height will be large
than the page, it'll be possible to scroll it, which users couldn't do
in the original version.
Now that comments and TOC can be closed at the same time, we use a flex
layout so the main content uses the available width.
We're also making the comments work better on medium-sized screens,
since previously they had a fixed width and now the width is adapted to
the size of the screen.
Since now the comment box element has a relative position instead of an
absolute one, we need to consider the draft panel height when
calculating the comment box position.
We were using JavaScript to show/hide the Table of Contents.
In my humble opinion, the <details> tag has a few shortcomings [1][2],
which means we should be careful about when to use it.
IMHO a Table of Contents is a good candidate for this tag because it's a
very common pattern to add a show/hide behavior for it, even if using it
means the "navigation" role (which we are *not* using anyway) wouldn't
be identified correctly.
I'm adding a <details> tag to the comments section as well for
consistency and in order to simplify the code. I'm not sure this is as
good an application of the <details> tag, though, but then again I'm not
sure about the interface we use to show/hide the comments (and this
feeling is increased by the fact that we use a different interface on
small screens). If we decide to change the interface in the future, we
might consider using the <details> tag for the Table of Contents but not
for the comments.
Since the <details> tag is not supported on Internet Explorer, I'm
only adding styles to this tag using the `:not([open])` option. On
Internet Explorer <details> will always be opened and so these styles
will be ignored.
[1] https://adrianroselli.com/2019/04/details-summary-are-not-insert-control-here.html
[2] https://daverupert.com/2019/12/why-details-is-not-an-accordion/
In commit a8537f7e1 we added a `height: 100%` rule on links inside
cards, which is great for cards in the "Featured" section of the
homepage. However, the card in the "Open processes" section of the
homepage has as many links inside as open processes, causing its height
to be 300% if there are three processes and so expanding below the
footer.
The planned budget investments redesign includes using icons in some
tables, so we might as well use them everywhere.
The original design used Foundation to show the tooltips. We're using
CSS in order to keep the ERB/HTML code simple. One advantage of using
CSS is we can show the tooltip on focus as well, just like accessibility
guidelines recommend [1]. On the other hand, Foundation tooltips appear
on the sides when the link is at the bottom of the page, making sure
they're visible in this case, while CSS tooltips do not. Neither CSS
tooltips nor Foundation tooltips are dismissable, which might be an
accessibility issue.
Note we aren't changing any ERB files in order to replace links with
icons; we're only changing CSS and one line of Ruby code.
[1] https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus
Note the CSS could probably be improved to avoid duplication with other
button style definitions. However, that's fine because we're going to
change the style of the links soon.
For the same reason, I haven't bothered to style every single link the
way it was until now.
In some tables, we had "actions", and some columns were also links
pointing to some places. Having both of them at the same time is
confusing, particularly since traditionally the links in the columns
pointed to the same place as some of the actions (although that's not
the case since commit 48db31cd).
We're still keeping links in tables which don't have an action column.
For instance, the proposals table has a "select" button which would be
harder to use if we had action buttons next to it.
By using real XML responses developers will be able to understand better
how the integration works (the data flow), and the correspondency between
`remote_census` settings and their place at a real XML response.
As `stubbed_responses` methods were removed from the model layer now the
stubbing part should be managed from the test environment code so also
added a new helper module `RemoteCensusSetup` that can be used anywhere
where we need to call the web service.
Co-Authored-By: Javi Martín <javim@elretirao.net>
Since the interface to select this date uses the classic multi-field
interface for day, month and year, we're transforming it into a date in
the Office::Residence initializer.
However, the factory to build an office residence does not assign the
paremeters in the initializer but using the `date_of_birth=` method, so
when doing so we need to use a date instead of a string.
By simplyfing the responses the configuration for specs can be simpler too.
We're also using more generic terms instead of the ones used in Madrid's
Census API.
Co-Authored-By: Javi Martín <javim@elretirao.net>
Otherwise the variants returned for document_type="1" and
document_number="" will be
`["0", "00", "000", "0000", "00000", "000000", "0000000", "00000000"]`
which seems to be useless.
Probably this case is not real for production environments where those
arguments will always be fullfilled but seems to be interesting for
testing environment where this method is being called when those
paremeters where empty.
Ruby 2.6 introduces `Enumerable#filter` as an alias to
`Enumerable#select`, and so our Filterable.filter method will not work
with Ruby 2.6.
So we're renaming the method to `filter_by`, which is similar to
`find_by`. We could also change the `filter` method so if a block is
given it delegates to `Enumerable#filter`, the same way ActiveRecord
handles the `select` method, but IMHO this is easier to follow.
Now we can use the checkbox label text directly as locator at spec,
also default web_sections are created before every spec by loading
`db/seeds.rb` file so we were duplicating "Proposals" WebSection.
We were allowing users to check/uncheck the "Visible to valuators"
checkbox even when the budget is finished and so the investments cannot
be edited. So users were still able to check/uncheck this attribute, but
the server was silently rejecting these changes.
We've considered removing the column in this case but decided to keep it
since users can already control which columns they'd like to display.
We added the background role to the production and preproduction
environments in commit d0b0782c4, but forgot to add it to the staging
environment as well.
There are a dozen ways to add an icon used for decoration. Each of them
offers advantages and disadvantages regarding these topics:
* Accessibility
* Ease of use for developers
* Ease of customization for CONSUL installations
* Maintainability
* Resulting file size
* Number of HTTP requests
* Browser support
* Robustness
We were using one of the most common ones: icon fonts. This technique
shines in many of these aspects. However, it misses the most important
one: accessibility. Users who configure their browser to display a
custom font would see "missing character" icons where our icons should
be displayed. Some users have pointed out they use a custom font because
they're dyslexic and webs using icon fonts make it extremely painful for
them [1].
Screen reader users might also be affected, since screen readers might
try to read the UTF-8 character used by the icon (even if it uses a UTF
Private Use Area) and will react to it in inconsistent ways. Since right
now browser support for different techniques to prevent it with CSS
ranges from non-existant (CSS speech module) to limited (use an
alternative text in the `content` property [2]), we've been adding an
HTML element with an `aria-hidden` attribute. However, by doing so the
ease of customizations for CONSUL installations is reduced, since
customizing ERB files is harder than customizing CSS.
Finally, font icons are infamous for not being that robust and
conflicting with UTF settings in certain browsers/devices. Recently Font
Awesome had a bug [3] because they added icons out of the Private Use
Area, and those icons could conflict with other UTF characters.
So, instead of loading Font Awesome icons with a font, we can add them
using their SVG files. There are several ways to do so, and all of them
solve the accessibility and robustness issues we've mentioned, so that
point won't be mentioned from now on.
All these techniques imply having to manually download Font Awesome
icons every time we upgrade Font Awesome, since the `font-awesome-sass`
gem doesn't include the `sprites/` and `svgs/` folders Font Awesome
includes in every release. So, from the maintenance poing of view,
they're all pretty lacking.
Method 1: SVG sprites with inline HTML
We can use SVG files where template icons are defined, like so:
<svg>
<use xlink:href="solid.svg#search"></use>
</svg>
This technique has great browser support and it only generates one HTTP
request for all icons. However, it requires adding <svg> tags in many
views, making it harder to customize for CONSUL installations. For
developers we could reduce the burden by adding a helper for these
icons.
Downloading all the icons just to use one (or a few) might also be
inconvenient, since the total file size of these icons will be up to a
megabyte. To reduce the impact of this issue, we could either minimize
the SVG file, compress it, or generate a file with just the icons we
use. However, generating that custom file would be harder to maintain.
Method 2: CSS with one SVG icon per file
We can use the separate SVG files provided by Font Awesome, like so:
background: url("solid/search.svg");
Or, if we want to add a color to the icon:
backgound: blue;
mask-image: url("solid/search.svg");
Using this technique will result in one HTTP request per icon, which
might affect performance. Browser support is also limited to browsers
supporting mask-image, which at the time of writing is 95% of the
browsers, with the notable exception of Internet Explorer 11.
On the plus side, using CSS makes it easy to customize and (IMHO) easy
to work with on a daily basis.
Method 3: CSS with SVG sprites
We can use the aforementioned sprites provided by Font Awesome and use
them with CSS:
backgound: blue;
mask-image: url("solid.svg#search");
The number of HTTP requests and file size are similar to Method 1, while
browser support, ease of customization and ease of use are similar to
Method 2.
There's one extra gotcha: this method requires doing minor changes to
the files provided by Font Awesome, which means this solution is harder
to maintain, since we'll have to do the same changes every time we
upgrade Font Awesome. Mainly we need to add these changes to every
sprite file:
- <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+<!--
+This is a modified version of Font Awesome Free regular sprite file.
The icons are exactly as they originally were; the only changes are:
+
+* <symbol> tags have been replaced with <svg> tags and a <style> tag
has been added
+* A <style> tag has been added
+* The style="display:none" attribute of the main <svg> tag has been
removed
+-->
+<svg xmlns="http://www.w3.org/2000/svg">
+ <style>
+ svg svg { display: none }
+ svg svg:target { display: inline }
+ </style>
And then replace every <symbol> tag with a <svg> tag.
Method 4: CSS with Data URI
Finally, we can write the icons directly in the CSS:
backgound: blue;
mask-image: url('data:image/svg+xml;utf8,<svg...');
This method does not generate any extra HTTP requests and only downloads
the icons we need. However, maintaining it is really hard, since we need
to manually copy all the <svg> code for every icon we use, and do it
again every time we upgrade Font Awesome.
In this commit, we implement Method 2. To improve browser support, we're
falling back to font icons on browsers which don't support mask images.
So 5% of the browsers might still conflict with users changing the fonts
or with screen readers trying to announce the icon character. We believe
this is acceptable; the other option for these browsers would be to show
those icons as a background image, meaning the icons would always be
black, meaning users of these browsers would have trouble to distinguish
them if the background was dark as well.
Since we aren't sure whether the performance hit of having one HTTP
request per icon is overcome by only requesting the icons we actually
use, we aren't taking this factor into account when choosing between
methods 2 and 3. We believe this method will be the less painful one to
maintain and customize. Generating SVG sprites with just the icons we
use would increase performance, but it would make it harder for existing
CONSUL installations to use icons we haven't included in the sprites.
[1] https://speakerdeck.com/ninjanails/death-to-icon-fonts
[2] https://developer.mozilla.org/en-US/docs/Web/CSS/content#Browser_compatibility
[3] https://blog.fontawesome.com/fixing-a-unicode-bug-in-5-14-0/
We were using `display: inline` assuming that's the way elements will be
displayed by default when shown. However, those elements could be
displayed in a different way (inline-flex, for instance). So we avoid
any possible conflicts by using the `display: none` rule when we want to
hide the elements.
Besides, the code is now symmetrical and IMHO easier to follow.
Even if "r" is shorter, "regular" is easier to understand, and we're
going to store these icons in a folder named "regular", which is the
convention Font Awesome uses.
