Grunt

Moodle 2.9

Grunt is a command line tool used to prepare our javascript and less-generated css for production usage. After making any change to javascript or less files in Moodle, you must run grunt to lint, minify and package the javascript/css properly so that it can be served by Moodle.

Install grunt

The Javascript modules (AMD and YUI) and less css in Moodle must be processed by some build tools before they will be visible to your web browser. We use "grunt" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "nodejs" environment. This means you first have to install nodejs - and it's package manager "npm". The details of how to install those packages will vary by operating system, but on Linux it's likely to be:

apt-get install nodejs npm

There are downloadable packages for other operating systems here: http://nodejs.org/download/. Once this is done, you can run the command:

npm install

from the top of the Moodle directory to install all of the required tools.

You also need to install the grunt-cli package globally in order to have a "grunt" command in your path. To do this run:

npm install -g grunt-cli 

Running grunt

Typical commands:

grunt amd               # Short-cut for grunt jshit uglify, rebuild all AMD modules.
grunt shifter           # Run shifter
grunt js                # Short-cut for grunt amd shifter

grunt css               # Run less
grunt                   # Try to do the right thing:
                        # * If you are in a folder called amd, do grunt amd
                        # * If you are in a folder called yui/src/something, do grunt shifter
                        # * Otherwise build everything (grunt css js).

grunt watch             # Watch for changes and re-run grunt tasks depending on what file changes

On Linux/Mac it will build everything in the current folder and below. On Windows, you need to specify the path on the command line like --root=admin/tool/templatelibrary.

Using Grunt in additional plugins

You may want to use Grunt for performing tasks in your custom Moodle plugins. For building AMD and YUI modules in your plugin, the standard configuration Gruntfile.js located in the Moodle root should work well. For building CSS files from LESS templates, you will have to set up a separate Grunt installation in the root of your plugin.

If you do not have it yet, create the package.json file in the root of your plugin:

   {
       "name": "moodle-plugintype_pluginname"
   }

Install grunt, grunt less and grunt watch modules. Note that you should put the folder node_modules into your plugin's .gitignore file, too.

   $ cd /path/to/your/plugin/root
   $ npm install --save-dev grunt grunt-contrib-less grunt-contrib-watch

Create a Gruntfile.js in the root of your plugin and configure the task for building CSS files from LESS:

"use strict";

module.exports = function (grunt) {

   // Load all grunt tasks.
   grunt.loadNpmTasks("grunt-contrib-less");
   grunt.loadNpmTasks("grunt-contrib-watch");
   grunt.loadNpmTasks("grunt-contrib-clean");

   grunt.initConfig({
       watch: {
           // If any .less file changes in directory "less" then run the "less" task.
           files: "less/*.less",
           tasks: ["less"]
       },
       less: {
           // Production config is also available.
           development: {
               options: {
                   // Specifies directories to scan for @import directives when parsing.
                   // Default value is the directory of the source, which is probably what you want.
                   paths: ["less/"],
                   compress: true
               },
               files: {
                   "styles.css": "less/styles.less"
               }
           },
       }
   });
   // The default task (running "grunt" in console).
   grunt.registerTask("default", ["less"]);

};

Now running "grunt" or "grunt less" in your plugin root folder will compile the file less/styles.less and saves it as styles.css. Running "grunt watch" will watch the less/*.less files and if some is changed, it will immediately rebuild the CSS file.

If you are working on a custom theme, you may have multiple less/*.less files that you want to compile to their style/*.css counterparts. You can either define an explicit list all such file pairs, or let that list be created for you by making use of expand:true feature of gruntfile.js:

// This dynamically creates the list of files to be processed. files: [

   {   
       expand: true,
       cwd: "less/",
       src: "*.less",
       dest: "style/",
       ext: ".css"
   }   

]

See also

• YUI/Shifter
• Javascript Modules
• LESS