Skip to content

Latest commit

 

History

History
109 lines (71 loc) · 6.19 KB

developer.md

File metadata and controls

109 lines (71 loc) · 6.19 KB

Developer Instructions

Setup for Development Stack

The implementation uses the following technologies:

  • Maven for builds, tests and IDE integration
  • Closure compiler
  • Closure library
  • Closure templates (aka Soy templates)
  • D3.js visualization library
  • jsTestDriver

The following sections explain how the dev-stack is setup and how you can build the project for production or during development (having fast way how to test javascript code in browser or manually is always good without need to compile whole code).

Google Closure, Soy templates and jsTestDriver are all very interesting and powerful technologies. However, despite the fact that all three are developed by Google they are not really integrated. Setting up automated and smooth dev-stack on top of it (from the POW of Java developer - who is mostly used to Maven or Ant and IDEs like Eclipse or IDEA) is not very straightforward task.

Building the application

  • Production: When building production artifact, it is all automated and driven by Maven only (including automated javascript tests).
  • Local development: When you need to quickly open the application without compilation then all you have to do is to execute one or two shell scripts and then you can open index.html in browser.

Closure Tools Version

It is important to keep versions of individual parts of Closure Tools that are used during development in the sync.

By Closure compiler version we mean release number as defined for Maven use: https://github.com/google/closure-compiler/wiki/Releases

Maven Plugin

ClosureJavascriptFramework Maven plugin is used to compile javascript source code. Specific version of Closure compiler used by this Maven plugin is set in pom.xml in property ${closure.library.version}.

Unit Testing via jsTestDriver

Tests are implemented using jsTestDriver. These tests are pure JavaScript executed in (captured) browser so we need to make sure browser can load needed parts of Closure library code. But Closure library is not "officially" released as a zip file, so the only option is to checkout source code directly from Closure library repository.

The other option is to download zip file from closure-library which is used by ClosureJavascriptFramework.

Then it is important to make sure correct paths are used in jsTestDriver.conf:

load:
  - closure-library-99cd91/closure/goog/base.js
  - ... etc

Keep jsTestDriver.conf Updated

To get updated list of required Closure library code for the jsTestDriver.conf just execute the printJSTDdeps.sh.

The script will print out list of JS scripts in correct order. Just copy and paste this list into jsTestDriver.conf into load: section. If you are using other third-party js libraries (like D3.js for instance) then make sure you add them manually.

Testing Manually in Browser

If you want to load the application into browser and test/play with it manually then use searchForTesting.sh or profileForTesting.sh scripts. When executed it builds search-testing-only.js or profile-testing-only.js which are referenced from index.html and profile.html respectively.

Tip for IntelliJ IDEA users: Generated *-testing-only.js files can be huge (this file is without any optimizations) and as soon as they are generated, IntelliJ IDEA tries to parse them. This can take some time and IDE gets frozen until it is done with parsing. While these files are really not needed for any code completion it makes sense to use Mark as Plain Text option from context menu.

Code Style Checking with gjslint

For gjslint install instructions see howto. Once installed IntelliJ IDEA users can enable it in Preferences > JavaScript > Code Quality Tools > Closure Linter.

For example on Mac systems the gjslint is by default installed under /usr/local/bin/gjslint. Configuration file gjslint.conf is located in the project root. Check gjslint --help for more options.

Closure Templates

To compile Closure templates (aka Soy Templates) into JavaScript run compileClosureTemplates.sh.

It grabs all templates from /src/main/soy_templates folder and compile them into src/main/javascript_source/generated_templates/ folder which makes them available for Maven plugin (the Maven plugin requires all JS sources to be located under javascript folder).

Note the soyutils_usegoog.js script in src/main/javascript_source/soyutils_slink. It is a symbolic to closure-templates-2011-22-12/soyutils_usegoog.js. This script is actually required by compiled templates so we had to mirror it under javascript_source folder to make sure:

  1. Maven plugin can find it during javascript compilation.
  2. Configuration of closurebuilder.py --root argument in shell scripts is kept simple.

Updating Closure Templates

Important, before you start, verify if upgraded version of Closure library is also needed!

  • Go http://code.google.com/p/closure-templates/downloads/list and see if new version has been released. We are interested in closure-templates-for-javascript-*.zip files.
  • Extract to src/closure-template-YYYY-MM-DD folder.
  • Update src/main/javascript_source/soyutils_slink to point to the new closure-templates-YYYY-MM-DD/soyutils_usegoog.js (see example below).
  • Finally, update compileClosureTemplates.sh.

For example:

cd src/main/javascript_source
rm -rf soyutils_usegoog.js
ln -s ../../../closure-templates-2012-12-21/soyutils_usegoog.js soyutils_usegoog.js

TODO - Automatic Building of Soy Templates

Configure automatic execution of build scripts from within IntelliJ IDEA. Whenever you change content in /src/main/soy_templates folder compile them in the background. As a result compiled templates will be in sync with soy files and both will be stored in the code repository.

HOWTO - http://www.jetbrains.com/idea/webhelp/external-tools.html