@molgenis/molgenis-theme

v1.7.1

Published

3 years ago

Base SCSS theme for Molgenis

Downloads

0High
0Medium
0Low

Molgenis Theme

This is the Bootstrap-based Molgenis SCSS theme generator. Its purpose is to streamline the theming workflow for all Molgenis sites by:

Simplifying the creation of new themes
Keeping existing themes maintainable
Keeping existing themes consistent by applying fixes to the base theme
Providing a better frontend developer experience using a proxy/reload tool chain
Establishing and simplifying the publishing & distibution workflow

Prerequisites

Basic Usage

git clone [email protected]:molgenis/molgenis-theme.git
cd molgenis-theme
yarn
# Set the default config file
cp .env.defaults .env
# Build the selected theme (MG_THEME_LOCAL in .env)
yarn build
# Build all themes at once
yarn build-all

:tada: Congratulations! You just generated the default molgenis-blue theme.

CSS files were written to the css directory. Each theme has a Bootstrap 3 and a Bootstrap 4 variant.

Configuration

The configuration for Docker and the SCSS tool are read from a shared environment file; the .env file. It has the following options:

# This is a Docker directive to make containers unique per project.
# Don't change this, unless you have a good reason to.
COMPOSE_PROJECT_NAME=mg_projects
# URL of a remote Molgenis instance to proxy (use with 'yarn proxy')
MG_PROXY=https://master.dev.molgenis.org
# Docker service name (use with 'yarn proxy-molgenis')
# MG_PROXY=http://molgenis:8080
# Docker host ip (use with 'yarn proxy-services')
# MG_PROXY=http://172.19.0.1:8080

# The local theme to serve and watch (/theme/...):
MG_THEME_LOCAL=molgenis-blue
# The proxy CSS theme to replace:
MG_THEME_PROXY=bootstrap-molgenis-blue.min.css

Development

Starting A New Theme

Copy an existing theme to a new directory:

cp -R theme/molgenis-blue theme/molgenis-red

Update the config to use the new theme

# vim docker/.env
MG_THEME_LOCAL=molgenis-red

Build the theme
```
yarn build
```

Using The Proxy

The proxy setup uses Nginx to apply locally developed theming files to a remotely controlled Molgenis site, to make your life as a developer a bit easier. The development service features auto-build of SCSS source-files and livereload of stylesheets, so changes to your theme are automatically reflected in the browser. It requires a bit of setup:

Setup the proxy config in the .env file:

# Example with yarn proxy
MG_PROXY=https://master.dev.molgenis.org
# Example with yarn proxy-services; use docker host ip here:
# MG_PROXY=http://172.19.0.1:8080
# Example with yarn proxy-molgenis; use docker service name here:
# MG_PROXY=http://molgenis:8080

# The theme that is being applied on the proxied host.
MG_THEME_LOCAL=molgenis-red
# The theme that is in use by the proxy
# Check view-source:https://master.dev.molgenis.org/ for
# the current theme in the <head> section
MG_THEME_PROXY=bootstrap-molgenis-blue.min.css

Start the proxy in one of the three different setups:

# When you want to style an existing Molgenis site; e.g. master.dev.molgenis.org
yarn proxy
# When you need to test with a certain local Molgenis branch (IntelliJ)
yarn proxy-services
# When you want to test with a locally deployed Molgenis site
yarn proxy-molgenis

Use the most simple option to get started; e.g. yarn proxy

Start the SCSS development server from another tab:

yarn dev

Visit localhost to see the public dev server using the Bootstrap 4 version of the molgenis-red theme
Install the Chrome livereload extension to autoreload on file-change
Switch livereload on
Try changing variable $mg-color-primary in molgenis-red/_variables.scss

The theme on the webpage should now automatically reflect your changes on save. Browse through the base theme to get an idea how a theme is being constructed. Checkout the mg-variables defintion file for the theming variables that are customizable.

Conventions

Both Bootstrap 3 & 4 CSS is being used in Molgenis while it transitions to Bootstrap 4. Make sure you check the current Molgenis page source to verify that the asserted theme is being used. The theme in scss/molgenis provides defaults for all themes, because themes inherit their main settings from it. When creating a new theme, please try to maintain the following workflow order:

