Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Grunt: Difference between revisions

From MoodleDocs
(Consolidate grunt installation documentation)
(2 intermediate revisions by 2 users not shown)
Line 4: Line 4:


== Install grunt ==
== 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 "[http://gruntjs.com/ grunt]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment. This means you first have to install nodejs - and it's package manager "[https://www.npmjs.com/ npm]". The details of how to install those packages will vary by operating system, but on Linux it's likely to be:
javascript and CSS in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[http://gruntjs.com/ grunt]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment. You will need to install NodeJS and the Grunt tools. For documentation on this process see [[Javascript_Modules#Install_grunt]].
apt-get install nodejs npm
See also: [http://askubuntu.com/questions/594656/how-to-install-the-latest-versions-of-nodejs-and-npm-for-ubuntu-14-04-lts/711976 how to install the latest version of nodejs and npm for ubuntu 14.04]
 
There are downloadable packages for other operating systems here: http://nodejs.org/download/.
 
Once this is done, cd into your Moodle directory and run the command:
npm install
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 ==
== Running grunt ==
Line 34: Line 23:




On Linux/Mac it will build everything in the current folder and below. You need to cd into the amd folder of your module root, i.e. <tt>dirroot/blocks/foo/amd</tt> before running <tt>grunt amd</tt> - this will compile only your plugins AMD source files. You can make output more verbose by adding <tt>-v</tt> parameter, if used with <tt>grunt shifter</tt> this will actually show what your lint errors are. On Windows, you need to specify the path on the command line like <tt>--root=admin/tool/templatelibrary</tt>.
On Linux/Mac it will build everything in the current folder and below. You need to cd into the amd folder of your module root, i.e. <tt>dirroot/blocks/foo/amd</tt> before running <tt>grunt amd</tt> - this will compile only your plugins AMD source files. You can make output more verbose by adding <tt>-v</tt> parameter, if used with <tt>grunt shifter</tt> you will have to cd into the <tt>module/yui/src</tt> folder, and to show what your lint errors are you can also use the <tt>-v</tt> parameter. On Windows, you need to specify the path on the command line like <tt>--root=admin/tool/templatelibrary</tt>.


== Using Grunt in additional plugins ==
== Using Grunt in additional plugins ==
Line 116: Line 105:
* [[Javascript Modules]]
* [[Javascript Modules]]
* [[LESS]]
* [[LESS]]
* [https://moodle.org/mod/forum/discuss.php?d=400229#p1614743 Bitbucket pipeline to build YUI JS]


[[Category:AJAX]]
[[Category:AJAX]]
[[Category:Javascript]]
[[Category:Javascript]]

Revision as of 03:15, 27 May 2020

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

javascript and 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. You will need to install NodeJS and the Grunt tools. For documentation on this process see Javascript_Modules#Install_grunt.

Running grunt

Typical commands:

grunt amd               # Short-cut for grunt jshint 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
grunt eslint --show-lint-warnings # Show pedantic lint warnings for JS


On Linux/Mac it will build everything in the current folder and below. You need to cd into the amd folder of your module root, i.e. dirroot/blocks/foo/amd before running grunt amd - this will compile only your plugins AMD source files. You can make output more verbose by adding -v parameter, if used with grunt shifter you will have to cd into the module/yui/src folder, and to show what your lint errors are you can also use the -v parameter. 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 grunt-load-gruntfile

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) {

   // We need to include the core Moodle grunt file too, otherwise we can't run tasks like "amd".
   require("grunt-load-gruntfile")(grunt);
   grunt.loadGruntfile("../../Gruntfile.js");
   // 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