Add a theme

[costateixeira]

As a test instance and event manager, I want to be able to create my own theme.

• Create a theme
• Document how to create and use a custom theme

[costas80]

@costateixeira, this is now published on the Test Bed's nightly build channel. The documentation (in the Test Bed's user guide) will be updated when the next release will be published. For now however you can use the following as a description on how to adapt/preconfigure the Test Bed's theme:

1. Using the current configuration issue a docker compose pull. This will get the latest nightly build images.
2. Start up the Test Bed using docker compose up -d.
3. Connect as Test Bed (not community) administrator (this would be the test@test.com account I communicated in the original email summarising the PoC's resources). Community administrators don't have access to overall system settings.
4. Go to System administration and select tab Themes. If you choose to create a theme here it will base the new theme on the existing one's configuration. You can change here all logos as well as numerous colours that are used on the interface. The simplest approach if you want to experiment is to set the new theme as "active", as any updates on the active theme are immediately reflected.
5. Once you're happy with the result (and ensuring the theme you want is active), go to Data export.
6. Select to make a community export and check everything (including the themes). Note that the archive's password will be set in the docker-compose.yml as an environment property (I had used "fhir" initially).
7. As a final step take the produced archive and use it to replace the existing export.zip archive.

Important note

The docker-compose.yml file reads the export.zip archive from folder ./config/data. Upon the very first startup this archive will be removed from this folder to avoid reprocessing it again at subsequent startups. To use the new export archive on a fresh Test Bed installation (or after you have issued a docker compose down -v) place it under ./config/data before you issue docker compose up -d.

Finally if you want to apply a theme on an existing Test Bed instance you could simply navigate on the UI to Data import and select the archive to import. You will always see here a confirmation screen in which you can select exactly what gets imported (you can e.g. skip the community/domain and just import the system settings). Alternatively for such a case you could also have simply exported only the system settings in the earlier steps in which case the archive would only contain the themes.

In case you want to reuse the simple themes I put together and showed in our last meeting (e.g. see screenshot below) I also attach here a export_themes.zip you can import (via the Data import screen) as a starting point. The password for the archive is "fhir".

[costateixeira]

so, importing a theme is via the filesystem, and applying a theme is not be a request or configuration, but must be done manually?

[costas80]

so, importing a theme is via the filesystem, and applying a theme is not be a request or configuration, but must be done manually?

No, you can change the theme (tweaking it, creating copies, activating other themes) via the UI when connected as Test Bed administrator. You do this in the System administration section. There is no need to go via file system export/imports to do this.

Alternatively to creating a theme manually you can have it be created (once) at startup as part of the other data defining the community, users, test suites etc. This is the case where you add such data in an export archive that is then configured in the docker-compose.yml file to be read when the Test Bed is started for the first time.

In this second case, besides importing one or more inactive themes, you can also set one as being active by default so that you don't need a manual action to activate it. This can be done in two ways:

• Option 1 - via the export archive: Before creating your data export that is used to populate the Test Bed at startup you can set the theme in question as active. A custom, active theme will be added as such in the export archive and will be set as active when imported.
• Option 2 - via environment variable: You can also have only inactive themes added in your data export file and select the one you want to activate by setting the THEME environment property in the gitb-ui container's configuration in the docker-compose.yml. You can see an example of this in the production installation guide where setting THEME=ec sets the built-in "ec" theme as active. If you have defined a custom theme with key "fhir" and you set THEME=fhir this will be activated at startup.

Regarding which theme is applied and how it was activated there is a message that appears in the gitb-ui container's log as follows:

2023-12-11 14:50:34 11/12/2023 12:50:34 INFO  managers.SystemConfigurationManager - Loaded theme [fhir] marked as active.

If set via environment variable you would see something like:

2023-12-11 14:50:34 11/12/2023 12:50:34 INFO  managers.SystemConfigurationManager - Loaded theme [fhir] selected via environment variable.