Working with Bootstrap OPAC LESS files

From Koha Wiki
Jump to navigation Jump to search

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

  1. Install Node.js
  2. 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 less@2.7.3

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.


Developer handbook

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Working_with_Bootstrap_OPAC_LESS_files&oldid=20859"