Build Tool Setup

Dependencies

The build tool uses Grunt for automation of linting, minifying, concatenating and other magical things we do with our JS and CSS files.

To install Grunt on Windows, you first need to install Node.js and Git binary, and then you can use the command prompt or PowerShell to run Grunt tasks.

After installing the dependencies, run the following in your command shell as Administrator

$ npm install -g grunt-cli

This will add the grunt command in your system path, allowing it to be run from any directory. You might want to restart your machine, just in case.

Build Tool

The build tool is just a Grunt project set up to automate the processing of the template, JS and CSS files before deployment. It also outputs the English and French versions of the main page template for both WET Government of Canada Intranet and Government of Canada Web Usability themes using supplies locale strings and templates.

The Build tool can also

Structure

There are two files required to configure and run the build tool: package.json and Gruntfile. They resided in RAMP at the root level.

package.json: stores metadata for the project; defines the list of Grunt plugins needed;

Gruntfile: configures and defines tasks;

Apart from these two files, there is also the node_modules folder in the root of RAMP containing Grunt modules which will be pulled from GitHub when you run npm install in the next section.

You can read more about Grunt projects here

Running the Build Tool

To run the build tool do the following:

  1. Open Command Prompt or PowerShell
  2. Change to the project’s root directory
  3. Use npm install to install project dependencies (need to run only once or when adding new modules)
  4. Use the following to run the build tool:
$ grunt

if you get an error that something is not found, try running npm install again.

Default Task

Unless you specify a task to run, grunt command runs cleanAll, css, js, page and assets tasks and they will

  1. increment the project’s version build number;
  2. convert LESS files from RAMP\src\css to CSS, add browser-specific prefixes to CSS files in RAMP\src\css, minimize CSS, and copy them to RAMP\buildcss__; concatenate CSS libraries located in __RAMP\src\css\lib, and copy the resulting lib.min.css to RAMP\build\css\lib;
  3. run JSHint on all JS source files – the default build task will fail if there are any errors present; uglify JS files from RAMP\src\js\RAMP and move them to RAMP\build\js\RAMP; uglifiy modified/pretty JS libraries from RAMP\src\js\lib, concatenate them with other, already uglified JS libraries and copy the resulting lib.min.js file to RAMP\build\js\lib; copy templates from RAMP\src\js\RAMP\Modules\templates to RAMP\build\js\RAMP\Modules\templates;
  4. output English and French versions of the content template file (src/ramp-src.html) by replacing placeholders with provided locale strings and applying templates from theme foldes in src\pages\ramp-gcwu-intranet and src\pages\ramp-gcwu-fegc; save them as in the build folder;
  5. generate API documentation using YUIDoc and annotated source code documents using Docco and save them in “docs/docco” and “docs/yuidoc” folder

–source

To generate source mappings for the core JS files, use source option as follows:

$ grunt --source

Other Tasks

The default task calls the three main build tasks and if you don’t want to build everything at once all the time, you can call any of the of build tasks individually. You can also call any of the utility tasks defined in the Gruntfile. You can do that by using

$ grunt <task-name>

api

Generate API documentation using YUIDoc and annotated source code documents using Docco and save them in “docs/docco” and “docs/yuidoc” folder. Use the following to run this task:

$ grunt api

bump

Increments the project’s version number in files package.json and yuidoc.json. Use the following to run this task:

$ grunt bump
>> Version bumped to 0.0.2

$ grunt bump:patch
>> Version bumped to 0.0.3

$ grunt bump:minor
>> Version bumped to 0.1.0

$ grunt bump:major
>> Version bumped to 1.0.0

$ grunt bump:build
>> Version bumped to 1.0.0-1

Everytime the default or css, js, page tasks are run, bump-only:build is also ran as well.

cleanAll

Removes all temporary and build folders:

Use the following to run this task:

$ grunt cleanAll

css

Converts LESS, prefixes CSS, minifies and copies the resulting CSS files to the build/css folder. Use the following to run this task:

$ grunt css

Note: You need to run this task every time you modify any *.less files since the browser cannot interpret them directly and no changes will be reflected in rendering of the page. It’s best to use wcss or watch task to auto-convert LESS to CSS on every change.

deploy

Runs the build and then copies only the necessary files to a specified location leaving out source folders. This task will fail if there are any JS errors present. Use the following to run this task:

$ grunt deploy

Note: The target folder is cleaned prior to copying files.

hint

Runs JSHint on all JS files in RAMP/src/js/RAMP/. Use the following to run this task:

