|
|
| Line 1: |
Line 1: |
| {{Moodle 2.9}} | | {{Template:Migrated|newDocId=/general/development/tools/nodejs}} |
| | |
| 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 "[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]].
| |
| | |
| == 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. <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>.
| |
| | |
| === Watchman installation ===
| |
| If you get an error when running "grunt watch" complaining about 'watchman', you most likely need to install it. Check out the [https://facebook.github.io/watchman/docs/install.html watchman installation] page. For example, [https://facebook.github.io/watchman/docs/install.html#installing-from-source installing from source in Linux/Mac]:
| |
| $ git clone https://github.com/facebook/watchman.git -b v4.9.0 --depth 1
| |
| $ cd watchman
| |
| $ ./autogen.sh
| |
| $ ./configure
| |
| $ make
| |
| $ sudo make install
| |
| | |
| | |
| If you're on Linux, you may also want to make sure that fs.inotify.max_user_watches is set in /etc/sysctl.conf (e.g. <syntaxhighlight lang="php">fs.inotify.max_user_watches = 524288</syntaxhighlight>) then reload (e.g. <syntaxhighlight lang="php">sudo sysctl -p</syntaxhighlight>).
| |
| | |
| == 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:
| |
| | |
| <syntaxhighlight lang="javascript">
| |
| "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"]);
| |
| };
| |
| </syntaxhighlight>
| |
| | |
| 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 [http://gruntjs.com/configuring-tasks#building-the-files-object-dynamically expand:true feature] of gruntfile.js:
| |
| | |
| <syntaxhighlight lang="javascript">
| |
| // This dynamically creates the list of files to be processed.
| |
| files: [
| |
| {
| |
| expand: true,
| |
| cwd: "less/",
| |
| src: "*.less",
| |
| dest: "style/",
| |
| ext: ".css"
| |
| }
| |
| ]
| |
| </syntaxhighlight>
| |
| | |
| == See also ==
| |
| * [[YUI/Shifter]]
| |
| * [[Javascript Modules]]
| |
| * [[LESS]]
| |
| * [https://moodle.org/mod/forum/discuss.php?d=400229#p1614743 Bitbucket pipeline to build YUI JS]
| |
| | |
| [[Category:AJAX]]
| |
| [[Category:Javascript]]
| |
