Debugging SCSS in Moodle LMS
You’ve been working on a theme for Moodle LMS, either developing a new theme or using the Raw Initial SCSS and Raw SCSS fields included with most themes based on Boost. If you’ve ever done this and made a mistake, an error in the SCSS will fail to compile and you end up back with just the basic SCSS from Boost. But how do you know where the error happened?
This month, we will explore the @debug, @warn, and @error SCSS directives and the secret to where you will find helpful debugging and error messages. These handy tools provide feedback to developers during the compilation process, helping catch issues and improve the code.
The @debug directive
The @debug directive is your friend who whispers secrets to you during development. When you use it, SCSS will output the specified message. It’s great for debugging and understanding what’s happening during the compilation process.
Basic Syntax:
@debug "This is a debug message.";You can also include SCSS variables in the message to display its value. For example:
$myColour: #0000FF; // Blue.
@debug "The value of myColor: #{$myColour}.";The output will be something like this:
(unknown file):224 DEBUG: The value of myColor: : #FFE03D.Note that, unlike the @error directive discussed later, the @debug directive does not stop the compilation of your SCSS, it just outputs a message.
If you are going to become familiar with and make use of just one of the directives covered here, this is the one to keep handy in your toolbox.
The @warn directive
The @warn directive works almost the same way as @debug. Like @debug, it does not stop the compilation process, but it will issue a warning. Use it when you want to notify developers about potential issues or deprecated values.
Basic Syntax:
@warn "This is a warning message.";Like @debug, you can also include SCSS variables in the message to display its value. For example:
$myColour: #0000FF; // Blue.
@warn "The value of myColor: #{$myColour}.";The output will be something like this:
WARNING: The value of myColor: #FFE03D.
on line 224 of (unknown file)The @error directive
The @error directive is the strict teacher who halts everything. If you use it, Sass will stop compiling and display the specified message as a fatal error. Reserve this for critical issues that require immediate attention:
Basic syntax:
@error "This is an error message.";Example:
$myColour: blue; // Blue.
@error "#{$myColour} is not a valid hex value for $myColour.";The output will look something like this:
Debugging: Error while compiling SCSS: File (unknown file) on line 224 ERROR: "blue is not a valid hex value for $myColour."
: line: 224, column: 1 in
* line 1537 of \lib\outputlib.php: call to debugging()
* line 1191 of \lib\outputlib.php: call to theme_config->get_css_content_from_scss()
* line 212 of \theme\styles.php: call to theme_config->get_css_content()
* line 178 of \theme\styles.php: call to theme_styles_generate_and_store()Finding the output log
You may be wondering, where do the debug, warning and error messages go?
You may have noticed that @debug and @warn messages, as well as SCSS compiler messages, don’t appear in Moodle LMS, even with debugging cranked up to the maximum DEVELOPER mode. Hopefully, this issue will be resolved in the future. Until then, you will find the output for all SCSS compilations in your webserver’s error log. This also includes general compiler errors.
@error is a little different. To see its output, turn the Moodle debugging up to DEVELOPER mode and its output will be found in the PHP error logs.
It is a good idea to keep your code clean and remove unconditional @debug, @warn and @error directives when you finish troubleshooting your code. This is because these directives will ALWAYS output messages to your error log, or stop compiling in the case of @error, even when Moodle LMS’ debugging is set to NONE. It is not the end of the world if you don’t though if you forget to do this since these only produce output during the SCSS compilation process and not during the normal day-to-day operation of Moodle LMS.
A few useful SCSS debugging tips
You may have noticed that the messages we showed so far indicate (unknown file). This is because Moodle LMS first combines all of the SCSS and then compiles it, at which point the compiler has no idea where the code came from
Did you know? Some SCSS functions will unexpectedly sometimes return colour names or rgba values instead of hex colours when you least expect it. This is a great example of a situation where @debug and @warn would come in handy to confirm the value of variables containing the colour. Of course, there are many other uses for these directives.
Always combine some text with the value in your variable. That way, you will know that your @debug or @warn line was executed, even if the variable is empty.
I am unsure if it is a bug, but compiling SCSS with an @debug and an @warn will cause Moodle to fail to compile the SCSS.
Remember, these directives are your trusty companions in the world of SCSS. They’ll guide you, warn you, and even shout if necessary. Use them wisely, and your SCSS stylesheets will be all the better for it!
Hope you find this information useful. See you next month!
Michael Milette
- Debugging SCSS in Moodle LMS – 23rd April 2024
- Moodle LMS Email Deliverability in 2024: Best Practices, Authentication Standards and Troubleshooting – 23rd February 2024
- Terminology for Those New to Moodle LMS – 20th January 2024
Very interesting post !
I did not know that this wouldn’t be output to the Moodle debugging GUI – so even that is really useful information – thanks 🙂