multigraph/js-multigraph

Javascript (HTML5) Multigraph Implementation

Multigraph

For more information about using Multigraph, see http://www.multigraph.org.

Development

To work on the Multigraph code, prepare your computer by installing the required dev tools:

• npm
• nodejs
• browserify (sudo npm install -g browserify)
• uglify-js (sudo npm install -g uglify-js)
• jasmine-node (for running the unit tests, sudo npm install -g uglify-js)

These tools are not needed for simply viewing Multigraph graphs, but they are needed for working on the Multigraph code. (The only thing needed for viewing a graph is a browser).

Then, to obtain and work with the code, use the following steps.

Clone the repo

git clone [email protected]:embeepea/js-multigraph

Initialize the git submodules

git submodule update --init --recursive

Install the npm dependencies

npm install

Run the unit tests from the command line

npm test

Build the bundled multigraph.js file

npm run build

Update and run the unit tests in a browser

npm run build-tests

After doing this, browse spec/index.html to run the tests in the browser.

Viewing the graph tests in a browser

Browse spec/graphics/index.html.

Adding a new graph test

Create a new *.xml file in spec/mugl, and optionally edit spec/mugl/tests.js; see the comments in spec/mugl/README.md for details. After adding a new *.xml file and/or editing spec/mugl/tests.js, run the command

npm run build-graph-tests

to update the tests, then browse spec/graphics/index.html.

Build everything (bundled and minified, with and without JQuery):

npm run build-all

js-multigraph's Issues

data object heirarchy

convert array_data & etc to Jermaine, and "merge" with existing Data.js object, etc

implement axis tickcolor and label color handling for raphael driver

See 13f6efe for how it's done with canvas.

canvas background images

Somebody needs to implement background image support in the canvas driver.

Detection of 'mouseleave' event in Raphael

The current event handlers to not always trigger mouseleave events when the mouse is currently being held down. This might be caused by bugs in jQuery 1.7.2's detection of events bound to SVG elements, but further investigation is needed.

array_data parsing bugs

There are two problems with our current parsing of array data values:

• values are required to be separated from each other by a comma; whitespace-only separators should be allowed as well
• if the number of columns of data found in the "values" section is less than the number of "variable"s in the "variables" section, no error is thrown, other than a cryptic "can't call method getRealValue of undefined" at runtime. Note that it's OK if the number of columns in the "values" section is more than the number of "variables"s in the "variables" section, because in that case the normalizer will supply the missing "variable"s.

write overview text for multigraph.github.com/examples page

Firefox (14.0.1) event handling problem

In Firefox 14.0.1 on LInux, Multigraph seems to hang as soon as the mouse is dragged at all --- the graph does not refresh, and the entire browser hangs for a long time, then eventually pops up a window saying that a script on the page is unresponsive. I am not sure what the problem is, but I'm guessing it has to do with our requestAnimationFrame() usage, and/or how we're catching / dealing with events. Needs investigation and fixing.

Favorite mugl services fail

http://occluded-d.ncdc.noaa.gov/xml/multigraph5.html

It's behind a firewall try

https://gist.github.com/cf2a6535ca02524a003a

test issue

will this email mark?

implement missing data display capability for main renderers

jquery plugin initializer doesn't return promise object

The Multigraph jQuery plugin is documented on http://multigraph.github.com/docs/js.html to say that it returns a promise object:

var promise = $(selector).multigraph({...});
promise.done(function() { ... });

However, it does not really seem to be returning a promise, because the above doesn't work. It is probably returning the jQuery object instead, since that's the standard behavior fo jQuery plugins. In order to use the promise, we have to do something like the following code from fcav:

https://github.com/nemac/ol-fcav/blob/0063efd176a0aacbd6ccf9174afa54b8df5620ca/fcav.js#L1230-L1239

Resolve this disparity by either:

* changing the plugin so that it really returns a promise, or
* deciding that the standard plugin behavior of returning the jQuery object is better, in
  which case the documentation mentioned above should be changed.

render type list changes

Somewhere along the way our code acquired multiple places that contain hard-coded lists of renderer types --- for example, at the end of src/core/renderer.js, and in src/normalizer.js. The way that src/core/render.js maintains a list of renderers needs to be modified so that we can eliminate these hard-coded lists, so that when a new renderer is added, we don't have to remember to edit all these lists to add it. The code needs to be written to allow a new renderer to be added by simply implementing and adding the code for that renderer (in core, and in the individual graphics drivers), with no need to update various lists elsewhere in the source. I can explain this in more detail in person.

implement ability to throttle outgoing web service requests

