Client & UI development

AngularJS
Style guide
Performance profiling
Grunt
Tasks
Watch
Running tests on host

AngularJS

Performance profiling

AngularJS is known to slow down the more watchers are active. As it is not always obvious where an how many watchers are active it can be helpful to have a tool visualizing the number of watchers. ngStats does exactly this and furthermore shows the time it takes for Angular to go through one digest cycle.

Include ngStats with Chrome Snippets

Open Chrome's dev tool bar
Go to sources/snippets
Create a new snippet called ng-stats: module, paste the code from dist/ng-stats.js from the repo and hit save (CMD + S).
Create another snippet called ng-stats: run, paste the following and hit save (CMD + S).
```
var ngStats = showAngularStats({
  position: 'bottomright'
});
```
Create a third snippet called angular-js: dev mode, paste the following and hit save (CMD + S).
```
angular.reloadWithDebugInfo();
```
Open Refinery (http://192.168.50.50:8000) and run the snippets in the following order
1. angular-js: dev mode
2. ng-stats: module
3. ng-stats: run

Grunt

Grunt is the main task runner for Refinery's front-end application.

Grunt tasks

grunt compile Standard task to use.
grunt build Only used in conjunction with grunt watch.
grunt make Helper task for uglify:vendorAssets, grunt compile and grunt build.
grunt test Run unit tests.
grunt Helper tasks for grunt test and grunt make.
grunt watch Watches UI source files and sends a reload event to the browser is something changed.
grunt lint:custom --files='<GLOB>' Lints custom files given the globbing, e.g. grunt lint:custom --files='source/js/global/**/*.js'
grunt esformatter --files='<GLOB>' Auto-formats files given the globbing, e.g. grunt esformatter --files='source/js/global/**/*.js'

grunt compile is the main task, which does all the heavy lifting to get the front end application ready for production use. This includes copying files to the production directory, minifying and concatenating, including source map creation, as well as translating less to CSS and adding vendor prefixes. Before reporting bugs please make sure you ran this task.

grunt build is the smaller brother of compile. It only does as little as possible to get the front end application running. This basically means that no files are minimized and no vendor prefixes are added to CSS.

grunt uglify:vendorAssets is separated from compile and build as it uglifies third party files only and and needs to run just once before compile and build.

grunt watch is the reason for grunt build. This tasks is watching all source files and re-runs certain parts of grunt build automatically when changes are being made and triggers a page reload.

grunt test --files='GLOB' can be used to run Karma against a restricted number of tests. E.g. grunt test --files='source/js/dashboard/**/*.spec.js'

grunt eslint:custom can be used to lint a subset of files. Can be handy for batch linting. Note: that grunt eslint lints everything!

grunt esformatter can be used to format JS files in an automated fashion. Since format will be edited in-place it might be a good idea to not run this command on the whole source code at once.

Grunt watch

Run fab vm conf:gdev on the host, then cd ui, run grunt watch, point Chrome to 192.168.50.50:8000 and activate the LiveReload plugin. Now every time you make a change Chrome will automatically be reload by Grunt.

Options:

--autoprefix Explicitly turns on auto-prefixing for grunt build and grunt watch. This can be useful when visual bugs are observed, e.g. Safari <= 8 doesn't support vendor-free translate3d.
--fast Only runs the linter on files that actually changed, making JS-related iterations much faster.

Note:

Make sure to have Grunt's CLI installed on your host machine, which requires Node.js with NPM.
Be sure that you start Grunt on your local file system and not from within the VM.

Why are there two separate tasks for compiling and building?

The build task does as little as possible that is needed to get Refinery up and running, e.g. translating LESS into CSS and copying JS files to their appropriate directory. These tasks is usually very fast, while computationally more challenging tasks like minimized are omitted to make grunt watch as responsive as possible.

Running tests on host

Currently, unit tests are executed by PhantomJS, a headless WebKit browser, on the VM. While PhantomJS is flexible solution, it might be good to evaluate tests in other browsers too.