@molgenis-ui/molgenis-theme

Molgenis Theme

Molgenis-theme is the SCSS/Bootstrap-based Molgenis theming source. Its purpose is to streamline the theming workflow by:

• Simplifying the creation of new themes
• Making existing themes maintainable & consistent
• Providing a better frontend developer styling experience
• Establishing and simplifying the publishing & distibution workflow

Prerequisites

• Docker
• Docker-compose
• Node.js 14+
• Yarn
• Visual Studio Code

Getting started

git clone [e-mail]:molgenis/molgenis-theme.git
cd molgenis-theme
yarn
# Set the default config file
cp .env.defaults .env
# Build the selected theme (MG_THEME in .env)
yarn build

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

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

Configuration

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

# Docker-specific; just ignore this.
COMPOSE_IGNORE_ORPHANS=True
COMPOSE_PROJECT_NAME=mg_projects

# Remote proxy only; use with 'yarn proxy'
MG_PROXY=https://master.dev.molgenis.org
# Docker host ip; use with 'yarn proxy-services'
# MG_PROXY=http://172.19.0.1:8080
# Docker service molgenis host; Use with 'yarn proxy-services-molgenis'
# MG_PROXY=http://molgenis:8080

# URL to the theme generator service from the NGINX docker container.
MG_PROXY_THEMEGEN=http://172.18.0.1:3030

# (!) The theme to serve and watch. Please note that
# you need to restart both the docker services and
# the SCSS tool after changing this variable.
MG_THEME=molgenis-blue

Modify a Theme

• Serve the theme

  # Proxy master.dev.molgenis.org on http://localhost
  yarn proxy
  # Start dev-service from another console tab:
  yarn dev

• Open localhost in Chromium.

This is the public dev server using the local styling of the molgenis-blue theme

• Install the Chrome livereload extension
• Switch livereload on
• Try changing variable $mg-color-primary in molgenis-blue/_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.

Conventions

Bootstrap 3 & 4 CSS are being used in Molgenis. This creates extra overhead, but is sadly a necessity while Bootstrap 3 is still in use in some apps. When creating a new theme, please try to maintain the following workflow order:

• Use existing Bootstrap classes wherever possible
• Apply only variables from /scss/molgenis/_variables.scss in the theme
• Refactor Molgenis variables in scss/molgenis if necessary

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

Common SCSS locations & their meaning

* 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`
* `scss/molgenis/theme-3/_theme.scss` is the root of the Molgenis Bootstrap 3 theme
* `scss/molgenis/theme-4/_theme.scss` is the root of the Molgenis Bootstrap 4 theme
* Bootstrap 3 variables are customized in `./scss/molgenis/theme-3/_variables.scss`
* Bootstrap 4 variables are customized in `./scss/molgenis/theme-4/_variables.scss`
* `scss/molgenis/_variables.scss` contains themable variables that can be overridden in `./themes/mytheme/_variables.scss`
* Theme-agnostic fixes MUST be made in the main theme at `./scss/molgenis`
* Theme variables that differ between Bootstrap 3 and 4 start with a `mg-` prefix
* Theme variables that are similar in Bootstrap 3 and 4 are used directly without `mg-` prefix
* Do NOT use variables in themes that are not already in `scss/molgenis/_variables.scss`
* Keep `scss/molgenis/_variables.scss` small and tidy

This is mainly legacy. Custom selectors should be removed in the long run,
or moved to Vue theme-agnostic component styling:

* Generic selectors Bootstrap 3: `scss/molgenis/theme-3/_custom.scss`
* Molgenis elements Bootstrap 3: `scss/molgenis/theme-3/modules/_some-page-element.scss`
* Molgenis modules Bootstrap 3: `scss/molgenis/theme-3/modules/_some-module.scss`

* Generic selectors Bootstrap 4: `scss/molgenis/theme-4/_custom.scss`
* Molgenis elements Bootstrap 4: `scss/molgenis/theme-4/modules/_some-page-element.scss`
* Molgenis modules Bootstrap 4: `scss/molgenis/theme-4/modules/_some-module.scss`

* Generic selectors Bootstrap 3+4: `scss/molgenis/_custom.scss`
* Molgenis elements Bootstrap 3+4: `scss/molgenis/elements/_some-page-element.scss`

Distribution

The generated theme CSS files are published to npm as soon as a new fix/feat commit is detected on the master branch. Unpkg is used to serve the CSS files directly. The default urls for the Molgenis-blue theme are:

/@molgenis-ui/molgenis-theme/dist/themes/mg-molgenis-blue-4.css
/@molgenis-ui/molgenis-theme/dist/themes/mg-molgenis-blue-3.css

A new feature is to serve stylesheets dynamically. We would still have a set of versioned and published themes to choose from, but also the option to generate a theme from the Molgenis UI on-the-fly. This makes it easy for customers to setup their own theme with just a few clicks. This requires a simple theming service backend and a new theming manager frontend.

• Start the SCSS service

  yarn service

The theme-manager posts a request body like this to the theming service endpoint:

{
  "name": "molgenis-blue",
  "variables": {
    "mg-color-primary": "#f00",
    "mg-color-primary-contrast": "#ff0",
    "mg-color-secondary": "#00f",
    "mg-color-secondary-contrast": "#0ff"
  }
}

The response is:

{
    "name": "molgenis-blue",
    "urls": [
        "mg-molgenis-blue-3-1614770277098.css",
        "mg-molgenis-blue-3-1614770277098.css"
    ],
    "timestamp": 1614770277098
}

• Go to the current theme-manager and choose Use a custom theme, fill in:

/generated/mg-molgenis-blue-4-1614770277098.css
/generated/mg-molgenis-blue-3-1614770277098.css

🎉 Congratulations! You just generated a dynamic theme.

FAQ

Yarn build breaks on node-sass on MacOS

You need to have the xcode-cli installed

xcode-select --install