@molgenis-ui/molgenis-theme
v2.10.0
Published
Base SCSS theme for Molgenis
Downloads
340
Readme
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
Getting started
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 in .env)
yarn build
:tada: 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.
* 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
:tada: 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