Working with Bootstrap OPAC LESS files
From Koha Wiki
The Bootstrap OPAC theme uses LESS files to generate the CSS files used in the theme. LESS is a "dynamic stylesheet language" (similar to Sass) which allows authors to use "variables, mixins, operations and functions." The bootstrap theme's LESS files contain some use of variables and mixins, but their primary difference from standard CSS is the logical grouping of style rules through nesting.
When making CSS changes to the Bootstrap theme changes should be made to the .less files, not the .css files.
Installing LESS in your development environment
- Install Node.js
- Use the Node Package Manager to install LESS (you might need to use sudo because it's a global package):
npm install -g less
Manually compiling a LESS file
You can manually compile a LESS file using this command:
lessc bootstrap/less/opac.less > bootstrap/css/opac.css
To output a minified CSS file add the "--yui-compress" flag ("--compress" in newer versions of lessc):
lessc --compress bootstrap/less/opac.less > bootstrap/css/opac.css
Even newer versions have deprecated "--compress" in favour of a separate NPM package. To install the CSS compressor:
npm install -g less-plugin-clean-css
To use it, add a flag to your lessc command, like so:
lessc --clean-css="--s0 --advanced --compatibility=ie7" bootstrap/less/opac.less > bootstrap/css/opac.css
Note: latest version of less (3.0.1) doesn't work correctly with less-plugin-clean-css. You can downgrade less to the latest 2.x version like this:
npm install -g firstname.lastname@example.org
Automate processing of LESS files during development
There are options for automatically compiling LESS files upon save during development. One such tool is Dead Simple LESS Watch Compiler.
node less-watch-compiler.js ~/kohaclone/koha-tmpl/opac-tmpl/bootstrap/less/ ~/kohaclone/koha-tmpl/opac-tmpl/bootstrap/css
In the example above the location of the LESS files is passed along with the destination path where compiled CSS files should be placed. Note that by default the Dead Simple LESS Watch Compiler minifies CSS using the --yui-compress flag. As of this writing (2014-01-30) Bootstrap OPAC CSS files shipped with Koha are not compressed, but they really ought to be.
Guidelines for editing LESS files
It is important to note that the main OPAC LESS file (opac.less) incorporates two other LESS files: mixins.less and responsive.less. mixins.less contains some very basic mixins for use by the other files. responsive.less contains any style rules which are applied depending on media queries of viewport width. These are kept separate for ease of editing.
responsive.less is @imported at the end of opac.less and thus the compiled output of responsive.less is appended to the end of the compiled output of opac.less. No style rules should appear after the @import rule for responsive.less.
When adding style rules to the LESS files please look for existing rules in which your additions might be logically nested.
Submitting patches containing changes to LESS and CSS
If you make a change to a LESS file and recompile the corresponding CSS file you should submit the updated CSS file in a separate patch. The recompiled CSS file will always conflict when applying the patch because git doesn't know how to merge the differences between two minified CSS files.