Customising CSS using SASS¶
The web packaging ecosystem¶
Reahl styling is implemented using Bootstrap. In order to customise your styling, you need to compile Bootstrap sources using SASS after changing its input variables to suit your needs.
You can of course also add your own CSS(see Layout and styling) on top of that too.
Once you have compiled your customised theme, you need to package the resultant CSS and JavaScript and make it part of your site.
For packaging, use npm and webpack, both of which need the Node.js runtime installed in your development environment.
In order to make the packaged CSS and JavaScript part of your site,
you create a custom Library (see also Shipping JavaScript and CSS code).
Install JavaScript and CSS build tools for your project¶
Install Node.js and npm:
sudo apt-get install nodejs npm
Note
If you know docker, you might prefer using it for executing Node.js commands instead of installing Node.js. If you do this, execution of the npm commands are done on your main machine even if you are using the Reahl docker development container for development, from the root of your source code.
To use docker, on your main machine, do:
alias npm='docker run --rm -v ${PWD}:/app -w /app node:15.7.0 npm'
Install bootstrap sources and packaging tools in your project:
cd bootstrapsass
npm init -y
npm install [email protected] --save
npm install autoprefixer css-loader mini-css-extract-plugin sass postcss-loader sass-loader style-loader webpack webpack-cli --save-dev
This creates package.json and package-lock.json files in the root of your project which state what packages your project needs. It also downloads and installs all these dependencies in the directory node_modules.
Configure webpack¶
Create a webpack directory containing an index.js which includes the bootstrap sources:
import 'bootstrap';
Define your theme by setting bootstrap variables (or custom CSS) in theme.scss in the webpack directory:
$body-bg: #000;
$body-color: #a08a78;
$theme-colors: (
"primary": #0074d9,
"danger": #ff4136,
"custom-color": #900
);
$enable-rounded: false;
$enable-shadows: true;
@import "bootstrap";
Create a file webpack.config.js to instruct webpack to package your theme sources:
//https://webpack.js.org/loaders/sass-loader/
const path = require('path');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
module.exports = {
entry: { 'main': './webpack/index.js',
'theme': './webpack/theme.scss'
},
output: {
filename: '[name].js',
path: path.resolve(__dirname, 'dist')
},
module: {
rules: [
{
test: /\.scss$/,
use: [MiniCssExtractPlugin.loader, 'css-loader', 'sass-loader'],
},
],
},
plugins: [ new MiniCssExtractPlugin({
filename: '[name].css'
})],
};
Edit package.json to make npm aware of webpack:
Add, at the top level:
"main": "webpack.config.js",
Under “scripts”, before “test”, add:
"build": "webpack",
Build your custom SCSS¶
Still in your project root, run:
npm run build
This command creates a dist directory which contains the packaged CSS and JavaScript files needed by your site.
Configure your application to use your customisation¶
Create a Library for the files created in dist as part of your source code:
class CompiledBootstrap(Library):
def __init__(self):
super().__init__('custom')
self.egg_name = 'bootstrapsass'
self.shipped_in_directory = 'dist'
self.files = [
'theme.css',
'main.js'
]
Create configuration that includes all the necessary Reahl libraries as well as your customised library, in the correct order:
from reahl.web.libraries import LibraryIndex, JQuery, JsCookie, JQueryUI, Underscore, HTML5Shiv, IE9, Reahl, Holder, ReahlBootstrap4Additions
from reahl.doc.examples.howtos.bootstrapsass.bootstrapsass import ThemedUI, CompiledBootstrap
web.site_root = ThemedUI
web.frontend_libraries = LibraryIndex(JQuery(), JsCookie(), JQueryUI(), Underscore(), HTML5Shiv(), IE9(), Reahl(), Holder(),
CompiledBootstrap(), ReahlBootstrap4Additions())
Congratulations!¶
You should now be able to serve your application as usual, but with a custom theme.