Skip to content

Prototype design

Jump to bottom Edit New page
haphut edited this page Jul 24, 2013 · 14 revisions

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.

Browsers

  • Firefox >= x
  • Chrome >= y
  • IE >= z
    • IE has only recently started following web standards.
  • Safari >= Ƒ
  • Opera >= §

Mobile OSs

  • Android >= x
  • iOs >= y
  • 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
  • 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

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.

Interesting libraries not yet used

  • RequireJS
    • Loads JavaScript libraries as needed instead of everything right away.
    • Handles dependencies.
    • 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.

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[1][2] 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 supporting such features, though.
    • Many house numbers are missing from the OSM data. Perhaps Väestörekisterikeskus could help as they collect all the geocoding data from all of the Finnish municipalities.
  • Google Maps (GM)
    • GM wants moolah?
    • Are there restrictions for use?
    • The data is not open.
  • Maanmittauslaitos (National Land Survey of Finland) (MML)
    • Their data is partly interpolated. They are interested in geography, not addresses.
  • 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?

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.

Add a custom footer
Add a custom sidebar
Clone this wiki locally