In general, we don't use links inside admin tables because we don't know
where the link will point to, and use "view" actions/links instead.
However, in this case, we're showing a URL, so it's perfectly obvious
where the link will point to. And so it makes sense to use the URL as a
link instead of using a "view" action/link.
Some institutions using CONSUL have expressed interest in this feature
since some of their tenants might already have their own domains.
We've considered many options for the user interface to select whether
we're using a subdomain or a domain, like having two separate fields,
using a check box, ... In the end we've chosen radio buttons because
they make it easier to follow a logical sequence: first you decide
whether you're introducing a domain or subdomain, and then you enter it.
We've also considered hiding this option and assuming "if it's got a
dot, it's a domain". However, this wouldn't work with nested subdomains
and it wouldn't work with domains which are simply machine names.
Note that a group of radio buttons (or check boxes) is difficult to
style when the text of the label might expand over more than one line
(as is the case here on small screens); in this case, most solutions
result in the second line of the label appearing immediately under the
radio button, instead of being aligned with the first line of the label.
That's why I've added a container for the input+label combination.
We were displaying an icon showing that certain actions can't be
performed. However, people who can't see the icons were hearing that
they _can_ perform certain actions while the opposite is true.
We've considered other options to solve this problem. One was to split
the list in two: actions that can be performed and actions that can't be
performed. It was tricky because in some cases we're listing that
actions that can be performed now and in other cases we're displaying
the actions that people will be able to perform once they verify their
account.
Another option was to include the word "Cannot" as a prefix instead of
"Additional verification needed". We haven't done so because, while in
English we say "cannot do this thing", in other languages they say
"this thing cannot do".
So we've gone with a solution where people hearing what's on the screen
know what's going on and we don't have to make big changes in the code.
As mentioned in commit 925f04e3f, icon classes make screen readers
announce strange symbols and aren't properly displayed for people who
have changed their preferred font family.
This way we simplify the ERB code.
Due to the bug mentioned in the previous commit, we're keeping the
original code instead of using `can?` to check permissions.
We were using similar code in four different places; six, if we count
the welcome pages seeds. Reducing duplication in the pages seeds is a
bit tricky because administrators are supposed to edit their content and
might remove the HTML class we use to define styles. However, we can
share the code everywhere else.
Note that there's a bug in the application since we show that level 2
users cannot vote for budget projects but we give them permission to do
so in the abilities model. We're keeping the same behavior after this
refactoring but we might change it in the future.
We were assigning variants in a controller, in the context of a request.
However, when sending emails, there is no request and no controller is
involved, so we also need to set the variant in the ApplicationMailer
class.
Sometimes it might be convenient to use completely different views for
different tenants. For example, a certain tenant might use a footer that
has nothing to do with the default one.
For these cases, instead of adding `case Tenant.current_schema`
conditions to the view, it might be tidier to use a different file.
For this purpose, we're using Rails variants [1], which means that a
tenant named `mytenant` will use a template ending with
`.html+mytenant.erb` if it's available.
This works with components too, but has a limitation: when using the
`custom/` folder to add ERB files for a tenant, the default tenant ERB
file needs to be added to the `custom/` folder as well; if there aren't
changes to this file, a symbolic link will do.
For example, if we're writing a custom `admin/action_component` view for
the tenant `milky-way` but don't need to change this file for the
default tenant:
1. Create `app/components/custom/admin/action_component.rb` according to
the components customizations documentation [2]
2. Create the custom view for the `milky-way` tenant and save it under
`app/components/custom/admin/action_component.html+milky-way.erb`
3. Enter the `app/components/custom/admin/` folder and run `ln -s
../../admin/action_component.html.erb`
We're also adding some controller tests. Since Rails doesn't load the
middleware during controller tests, we're stubbing the `current_schema`
method directly instead of changing the subdomain of the request.
[1] https://guides.rubyonrails.org/v6.0/layouts_and_rendering.html#the-variants-option
[2] https://docs.consulproject.org/docs/english-documentation/customization/components
Back in commit 36e452437, we wrote:
> The `reload` method added to max_votes validation is needed because
> the author gets here with some changes because of the around_action
> `switch_locale`, which adds some changes to the current user record
> and therefore, the lock method raises an exception when trying to lock
> it requiring us to save or discard those record changes.
This happened when `current_user` didn't have a locale stored in the
database and the `current_locale` method returned the default locale.
And the test "Poll Votation Type Multiple answers" would indeed fail if
we removed the `reload` method. However, we can remove the need to
reload the record by avoiding the mentioned changes on the current user
record.
So we're changing the `User#locale` method so it doesn't modify the user
record.
This way we'll avoid having all tenant organizations named "CONSUL" by
default, and we'll also use different email senders per tenant, which
will reduce the change of the emails being marked as spam.
We were using `consul.dev` as default, which might be fine for the
development environment, but it's something that definitely needs to be
changed on production.
Now we're providing a better default setting: using the same domain
which is used to generate URLs in emails. This also makes it easier to
configure new tenants, since the setting will default to whatever host
the new tenant is using.
The `|| "consul.dev"` part might not be needed; I'm keeping it because
I'm not sure production environents would not experience any new issues
if we don't add it, but we might remove it in the future.
When voting investment projects, the sidebar was rendered without the
`@heading_content_blocks` being set. That resulted in a 500 error when
the heading had content blocks.
By extracting the logic to a component, we make sure the heading content
blocks are properly set every time this code is rendered, no matter
which controller is rendering the view.
We were already doing the same for the main header color; now we also
make it easier to use different top links, subnavigation and footer
colors per tenant.
Just like we do with SCSS variables, we use the brand-secondary color
for the top links when the `--top-links` variable isn't defined.
Just like we did with SCSS variables, we use the `--main-header` CSS
variable and, if it isn't defined, we use the `--brand` CSS variable
instead.
Note that we're still using the `inverted-selection` mixin based on the
default `$main-header` color, so it's possible that we get the inverted
selection in the main header when using a dark color with `$main-header`
but a light color with `--main-header`, which doesn't make much sense.
Not sure whether there's anything we can do about it.
Until now, overwriting the styles for a certain tenant was a very
tedious task. For example, if we wanted to use a different brand color
for a tenant, we had to manually overwrite the styles for every element
using that color.
It isn't possible to use different SCSS variables per tenant unless we
generate a different stylesheet per tenant. However, doing so would make
the CSS compilation take way too long on installations with more than a
couple of tenants, and it wouldn't allow to get the colors dynamically
from the database, which we intend to support in the future.
So we're using CSS variables instead. These variables are supported by
97% of the browsers (as of October 2022), and for the other 3% of the
browsers we're using the default colors (SCSS variables) instead.
CSS variables have some limitations: for instance, it isn't possible to
use functions like `lighten`, `darken` or `scale-color` with CSS
variables, so the application might behave in a strange way when we use
these functions.
It also isn't possible to automatically get whether black or white text
makes a better contrast with a certain background color. To overcome
this limitation, we're providing variables ending with `-contrast`. For
instance, since the default `$brand` color is a dark one, when assigning
a light color to `--brand`, we probably want to assign
`--brand-contrast: #{$black}` as well, so the text is still readable.
Until now, we didn't have specific variables for the headers and were
using the brand colors instead. Now we maintain the brand colors as
default values, but allow overwriting them.
For the navigation and footer, we didn't even have variables.
Back in commit 5dbd69486, I said:
> I'm choosing to use the same color for solid and hollow buttons
> because these elements are usually isolated and so from the UX
> perspective they are similar; links, on the other hand, are often in
> the middle of some text.
However, I made a mistake. The crucial factor is that solid buttons
might have a light background if we choose the brand color to be a light
one, and in this case they automatically get black text. However, hollow
buttons always have a light background and so we can't use a light color
for the text and border of these buttons.
Note this only affects images which can also be customized using the
administration interface; other images like `avatar_admin.png` must be
the same for all tenants. I think this is good enough for now, since the
images that can't be different are the images that aren't customized
that often, and if there's a need to use different images in a certain
CONSUL installation, it can be achieved by changing the code which
renders that image so it uses `image_path_for`.
We were using the same logic in many different places, so we're
simplifying the code. I'm not convinced about the method names, though,
so we might change them in the future.
Note using this method for the default tenant in the `TenantDiskService`
class resulted in a `//` in the path, which is probably harmless but
very ugly and it also generates a different key than the one we got
until now. I've added an extra test to make sure that isn't the case.
We're using the "tenants" subfolder for consistency with the folder
structure we use in ActiveStorage and because some CONSUL installations
might have folders inside the `data` folder which might conflict with
the folders created by tenants.
Note that the Python scripts have a lot of duplication, meaning we need
to change all of them. I'm not refactoring them because I'm not familiar
enough with these scripts (or with Python, for that matter).
Also note that the scripts folder is still shared by all tenants,
meaning it isn't possible to have different scripts for different
tenants. I'm not sure how this situation should be handled; again, I'm
not familiar enough with this feature.
Note we don't need to update the tests; the tests themselves help us
confirm that `Rails.application.secrets` and `Tenant.current_secrets`
return the same object on single-tenant applications.
Right now this is configured using the `secrets.yml` file, which is the
file we've used in the past to configure SMTP settings.
Note that, in the `current_secrets` method, the `if default?` condition
is there so in single-tenant applications it returns the exact same
object as `Rails.application.secrets`, and it makes it immediately clear
for developers reading the code. We're also caching the tenant secrets
(using `||=`) so they behave the same way as Rails secrets; for this to
work properly 100% of the time (for example, in tests) we need to expire
these cached secrets whenever the Rails secrets change.
A similar `unless Tenant.default?` condition is present in the
ApplicationMailer because there's a chance some CONSUL installations
might not be using secrets to define the SMTP settings(they might be
using environment variables, for example) and so in this case we don't
want to force settings based on the secrets.yml file because it would
break the application.
The structure of the SMTP settings in the secrets file should be:
```
production:
tenants:
name_of_the_tenant_subdomain:
smtp_settings:
address:
(...)
```
This way it will be possible to write CSS and JavaScript code that will
only apply to specific tenants.
Note that CSS customization is still limited because it isn't possible
to use different SCSS variables per tenant.
We forgot to do so in commit d827768c0. In order to avoid the same
mistake in the future, we're extracting a method to get these
attributes. We're also adding tests, since we didn't have any tests to
check that the `dir` attribute was properly set.
Note we aren't allowing to delete a tenant because it would delete all
its data, so this action is a very dangerous one. We might need to add a
warning when creating a tenant, indicating the tenant cannot be
destroyed. We can also add an action to delete a tenant which forces the
admin to write the name of the tenant before deleting it and with a big
warning about the danger of this operation.
For now, we're letting administrators of the "main" (default) tenant to
create other tenants. However, we're only allowing to manage tenants
when the multitenancy configuration option is enabled. This way the
interface won't get in the way on single-tenant applications.
We've thought about creating a new role to manage tenants or a new URL
out of the admin area. We aren't doing so for simplicity purposes and
because we want to keep CONSUL working the same way it has for
single-tenant installations, but we might change it in the future.
There's also the fact that by default we create one user with a known
password, and if by default we create a new role and a new user to
handle tenants, the chances of people forgetting to change the password
of one of these users increases dramatically, particularly if they
aren't using multitenancy.
We had some of the logic in the ApplicationMailer. Since we're going to
use this logic in more places, we're moving it to the Tenant model,
which is the model handling everything related to hosts.
While we ping some search engines (currently, only Google) when
generating the sitemap files, we weren't telling search engines
accessing through the `robots.txt` file where to find the sitemap. Now
we're doing so, using the right sitemap file for the right tenant.
Note that the `sitemap:refresh` task only pings search engines at the
end, so it only does so for the `Sitemap.default_host` defined last. So
we're using the `sitemap:refresh:no_ping` task instead and pinging
search engines after creating each sitemap.
Note we're pinging search engines in staging and preproduction
environments. I'm leaving it that way because that's what we've done
until now, but I wonder whether we should only do so on production.
Since we're creating a new method to get the current url_options, we're
also using it in the dev_seeds.
Some tasks don't have to run on every tenant. The task to calculate the
TSV is only done for records which were present before we added the TSV
column, and that isn't going to happen in any tenants because we added
the TSV column before adding the tenants table. Similarly, the migration
needed for existing polls isn't necessary because there weren't any
tenants before we allowed to set the starting/ending time to polls.
We aren't adding any tests for these tasks because tests for rake tasks
are slow and tests creating tenants are also slow, making the
combination of the two even slower, particularly if we add tests for
every single task we're changing. We're adding tests for the
`.run_on_each` method instead.
The subdomain elevator we were using, which is included in apartment,
didn't work on hosts already including a subdomain (like
demo.consul.dev, for instance). In those cases, we would manually add
the subdomain to the list of excluded subdomains. Since these subdomains
will be different for different CONSUL installations, it meant each
installation had to customize the code. Furthermore, existing
installations using subdomains would stop working.
So we're using a custom method to find the current tenant, based on the
host defined in `default_url_options`.
In order to avoid any side-effects on single-tenant applications, we're
adding a new configuration option to enable multitenancy
We're enabling two ways to handle this configuration option:
a) Change the application_custom.rb file, which is under version control
b) Change the secrets.yml file, which is not under version control
This way people prefering to handle configuration options through
version control can do so, while people who prefer handling
configuration options through te secrets.yml file can do so as well.
We're also disabling the super-annoying warnings mentioning there are no
tenants which we got every time we run migrations on single-tenant
applications. These messages will only be enabled when the multitenancy
feature is enabled too. For this reason, we're also disabling the
multitenancy feature in the development environment by default.
Note we're using the `:HOST` regular expression since subdomains can
contain the same characters as domains do. This isn't 100% precise,
though, since subdomains have a maximum length of 63 characters, but is
good enough for our purposes.
This way all tenants will be able to access them instead of just the
default one.
The apartment gem recommends using a rake task instead of a migration,
but that's a solution which is primarily meant for new installations.
Migrations are easier to execute on existing installations.
However, since this migration doesn't affect the `schema.rb` file, we
still need to make sure the shared schema is created in tasks which do
not execute migrations, like `db:schema:load` or `db:test:prepare`, just
like the apartment gem recommends. That's why we're enhancing these
tasks so they execute this migration.
Note that there might be cases where the database user isn't a superuser
(as it's usually the case on production environments), meaning commands
to create, alter or drop extensions will fail. There's also the case
where users don't have permissions to create schemas, which is needed in
order to create the shared extensions schema and the schemas used by the
tenants. For these reasons, we're minimizing the number of commands, and
so we only alter or create extensions when it is really necessary.
When users don't have permission, we aren't running the commands but
showing a warning with the steps needed to run the migration manually.
This is only necessary on installations which are going to use
multitenancy; single-tenant applications upgrading don't need to run
this migration, and that's why we aren't raising exceptions when we
can't run it.
For new installations, we'll change the CONSUL installer so extensions
are automatically created in the shared schema.
Also note the plpgsql extension is not handled here. This is a special
extension which must be installed on the pg_catalog schema, which is
always in the search path and so is shared by all tenants.
Finally, we also need to change the `database.yml` file in order to
search for shared extensions while running migrations or model tests,
since none of our enabled extensions are executed during migrations;
we're also adding a rake task for existing installations. Quoting the
apartment documentation:
> your database.yml file must mimic what you've set for your default and
> persistent schemas in Apartment. When you run migrations with Rails,
> it won't know about the extensions schema because Apartment isn't
> injected into the default connection, it's done on a per-request
> basis.
We were using each one half the time, while they both had the same value
by default. It was impossible to know when me meant "use a dark color
here" or "use the secondary brand color" here.
So now we're only using one variable, so it's easy it'll be easy to add
CSS custom properties to overwrite this variable. We're choosing
`brand-secondary` because its name makes it less problematic to use a
light color.
This is consistent with the usage of `$body-background`. This way
Foundation elements using `$body-font-color`, like the `<body>` tag,
will be changed when changing this variable, which wouldn't happen when
using `$text`.
The variables `$anchor-color` and `$anchor-color-hover` are the ones
Foundation uses internally; by using them, we make sure every link will
use the colors we define.
Now we can simplify the default styles for the `<a>` tags, since by
default they already use these variables.
This way we simplify the code a bit.
Note we're only using this function when variables for background colors
are already defined, since that means customizing the variable using the
background color will automatically change the color of the text.
Customization isn't easier when using raw colors.
We were defining (for instance) white text against the `$brand`
background. That meant that, if somebody customized the `$brand` color
so it used a light color, they had to customize the text color as well
in order to guarantee proper contrast between text and background
colors.
So we're using `color-pick-contrast` instead, which means we don't have
to manually calculate whether white or black will be the color which
makes the text more readable.