$ grunt hint
–target / -tr

To lint a specific JS file, use the –target or its shortcut -tr options and specify the path to the file relative to RAMP/src/js/RAMP/:

$ grunt hint --target=Modules/datagrid.js
$ grunt hint -tr Modules/datagrid.js
–output / -o

To lint a specific JS file, use the –target or its shortcut -tr options and specify the path to the file relative to RAMP/src/js/RAMP/:

$ grunt hint --output=jsHintErrors.my
$ grunt hint -o jsHintErrors.my

js

JShints, uglifies, concatenates, and copies the resulting JS files and templates to the build/js folder. This task will fail if there are any errors present. Use the following to run this task

$ grunt js
–source

To generate source mappings for the core JS files, use source option as follows:

$ grunt js --source

page

Outputs English and French versions of the content template file (ramp-src.html) for both themes by replacing placeholders with provided locale strings; saves them into the build folder. Certain sections in the tempate file will be replaced:

head.wetCss
<!-- build:section head.wetCss -->
    ...
<!-- /build -->

is replaced by the content of the theme-specific file src/pages/[theme]/head.wetCss.html.

head.wetCss
<!-- build:style head.rampCssLib -->
    ...
<!-- /build -->

is replaced by the CSS reference to build/css/lib/lib.min.css.

head.rampCssCore
<!-- build:style head.rampCssCore -->
    ...
<!-- /build -->

is replaced by the CSS reference to build/css/[theme]/theme.less.min.css.

body.wetHeader
<!-- build:section body.wetHeader -->
    ...
<!-- /build -->

is replaced by the content of the theme-specific file src/pages/[theme]/body.wetHeader.html.

body.wetFooter
<!-- build:section body.wetFooter -->
    ...
<!-- /build -->

is replaced by the content of the theme-specific file src/pages/[theme]/body.wetFooter.html.

body.wetJs
<!-- build:section body.wetJs -->
    ...
<!-- /build -->

is replaced by the content of the theme-specific file src/pages/[theme]/body.wetJs.html.

body.rampJsLib
<!-- build:script body.rampJsLib -->
    ...
<!-- /build -->

is replaced by the JS reference to build/js/lib/lib.min.js.

body.rampJsCore
<!-- build:script body.rampJsCore -->
    ...
<!-- /build -->

is replaced by the JS reference to build/js/RAMP/RAMP-starter.js.

It reads two csv files containing English and French strings respectively from RAMP/src/assets/strings_en.csv and RAMP/src/assets/strings_fr.csv. The files are a simple set of key-values with the header of key,value. The build tool also loads the config file located at configFileLocation and mixes found stringResources with strings from the csv files. After that, it runs a replacement task on the content template, generating a language specific html files.

Saves the newly created files into the build folder.

Use the following to run this task:

$ grunt page

watch

watch is a shortcut to run wcss, wjs, wpage, and wtempate tasks. Use the following to run this task:

$ grunt watch

wcss

Watches all LESS files in RAMP/src/css/ and runs the css task on change. Use the following to run this task:

$ grunt wcss

wjs

Watches all JS files in RAMP/src/js/RAMP/ and runs the hint task on the changed file and then runs js task. Use the following to run this task:

$ grunt wjs
–target / -tr

To watch for a specific JS file, use the –target or its shortcut -tr options and specify the path to the file relative to RAMP/javascript/src/RAMP/:

$ grunt wjs --target=Modules/datagrid.js
$ grunt wjs -tr Modules/datagrid.js

wpage

Watches main HTML template file RAMP/src/ramp-src.html and all the theme-specific templates in src/pages folder; runs page task when changes are detected:

$ grunt wpage

wtempate

Watches all JSON files in RAMP/src/js/RAMP/Modules/Templates and copies them to the build folder when changes are detected. Use the following to run this task:

$ grunt wtempaltes

Config File - package.json

package.json contains the metadata about the build tool project, grunt dependencies to be installed and some of the variables used by the build tool such as various paths, folders, and file names. package.json is a pure JSON file (no comments, no unquoted strings, no multiline values allowed). All the variables related to the build tool stored in ramp object.

jsLibToUglify

A list of JS libraries’ files to be uglified, their paths relative to the lib folder in RAMP/src/js/. Since some of the libraries come in a non-uglified state and some of the libraries’ source code was modified by us, we need to uglify them before concatenating with other, already uglified JS libraries.

console.log, warn, etc. statements are removed during uglification.

jsLibToConcat