list of mugl incompatibilities

This issue documents differences in the MUGL specification between the version of MUGL that js-multigraph expects, as compared to the MUGL used by older versions of Multigraph --- in particular, the Flash version. We do not necessarily need to code js-multigraph to be backward compatible to support these differences, but we do want to at least document them here.

• "dotsize" (Flash) renderer option name changed to "pointsize" (js-multigraph)
• "dotcolor" (Flash) renderer option name changed to "pointcolor" (js-multigraph)
• Flash version of Multigraph actually works with MUGL files having a <plot> section that reference a non-existent axis id, because it defaults to the first axis
• older versions of Flash multigraph had "missingvalue" and "missingop" as renderer options, rather than metadata tags in the <data> section
• older Flash versions used a single number for the axis "position" attribute, and a "positionbase" attribute, instead of the newer position/base/anchor positioning attributes
• "pink" used to be a valid color name

raphael band renderer

Somebody needs to implement band renderer support in the raphael driver.

refactor raphael transformations

raphael allows for the notation

elem.transform(...[transform])
elem.transform([transform]...)

to append and prepend transformations, respectively. Current transformations should be re-written using this syntax for maintainability.

implement user message if no service data present

Per conversation with Rich Baldwin, implement a feature that causes Multigraph to display a message to the user saying something like "no data is available during this period for temp,precip" when viewing a time period that covers a request for which no data was received.

This is only pertinent for web service data situations; the message should be on a per- basis.

implement mugl preprocessor

The need for a function that will transform a jQuery XML MUGL object into one that is "complete" --- i.e. contains all tags and attribute values with settings from the original XML, or default settings, including tags and attributes with context-sensitive default settings -- is getting large enough that I think we should make it a priority. I'm starting this issue to document the requirements for it. At the moment, this is just a placeholder; we can talk about it and flesh it out soon.

integrate tester into multigraph.github.com

data variable column order csv_data & service_data

The current variable parsing code does not organize variables in order by columns, but the csv_data & service_data paring code assumes that the variables are sorted by columns. So if in the mugl a user does not give the variables in the correct order then improper behavior will result.

minimal mugl file doesn't render

The following MUGL file, given as an example of the simplest, minimal, MUGL possible, does not work with the new Multigraph: https://gist.github.com/3854777

Constant plots

This type of plot needs to be implemented, see dashboard-aoi spec for how multigraph currently handles these.

4.0 Release TODO

Code Changes

* DONE AxisTitles  JOHN
* DONE GraphTitles JOHN
* Raphael Bugs JOHN
* DONE Geomweather Legend JOHN (see issue #39)
* DONE "point" Renderer JOHN
* DONE Rename yuidoc output dir to "api"; remove old "doc" jsdoc output dir JOHN
* DONE BandRenderer, RangeBarRenderer method "renderLegendIcon" JOHN

multigraph.github.com

* DONE set up repo, include js-multigraph as a submodule JOHN
* Script to auto-generate example pages MARK
* JavaScript version of tester, including adding "muglstring" key to createGraph options JOHN
* Compose announcement / intro docs MARK

release process

* script to automate release process, including tagging, generating dist files, uploading dist files  MARK
* DONE investigate API for upoading "download" files to github JOHN

mugl schema

* DONE create a "pure" schema project repo on github, make it a subproject of js-multigraph, create validation script for checking validity of mugl/spec files, link to it from the docs on multigraph.github.com  MARK

legend error

The new test graph temp-precip-800x500.html causes an error message saying cannot call method 'height' of undefined. Using the chrome debugger I traced the problem to somewhere inside the legend code, and this is confirmed by the fact that if you turn the legend off (setting <legend visible="no"/> in the mugl), the graph works fine.

So, the issue is to figure out what's causing this error, and fix it.

email out release announcement

Once 4.0 is released, send email announcement to:

Semmy
[email protected] email list
John Keck
Rich Baldwin
Jon Burroughs
Ann Clites / Drew ?? @ GLERL
Jeb Stewart @ ESRL
Davide Cervone
David Herring / Dashboard Team
[email protected]
devin eldreth

raphael rangebar renderer

Somebody needs to implement rangebar renderer support in the raphael driver.

note on old SourceForge project

Put a note on the old SourceForge multigraph project letting people know that what is there is no longer used --- send them to github instead.

measuring height/width of text

No renderer takes factors such as rotation/fonts/font size into consideration in their computations of width/height of text elements

mousewheel zooming also scrolls the page

When using mouse wheel zooming the page containing the graph scrolls.

Floating point spacings in Datetime Measure

As a workaround for the complicated issue of locating the first tick mark for datetime measures with floating point spacings, we only allow integer spacings at the present. When we have time to re-visit this we need to get rid of this workaround and implement support for floating point spacings.

license

Decide on an open-source license to use, and incorporate it into the source code repo and multigraph.github.com web site.

array data parsing with unfinished variables section

The current array data parsing of the actual data can be incorrect if the variables section is not complete.

Proposed fix: add a 'stringArray' attribute on the array_data model which stores the array of data as an array of strings. The normalizer will handle the variables then parse the correct data types for the stored stringArray, store the result in 'array' then reset stringArray to [].

need consistent recognition of Boolean values in MUGL files

Currently the Multigraph parsing code has an inconsistent treatment of Boolean values. In some cases, such as in <legend visible="..."/>, the words true and false are recognized, but not the words yes or no. In other cases, such as <pan allowed="..."/>, the words yes and no are recognized, but not true or false.

This should be made consistent, so that in all cases in a MUGL file where a Boolean is expected, any of the strings true, false, yes, and no are accepted.

So, go through the entire MUGL spec to identify all the attributes that take on Boolean values (consult the Annotated Mugl File), and change the parsing code to be consistent with all of them. Do this by writing a single Boolean parsing utility function and calling it to convert string values to Boolean values in every place where a string is parsed into a Boolean.

web service data parser should ignore XML tags

So that it will correctly work with old-style data services that surround their responses with tags.

No way to specify custom error or warning handler in HTML

The code in src/events/jquery/multigraph.js does not look for any tags in the html to specify custom error or warning handlers.

axis label positioning (with rotation) (canvas?)

Something is wonky with the positioning of axis labels when the angle is not zero; see fotos-sst test graph for an example. The issue might be specific to the canvas driver; not sure yet.

namespace / src dir reorg

mg namespace / src tree reorg notes:

src/multigraph/math => src/math

src/multigraph => src/core
flatten src/core
similarly for shadowed copies
remove "Parser" from names of parser files
remove "ParserTest" from names of parser specs

rename files to c-style lowercase names

src/jquery-xml-handler => src/parser/jquery

namespaces should exactly mirror new directory structure

Areas of multigraph that still need to be implemented

• html embedding support
• implement min/max for individual renderer drivers
• automatically generating API documentation from source code(student)

---

general

• error reporting/recovery
• proper insertion of default values
  • general function to insert static defaults
  • handler code to process rule based defaults
  • proper implementation of passing functions to defaultsTo (see core/plotarea.js)
• find location for enums
  • allowed(YES & NO)
    • needed for pan & zoom
  • frame(PLOT & PADDING)
    • needed for legend & img
• abstract text model
• clean up code to use consistent spacings, quotes, etc
• figure out how to deal with fonts
  • font type, family, size
  • consistency across all types of text

jermaine

• event emitter?
• proper implementation of passing functions to defaultsTo (see core/plotarea.js)
• create static methods in jermaine
  • attach functions to models themselves

src

• core
  • array_data:
    • fully implement error reporting
    • textToDataValuesArray should be moved to Data model2
  • axis:
    • remove commented out redundant code
    • fully implement pan/zoom
  • axis_title:
    • properly implement this
      • implement proper type checking for its types
      • add render method
  • binding:
    • properly implement this
      • implement proper type checking for its types
  • datatips & datatips_variable:
    • properly implement this
      • implement proper type checking for its types
      • add whatever methods are needed to provide proper functionality
  • filter & filter_option:
    • properly implement this
      • implement proper type checking for its types
      • add whatever methods are needed to provide proper functionality
  • graph_title:
    • properly implement this
      • implement proper type checking for its types
      • add whatever methods are needed to provide proper functionality
  • grid:
    • properly implement this
      • implement proper type checking for its types
      • add render method implementation
  • plot:
    • renderer.setUpMissing call needs to be improved
      • possibly use parent pointers
  • renderers:
    • implement more renderers
      • barerror
      • lineerror
      • point?
      • band
      • rangebar
  • service_data:
    • implement RESTful data service
• events
  • jquery:
    • implement touch events
• math
  • RGBColor:
    • add more color names to parser
• utility_functions
  • parsing-functions:
    • re-write most of these functions
      • insert Defaults
      • getDefaultValuesFromXSD should actually parse the XSD
  • validation-functions:
    • rewrite/remove most of these functions
• parser
  • jquery
    • better handle attributes not being set in the mugl
    • implement appropriate rule based default values
      • or implement second parser, which takes the parsed mugl and inserts defaults where properties are missing, based on rules
      • Error reporting will be difficult to properly implement
      • possibly use a pre-processing parser which does validates rule based errors. Then type errors will be handled by the core parser. The post-processing parser would insert rule based defaults. Put this on the backburner so we can get a working build sooner.

---

Implement more rigorous graphics tests

• Set up suite of graphics tests which fully test the various graphical and mugl features of multigraph
  • dashboard graphs(15 of them)
  • need to also test features not in dashboard graphs
    • legend
    • RESTful data service
    • titles

Figure out the top level API

• process by which end user will call and implement multigraph
  • simple call for user to embed multigraph in HTML page
  • call for users to dynamically insert graphs in larger applications
• unify call for createGraph
  • have default to try and figure out what driver set to use
  • can override with a well-defined, standardized parameter

Packaging

• have driver specific packages to save on filesize
  • WebGL version or canvas version, etc
• possibly not include serialization code

Documentation

• User guide needs to be updated
• Multigraph.org site needs to be updated to be brought back upto date
  • scrapped and re-factored in Drupal 7

Demonstration

• Set up one or several web pages which are using this new version of multigraph
• Go through process of setting up graphs like end users will
• Litmus test applications
  • Marks Home weather station
  • FCAV time series graph
  • other?

Jasmine code coverage

• write more tests
• look into code coverage analysis tools for JS

---

Priorities

---

NCDC Wishlist

• Implement 'loading' wheel for async requests
  • Only allow one loading wheel at a time
• impose some limit on async requests
  • one option is for hard limit of 5 async requests
    • turn off pan and zoom beyond this region until the async requests return
  • have a fixed minimum range for async requests
• 'Annotation' renderer
  • allows for highlighting regions of graphs
    • indicate regions where data is missing
    • indicate regions where data is loading
  • have optional text in the region
  • supports extra service-side special values which indicate different conditions
• buttons for zooming and panning
  • change mouse icon to a 'hand'
  • google maps type buttons for zooming
  • image gallery-esque buttons for panning
• scroll wheel support for zooming

web service data "auto" min and max values

The web-service data algorithm for determining the proper bounds in the flash version is a kludge. It needs to be either revisited or the mugl spec needs to require users to specify the min and max in axes with only web service data revisited.

min/max setting problem with bound axes

When multiple axes are bound together, it's supposed to be possible to specify the min/max for just one of them in the mugl file, and Multigraph is supposed to set the min/max of the other axes that are bound to it using the binding. This doesn't appear to be working. See the geomweather.xml graphicstest for an example.

implement new plotarea (background) "color" attribute in raphael driver

See a68d642.

initial axis label/tick spacing

Label/tick mark spacing does not seem to be working correctly. Often, the choice of label/tick density seems wrong (too many labels scrunched together too tightly, or too few spread out too far), and sometimes the spacing takes an immediate jump when the axis is first panned or zoomed. For an example, see the vertical axis in the acis-webservice test graph.

implement axis binding

event handling in IE (raphael)?

Now that all tests pass (!!) and all graphs draw (!!!!!) in IE (IE9, at least), there are still some issues with IE. In particular, with the raphael driver, panning/zooming is jerky/slow. This is especially true with zooming. I did not notice the same jerkiness with the canvas version, although both should be more thoroughly tested.

The task here is to investigate these issues and figure out what, if anything, can be done to fix them.

axis "min" and "max" values with "auto" keyword

Axes currently do not determine the proper min & max values from the dataset if they were not specified in the mugl or were set to "auto".

notice on www.multigraph.org

Put a notice on every page on www.multigraph.org, telling users that the new, JavaScript/HTML5, version of multigraph is now at multigraph.github.com.

touch events

touch events need to be developed for the project.

User specified fonts

For all multigraph components which require text to be displayed a method to allow users to specify fonts/font-families/font-sizes must be developed & implemented.

plotarea border drawing in canvas driver

Somebody needs to implement drawing the plotarea border for the canvas driver. For an example, see the green border around the plotarea in raphael's version of the background_image test.

legend opacity should only apply to legend background, not entire legend

The "opacity" attribute of the tag is currently implemented to affect the opacity of the entire legend, but it's supposed to only affect the opacity of the legend's background rectangle.

This means that <legend opacity="0" ... /> results in a completely invisible legend; it's supposed to result in the background rectangle of the legend being completely invisible, but the text and icons of the legend still completely visible.

This can be fixed by changing the legend rendering code so that the opacity setting only affects the legend background; the icons and text should always be drawn at full opacity.