Jarmon User Guide

Jarmon is a browser based graph rendering system.

Contents

1. Browser Compatibility
2. API documentation
3. Release process and tools
4. Running automated tests

Browser Compatibility

Jarmon depends upon the Flot graphing library which makes use of the HTML5 canvas element. The canvas element is only supported in certain web browsers.

Internet Explorer Caveats

Internet Explorer (<= IE8)

This version of IE does not have native support the HTML canvas (see Internet Explorer workarounds below) element.

Internet Explorer 9

Due to be released in late 2010 this new version of IE will provide native canvas support and will be able to render Jarmon graphs as fast (if not faster) than other browsers.

Internet Explorer Workarounds

Excanvas

This is the default IE compatibility workaround. Jarmon bundles the excanvas library which translates canvas api calls into VML, but this is much slower than the native canvas support in other browsers. In the absence of other workarounds, Jarmon will transparently use the excanvas library.

Chrome Frame

Chrome Frame is an IE plugin developed by Google. Once installed, it replaces the standard IE rendering module with the more performant Chrome rendering module.

When first visiting a Jarmon page using <= IE8, you will be prompted with an advisory message, explaining the performance penalty of using the standard excanvas compatibility layer.

You will be asked whether you want to Install and use Chrome Frame. You will be presented with the following options:

Yes

After you choose this option the message will be hidden and you will be guided through the steps necessary to install Chrome Frame after which you can continue to use Jarmon normally.

Remind me later

After you choose this option, the message will be hidden and you can continue to use Jarmon.

Your preference will be saved in a cookie and the warning message will not re-appear for 1 month.

Never

After you choose this option, the message will be hidden and you can continue to use Jarmon.

Your preference will be saved in a cookie and the warning message will never re-appear (unless the preference cookie is deleted or expires).

API Documentation

Jarmon includes comprehensive API documentation

This API documentation is generated automatically by the release command, but you can also build it yourself by issuing the ./bin/build apidoc command from within a Jarmon source tree. The documentation will be saved in a build subfolder.

Release Process and Tools

Jarmon includes tools to automate source archive releases. First check out the source code, then issue the ./bin/build -V 10.8 release command from within the source tree.

Running automated tests

Jarmon includes unit tests which are used to exercise the library code, to check for compatibility with various platforms and web client software and to check for regressions as the library evolves.

The unit tests are designed to be run inside a web browser using the YUI test harness.

1. Generate test data by running the following command ./bin/build testdata from within the source tree.
2. Start a web server to serve the test page. Eg $ nginx -p . -c docs/examples/nginx.conf.example
3. Use a web browser to load the test page ( http://localhost:8080/test.html)

Measure code coverage

There are number of tools available to measure the code coverage of Javascript unit tests.

One such tool is JSCoverage. It is very easy to install JSCoverage on a Debian / Ubuntu system and use it to measure the coverage of the Jarmon unit tests.

1. sudo aptitude install jscoverage - install jscoverage.
2. jscoverage-server - run the JSCoverage web server from the root of the Jarmon source tree.
3. Visit http://localhost:8080/jscoverage.html?test.html to run the unit tests through the JSCoverage server. The server will automatically instrument the Jarmon code and present a web interface which reports how much of the code has been exercised.