A list of JS libraries’ files to be concatenated together. Make sure you only include the uglified version of the files. This list must include all the files from the jsLibToUglify list with .min.js extensions instead of just .js.

jsLibResourcesToCopy (not used right now)

A list of JS libraries’ resources that need to be in the same folder as the main library file. They will be copied over to the RAMP/javascript/lib folder. Right now this list is empty.

jsExtraToCopy

A list of other JS libraries, or just files to be copied to the build folder without modifications.

cssLibToMinify

A list of CSS libraries’ to be minified, their paths relative to the lib folder in RAMP/src/css/. As with JS libraries, we modify some of the libraries’ CSS and they need to be modified before concatenation.

cssLibToConcat

A list of CSS libraries’ files to e concatenated together. Make sure you only include the minified version of the files. The list must include all the files from the cssLibToConcat list with .min.css extensions instead of just .css.

cssLibResourcesToCopy

A list of CSS libraries’ resources/assets like images, fonts, etc. that will be copied to the build/css/lib folder.

themes

A list of theme names corresponding to the folder names in the src/pages folder. Right now two themes are used: ramp-gcwu-fegc and ramp-gcwu-intranet.

pageToBuildEn

The suffix to be appended to the English version of the built page.

pageToBuildFr

The suffix to be appended to the French version of the built page.

assetsToCopy

A list of folders and files to be copied as part of the deploy task.

deployToFolder

A path to the deploy folder.

configFileLocation (not used right now)

Points to the config file to be harvested for locale strings. Can be either a local file (config.{lang}.json) or a remote url (http://sncr01wbingsdv1.ncr.int.ec.gc.ca/RAMP_Service/getConfig/{lang}/?keys=_). Make sure to leave {lang} in the file path instead of specifying a language. If it’s a remote url, make sure it returns pure JSON, not JSONP .

docco.path

A path to the JavaScript folder to be parsed.

docco.outdir

A path where to put generated documents.

yuidocconfig

The Config object for YUIDoc is located in yuidoc.json file. You can read about its structure here: http://yui.github.io/yuidoc/args/index.html

hintColors

Specifies the colors to be used by JSHint when outputting to the console; this property is in the root of package.json.

Grunt Modules

The build tool uses a number of Grunt-specific and general NPM modules. They are:

Other

Making your Grunt Snarl

To see sweet notification balloons when your Grunt wants to tell you that your task has failed (or when JS has been JShinted successfully, or when LESS has been converted to proper CSS), install Snarl from here: http://sourceforge.net/projects/snarlwin/files/latest/download?source=files

You don’t need to do anything else.

Adding JavaScript Library

To add a JavaScript library, do the following:

  1. create a folder in RAMP/src/js/lib/{library name}.{ library version}, and copy the library files into this folder;
  2. add the main uglified library file name(s) to the jsLibToConcat property in package.json file making sure the path is relative to the jsFolder property; if the library doesn’t have an uglified version, do step 3 even if you didn’t modify the library’s source;
  3. if you made changes to the library’s source file(s), add their names to the jsLibToUglify property of the package.json file; the build tool will create an uglified version with *.min.js extension;
  4. include the reference to the library’s source file(s) if you modified them and to main uglified file(s) if you didn’t in ramp-src.html between the comment tags:
  5. run the tool;

Adding CSS Library

To add a CSS library, do the following:

  1. create a folder in RAMP/src/css/lib/{library name}.{ library version}, and copy the library files into this folder;
  2. add the main minified library file name(s) to the cssLibToConcat property in package.json file making sure the path is relative to the cssFolder property; if the library doesn’t have an minified version, do step 3 even if you didn’t modify the library’s source;
  3. if you made changes to the library’s source file(s), add their names to the cssLibToMinify property of the package.json file; the build tool will create an minified version with *.min.css extension;
  4. include the reference to the library’s source file(s) if you modified them and to main minified file(s) if you didn’t in ramp-src.html between the comment tags:
  5. run the tool;

Making Cake

To have the build tool make you a cake, do the following:

  1. save a picture of the cake you want in RAMP/assets/images/cake.png;
  2. save the cake’s recipe in RAMP/assets/recipe.txt;
  3. spin three times on your chair clapping your hands and shouting “Cake”;
  4. use the command grunt cake
  5. enjoy your cake;

Troubleshooting

Task Not Found

If you get a “Task not found” error like this one:

Warning: Task "***" not found.  Use --force to continue.
Aborted due to warnings.

Run the npm install command again (you may want to delete the node_modules folder from the root, if it didn’t work after the first try, just in case):

Date modified: