Prototype design

Reasoning for design choices

Our prototype is in another castle!

HTML5, CSS, JavaScript

As a small team, at least initially, we cannot afford to waste time rewriting the same software as native apps in different languages for different platforms. One codebase allows fast iteration. And perhaps later we can use tools like Phonegap to wrap the project into a mobile app if necessary.

Target platforms

We aim to use modern HTML5 features with little legacy baggage. Developer resources are prioritized higher than compatibility with old phones. Versions are based on necessary browser capabilities.

Browsers

• Firefox >= 3.5 (localStorage)
• Chrome >= 4.0 (localStorage)
• IE >= 8.0 (localStorage)
• Safari >= 4.0 (localStorage)
• Opera >= 10.5 (localStorage)

Mobile OSs

Stock browsers:

• Android >= 2.1 (localStorage)
• iOs >= 3.2 (localStorage)
• Windows Phone >= z
• Jolla?

License

Currently it's set to EUPL v1.2 or AGPL v3. The former has not been published yet, though.

Language

CoffeeScript compiles to readable JavaScript and offers a more concise and less bracey JavaScript development experience. CoffeeScript provides some safeguards and modern syntax tricks. Despite its lax specification we, like many others, have found it useful. There are many other tools to avoid writing raw JavaScript, though.

Third-party components

Libraries

• jQuery
  • A library to simplify client-side scripting.
  • License: MIT.
• jQuery Mobile
  • A library for single-page applications.
  • Includes CSS.
  • License: MIT.
• Underscore.js, Lo-Dash or Lazy.js
  • Functional programming libraries for JavaScript. Underscore.js is the most well-known and uses the browser's native capabilities, if present. Lo-Dash can act as a replacement for Underscore.js. Lo-Dash does not use native implementations as it runs faster than them in current tests. In some cases Lazy.hs is faster than the other two by a magnitude.
  • Currently we use Underscore.js.
  • Currently of little use!
  • License: MIT.
• Backbone.js
  • A model–view–presenter framework.
  • Possibly useful for avoiding callback hell.
  • Backbone.js depends on Underscore.js.
  • Full features of Backbone.js also require a DOM manipulation library, e.g. jQuery, and json2.js. json2.js is required for JSON.stringify() in Backbone.sync() if the browser does not support it natively.
  • Currently of little use!
  • License: MIT.
• Handlebars.js
  • Semantic templates for JavaScript. Think of smart C macros.
  • FIXME: Completely unused currently! Should this be removed for now?
  • License: MIT.
• Leaflet
  • Leaflet provides an interface for interactive maps.
  • Includes CSS.
  • License: BSD 2-Clause.
• Leaflet.label
  • An officially supported plugin for Leaflet.
  • Adds labels for markers.
  • Includes CSS.
  • License: MIT.
• Leaflet.awesome-markers
  • A plugin for Leaflet.
  • Provides markers with easy to recognize icons based on Font Awesome/Twitter Bootstrap icons.
  • Includes CSS.
  • License: MIT.
• Leaflet OSM Notes
  • Pull OpenStreetMap notes on Leaflet to show user-reported issues.
  • FIXME: Is this what we use for reporting issues to OSM as well?
  • License: Public Domain (Unlicense).
• Faye
  • A publish-subscribe messaging system.
  • We use it to broadcast realtime locations of relevant vehicles to the clients.
  • License: MIT.
• Moment.js
  • A "date library for parsing, validating, manipulating and formatting dates".
  • Used to calculate travel times, at least.
  • License: MIT.

Building

• Buildout
  • A build system written in Python.
  • We use it to install Robot and Selenium2Library.
  • We use the current version 2.
  • Relevant files:
    • buildout.cfg describes what to do.
    • bootstrap.py executes on the contents of buildout.cfg.
  • License: ZPL v2.1. It's not copyleft.
• npm
  • The node.js package manager.
  • We use it to install the development environment.
  • Relevant files:
    • package.json describes the project version, license and dependencies, for example.
  • License: MIT.
• Grunt
  • A task runner. Used for building and running tests while developing.
  • For interaction with other tools we also use these plugins:
    • grunt-contrib-watch
    • grunt-contrib-coffee
    • grunt-contrib-connect
    • grunt-exec
    • grunt-testem
  • Relevant files:
    • Gruntfile.coffee is similar to a makefile and handles all of the configuration.
  • License: MIT.

Testing

• Chai
  • Chai describes itself as an assertion library for JavaScript offering should, expect and assert style functions.
  • Thus far we have used the should functionality.
  • License: MIT.
• Mocha
  • Mocha is a test framework that can utilize Chai, for example. Tests are run serially even for asynchronized code so that failures and exceptions are mapped to correct tests. Mocha supports several interfaces of testing functions for different testing cults.
  • We use BDD style, i.e. describe(), it(), before(), after(), beforeEach() and afterEach().
  • Relevant files:
    • tests/*.coffee are listed in Gruntfile.coffee.
  • License: MIT.
• Selenium
  • A testing tool to automate interaction with a browser. One can record or write scripts of quite realistic browser user interaction with a website, such as clicking things or filling forms. Asserts can be set for certain texts in the navigated pages, for example. The scripts can then be played and assertions checked automatically.
  • Relevant files:
    • tests/selenium.robot describes the Selenium configuration for other Robot test files.
  • License: Apache v2 License.
• Robot Framework
  • A keyword-driven test framework: write imperative test programs using keywords that some test library for Robot can understand and execute. The keywords tend to act like functions and are given test data as arguments.
  • Selenium2Library is a Selenium test library for Robot.
  • Relevant files:
    • Grunfile.coffee describes how Robot tests are run via Sauce Labs while developing.
    • tests/*.robot are the test files.
    • tests/selenium.robot specifically describes the Selenium configuration for other Robot test files.
  • License: Apache v2 License.
• Testem
  • Test runner for either running tests manually or running them on each commit.
  • We use it for running Mocha tests while developing and before pushing to GitHub.
  • License: MIT.
• PhantomJS
  • Scriptable, headless WebKit that can be used for testing.
  • Currently in use.
  • Relevant files:
    • Gruntfile.coffee has PhantomJS set as the browser for local desktop testing.
  • Integrates with Mocha.
  • License: BSD 3-Clause.
• saucelauncher
  • "A command line browser launcher for SauceLabs"
  • We use it with Grunt to run Testem on Sauce Labs.
  • License: Unknown.

Interesting libraries not yet used

• RequireJS
  • Loads JavaScript libraries as needed instead of everything right away.
  • Handles dependencies.
  • For Grunt integration there is grunt-contrib-requirejs or grunt-requirejs. The latter also supports almond.
  • License: BSD 3-Clause or MIT.
• json2.js
  • If we would like to support other platforms than the ones that support native JSON parsing and we need Backbone.sync(), we should include json2.js.
  • License: Public Domain (Custom).
• chai-backbone
  • Backbone.js-specific assertions for testing routing, for example.
  • License: MIT.
• Prefill
  • "guess which stop areas to prefill in a journey planner front-end"

Services

Testing

• Travis CI
  • Travis CI ensures continuous integration by automatically running tests for each commit pushed to GitHub.
  • "As a free community service, Travis CI limits build duration to about 20 minutes."
  • Relevant files:
    • .travis.yml
  • License: MIT. Not that we need to know.
• Sauce Labs
  • Sauce Labs runs different operating systems, also mobile OSs, and browsers for cross-platform testing.
  • Integrates with Selenium.
  • Experimental, alpha-quality integration with Mocha.
  • They offer a free trial.

Geocoder

• Nominatim used by OpenStreetMap (OSM)
  • Nominatim does not support autocomplete or suggestion features. Nor does OSM allow trying to implement such features by using their resources. There are plans for creating the features, though.
  • Many house numbers are missing from the OSM data. Perhaps Väestörekisterikeskus (VRK) could help as they collect all the geocoding data from all of the Finnish municipalities.
• Open MapQuest Nominatim v1 API
  • Offers some kind of fuzzy search. Perhaps it removes common place names like katu, tie or tori before the search.
  • Also automatic removal of diacritics.
• Open MapQuest Geocoder API
  • FIXME: Haven't tested it yet.
• CloudMade Geocoding v3 API
  • Offers a fuzzy and a hybrid (structured + fuzzy) search.
  • FIXME: Haven't tested it yet.
• Google Geocoding API
  • FIXME: Restrictions?
  • The data is not open.
• Maanmittauslaitos (National Land Survey of Finland) (MML)
  • The data in their map services is partly interpolated and thus slightly inaccurate. For example "Joonaksenkuja 5, Helsinki" or "Turuntie 2, Helsinki" are not available. There seems to be no API for that data, either.
  • The interface MML built in collaboration with VRK for the accurate addresses is not gratis to use and the data is not available as an open data dump.
• Code for Europe Geocoder
  • Built for us. Perhaps later we would like to offload this work to OSM where it seems to fit.

Maps

• OpenStreetMap
  • A site and a service for open map and address data.
  • Uses vibrant colors. Considering that we are going to use colored lines to represent routes, we might prefer more subdued colors for the underlying map.
• OpenCycleMap
  • The OpenStreetMap Cycle Map.
  • Cycle paths are marked clearly but the colors are very intense.
• CloudMade
  • CloudMade uses primarily map data from OpenStreetMap but offers a restrained color palette. Possibly other palettes are available.
• MapQuest
  • Seems to emphasize major roads.
  • FIXME: Are we getting OpenStreetMap data here, too?
• Google Maps
  • We do not use these currently.
  • FIXME: Restrictions?
  • The data is not open.

Test setup

In general, Mocha scripts use Chai as their assertion library. Testem runs the Mocha scripts in one or more "launchers". Some of the launchers are locally installed browsers, some of them are remote mobile platforms on Sauce Labs servers. Robot runs the Selenium tests on an array of platforms at Sauce Labs, as well.

Grunt handles any local building and testing explicitly instigated by the developer. Travis CI will automatically do more-or-less the same for commits pushed to GitHub.

Current Grunt commands:

`grunt'             builds the project.
`grunt server'      opens a server on localhost and keeps rebuilding after changes to source files.
`grunt test'        leads to Grunt -> Testem -> Mocha -> Chai.
`grunt test-mobile' leads to Grunt -> Testem -> Sauce Labs -> Mocha -> Chai.
`grunt test-robot'  leads to Grunt -> Robot -> Sauce Labs -> Selenium.

FIXME: Describe Travis CI behaviour.