Apply only Molgenis (mg-) variables in your theme

To keep theming maintainable and your future self happy, it is crucial that each theme refrains from applying custom styling, unless there is no other option. Always make an effort to fit your "unique" use-case in the base theme. In case the current theming variables are not providing the required customization:

Update Bootstrap variables in scss/molgenis
Refactor Molgenis variables in scss/molgenis if necessary
Add selectors in scss/molgenis (_custom) using Molgenis variables

(!) Keep in mind that changes are applied to all themes.

* **theme-3.scss** is the root source-file for the generated Molgenis Bootstrap 3 theme
* **theme-4.scss** is the root source-file for the generated Molgenis Bootstrap 4 theme
* Theme variables go in **./theme/myproject/_variables.scss**
* Theme-agnostic fixes should be made in the main theme at **./scss/molgenis**
* Molgenis theme variables start with the **mg-** prefix
* Molgenis theme variables are in **./scss/molgenis/_variables.scss**
* Do not use Bootstrap variables in themes directly if you don't need to;
* use the **mg-** prefixed Molgenis theme variables instead
* Bootstrap-3 variables are in **./node_modules/bootstrap-sass/assets/stylesheets/bootstrap/_variables.scss**
* Bootstrap-4 variables are in **./node_modules/bootstrap-scss/_variables.scss**
* Bootstrap-3 variables are customized in **./scss/molgenis/theme-3/_variables.scss**
* Bootstrap-4 variables are customized in **./scss/molgenis/theme-4/_variables.scss**
* Small theme-agnostic Bootstrap-agnostic selectors are in **scss/molgenis/_custom.scss**
* Extensive theme-agnostic Bootstrap-agnostic selectors are in **scss/molgenis/elements/_some-page-element.scss**
* Small theme-agnostic Bootstrap-3 specific selectors are in **scss/molgenis/theme-3/_custom.scss**
* Extensive theme-agnostic Bootstrap-3 specific selectors are in **scss/molgenis/theme-3/elements/_some-page-element.scss**
* Theme-agnostic Bootstrap-4 specific selectors are in **scss/molgenis/theme-4/_custom.scss**
* Extensive theme-agnostic Bootstrap-4 specific selectors are in **scss/molgenis/theme-4/elements/_some-page-element.scss**

Publishing

Distribution

The generated theme CSS files are published to the npm package management service, as soon a new version is detected on the master branch. We use Unpkg to serve the CSS files directly from npm. This way, you don't necessarily have to build the themes yourself. Also, this may later be used as an alternative distribution mechanism, using a variation of our Unpkg proxy setup, e.g.:

location @molgenis{
    rewrite ^/@molgenis/[email protected]/css/mg-(?<theme>[-\w]+)-(?<version>[0-9]+).css /css/bootstrap-$version/bootstrap-$theme.min.css break;
    proxy_pass https://master.dev.molgenis.org;
    proxy_buffers 4 32k;
    proxy_ssl_session_reuse on;
}

location ~ ^/css/bootstrap-(?<version>[0-9]+)/bootstrap-(?<theme>[-\w]+).min.css {
    rewrite ^/css/bootstrap-(?<version>[0-9]+)/bootstrap-(?<theme>[-\w]+).min.css /@molgenis/[email protected]/css/mg-$theme-$version.css break;
    proxy_pass https://unpkg.com;
    proxy_intercept_errors on;
    error_page 404 = @molgenis;
}

Dynamic Themes

This is a Proof-of-Concept theme service, that generates theme files on-the-fly. Instead of requesting CSS files, a Molgenis instance just posts a set of variables to this service. The accompanying theme file is then returned accordingly.

Usage:

Start the SCSS service
```
yarn serve
```

Post a request body to the theme endpoint with a tool like Postman:

{
  "name": "molgenis-red",
  "version": 4,
  "mg-color-primary": "#005c8f",
  "mg-color-primary-light": "#0069a4"
}

Depending on the version (3 or 4), either the generated Bootstrap 3 or Bootstrap 4 version is returned. Post validation is still a bit flunky, so it's easy to break.