SCSS

Moodle 3.2

Overview

SCSS or SASS Sass (Syntactically Awesome Stylesheets) is a style sheet language initially designed by Hampton Catlin and developed by Natalie Weizenbaum. It's an advanced way of writing CSS that we use in some themes within Moodle.

Browsers don't interpret it themselves, however, so SCSS files need to be converted into normal CSS before use.

Using in a theme

Moodle includes a built in SCSS compiler so to use SCSS in your theme, you only need to set the theme scss variable, in your theme's config.php file, to point to the main scss file for your theme:

// Points to the file theme/themename/scss/main.scss.
$THEME->scss = 'main';

Moodle will look for a file named 'main.scss' in the 'theme/themename/scss' folder and compile it. If you don't see the affect of your changes right away, try purging the caches or enabling theme designer mode.

Inheriting from a parent

Even if your theme is inheriting from a parent, the SCSS file itself will not inherit from anything, this is something you should do manually. For instance, if you want your SCSS file to include all of the SCSS code provided by theme_boost, usually to change the variables, you need to manually import the file like this:

// In your theme's SCSS file
@import "../../boost/scss/moodle";

The path needs to be relative and not absolute. You would use it like this:

$brand-primary:             #00acdf !default;
$my-color:                  #ff9900 !default;

@import "../../boost/scss/moodle";

body {
    background-color: $my-color;
}

NOTICE: At the moment, Moodle is using a PHP sass compiler which does not support '@import url' at-rule MDL-57875, which is a challenge when you wish to use bootswatch presets or Google fonts directly. so it is advise to use the OS level sass binary compiler (by installing libsass via 'yum install libsass' || 'apt install sassc', or other means) and then setting the admin $CFG->pathtosassc to use the 'sassc' binary.

Advance usage

On-the-fly injections

The following settings allow themers to point to a function which will either prepend, or append, SCSS code to content gotten from $THEME->scss.

// The content returned by this function is added before the main SCSS.
$THEME->prescsscallback = 'theme_themename_scss_to_prepend';

// The content returned by this function is added after the main SCSS.
$THEME->extrascsscallback = 'theme_themename_scss_to_append';

The functions will receive the theme config as first argument.

Dynamic $THEME->scss

Rather than giving the name of your SCSS file in $THEME->scss, you can make it a function which returns the SCSS content.

$THEME->scss = function($themeconfig) {
    $scsscontent = '$my-var: red;';
    $scsscontent .= body { color: $my-var; }';
    return $scsscontent;
}

Example

Moodle's Boost theme has rules written using SCSS.

See also

• Using 'sassc' binary sass compiler as an alternative to Moodle PHP sass compiler. MDL-61394 ($CFG->pathtosassc)
• Sass official website