Working With LESS in Themes

Owned by Former user (Deleted)
Oct 25, 2017

Totara Learn (formerly Totara LMS) 9.0

Styles in the new themes Roots and Basis in Totara Learn 9.0 are authored using the CSS preprocessing language LESS. It is possible (but not mandatory) to use LESS to author styles in your custom themes. LESS compilation is automated using the Node based Grunt task runner. Also see the documentation on working with themes in 9.0.

Setup

If you would like to use LESS in your theme you will first need to ensure that you have Node and NPM installed. Once these requirements are met if you have not already installed the global Grunt CLI then enter the following at the command-line:

npm install -g grunt-cli

Once that has completed install local dependencies by running the following in your Totara install directory:

npm install

Important: If you are upgrading a (development) environment in which you have already installed Node dependencies you will need to update the installed packages. Delete the node_modules directory and re-run npm install.

Compiling theme styles

The LESS to CSS compilation task has been designed to be consistent with the JavaScript AMD task in that the files it compiles are based on your current working directory (CWD). If the CWD is a theme directory then only theme LESS files will be compiled and if the CWD is a component then only component LESS will be compiled. Any other directory will cause all LESS files in themes and components to be compiled. As this takes longer (and will be unnecessary) it is recommended you compile from your theme directory. Note the dollar signs in the examples which follow indicate the command-prompt and are not part of the command.

$ cd /path/to/totara/theme/mytheme
$ grunt css

It is possible to add a custom theme directory in Totara using the themedir config option. If this is the case you will need to tell Grunt about it when compiling:

$ grunt css --themedir='/path/to/custom/themedir'

This will work when CWD is the Totara installation root directory (but will also compile all theme and component LESS). In order to run Grunt for a single theme in your custom directory you will need to also tell it where to find the Gruntfile (assuming the custom dir is not inside the Totara codebase). Use the following inside a theme in the custom directory:

$ grunt css --themedir='/path/to/custom/themedir' --gruntfile='/path/to/totara/Gruntfile.js'

Style Inheritance

Special considerations for LESS based inheritance in your theme are covered by the documentation on working with themes in 9.0.

Vendor prefixing

Browser vendor-specific prefixes for newer CSS properties in theme stylesheets are automatically generated when running the Grunt CSS task via the Autoprefixer PostCSS plugin. Prefixing is automated for the last two versions of all major browsers and includes support for IE9+. Note: this is only applicable for theme stylesheets, core components and plugins are not autoprefixed.

RTL language styles

Since Totara Learn 9.0 theme styles for right to left (RTL) languages are automatically generated when running the Grunt CSS task. At present this is achieved via the RTLCSS PostCSS plugin which outputs a stylesheet of the same name with a direction-specific suffix e.g. the stylesheet theme/roots/less/totara.less is output as theme/roots/style/totara.css AND theme/roots/style/totara-rtl.css Note: this is only applicable for theme stylesheets, core components and plugins are not flipped.

Prevent Grunt processing of CSS

If for some reason a stylesheet should NOT be processed by Grunt RTL and vendor prefixing tasks add the suffix '-noprocess' e.g. mystyles.css would become mystyles-noprocess.css An example where this is useful is the stylesheet theme/basis/style/settings-noprocess.css which is not compiled from LESS source and contains Totara theme settings tokens (e.g. [[setting:buttoncolor-readable-text]]) which cause the LESS parser and post processing tasks to fail as they are not recognised LESS or CSS.

Totara Learn (formerly Totara LMS) 2.9 and below

Note that the only theme which contains LESS is the base theme Bootstrapbase. Standard Totara Responsive and Kiwifruit extend this using CSS only therefore if your theme extends Standard Totara Responsive or Kiwifruit it is unlikely you will need to work with LESS.

If you're working with the responsive themes you will need to use a command line tool called 'Recess' to compile LESS files into CSS. LESS is a CSS pre-processor that extends the CSS language, adding features that allow variables, mixins, functions and many other techniques to create CSS that is more maintainable, themable and extendable.

To Install Recess follow the instructions here: https://docs.moodle.org/dev/LESS.

If you're running Ubuntu and get the following error when you run the recess command:

bash: ../style/moodle.css: No such file or directory

Then use the following to create a symbolic link which should solve the problem. If it still doesn't work, then Google is your friend.

sudo ln -s /usr/bin/nodejs /usr/bin/node

If you want an easy life, add the following alias to your terminal. This will alow you to use 'recesscss' to run Recess from the root of your Totara site.

alias recesscss='recess --compile --compress theme/bootstrapbase/less/moodle.less > theme/bootstrapbase/style/moodle.css'