Using Multigraph with JavaScript

Multigraph's HTML5 interface lets you create a graph in an HTML page by simply putting a div in the page which has class="multigraph", and a data-src attribute that gives the location of the MUGL file to load (see the integration page for details). Multigraph scans through the entire page looking for all divs of class multigraph, and runs some code on each one to insert the relevant graph into it. This is the easiest way to get a Multigraph into a web page, and doesn't involve writing any JavaScript code. If you want more control over the details of what Multigraph does, though, you can write your own custom JavaScript code that interacts with Multigraph.

The multigraph JavaScript Namespace

The first thing to be aware of if you want to interact with Multigraph using JavaScript is that multigraph(-min).js defines a single variable at the global level named multigraph. This variable serves as a namespace for Multigraph — all functions and objects that Multigraph defines are inside this object. This global multigraph object is also available as window.multigraph.

Multigraph and jQuery

Multigraph uses jQuery, and multigraph.js includes a copy of jQuery inside it. This copy of jQuery is included in a way that does not define any global variables — in particular, it does affect the value of the global variable $. This is to avoid any conflicts between multigraph.js and other libraries (such as prototype.js, or another copy of jQuery) on the page that might use $ for their own purposes. The jQuery object from this internal copy of jQuery is available through the expression window.multigraph.jQuery, though, and you're free to reassign that value back to $ if you want to use jQuery on your page without having to load it separately:

<script type="text/javascript" src="http://multigraph.github.io/download/multigraph-min.js"></script>
    <script type="text/javascript">
      $ = window.multigraph.jQuery;
      /* ... from this point on you can use $ to refer to jQuery as usual ... */
      console.log('This copy of Multigraph uses jQuery version ' + $().jQuery);
    </script>

At the time of this writing, the version of jQuery included in Multigraph is 1.8.2; you can always check the jQuery version number exactly by examining $().jQuery as in the above example.

The Multigraph jQuery Plugin

Multigraph is implemented as a jQuery plugin — it defines a function named multigraph that you can call on a jQuery collection. You can use this function to create and/or access instances of Multigraph in divs in the page. For example, suppose your HTML page contains the following div:

<div id='#mygraph' style="width:500px; height:300px"/>

You can insert a Multigraph into this div by calling

$('#mygraph').multigraph({ 'mugl' : URL-OF-MUGL-FILE-HERE });

This is in fact exactly what Multigraph itself does to implement the normal HTML5 interface that automatically inserts a Multigraph instance into all divs in the page having a class of multigraph.

Creating a Multigraph

The multigraph plugin function takes a single argument which is a JavaScript object that specifies options that govern how the Multigraph is created. The possible values in this options object are:

• mugl

  this should be the URL of a MUGL file to load. Exactly one of mugl or muglString must be present.

• muglString

  this should be a string which contains the MUGL XML to be loaded (the actual XML document, as a string, not the URL or name of a file containing it). Exactly one of mugl or muglString must be present.

• width

  the width of the graph, in pixels. If this is not present, Multigraph will query the div itself to get its width; this means that you can use CSS to assign it.

• height

  the height of the graph, in pixels. If this is not present, Multigraph will query the div itself to get its height; this means that you can use CSS to assign it.

• driver

  the graphics driver to use in the graph. The possible values are

  • "canvas"

    causes Multigraph to use the HTML5 Canvas tag for graphics. This works in all recent browsers except versions of IE prior to 9.

  • "raphael"

    causes Multigraph to use the Raphael graphics library for graphics. This library uses SVG in browsers that support SVG; it uses VML in versions of IE prior to 9.

  • "auto"

    this is the default; it causes Multigraph to use the canvas driver in all browsers that support it, and otherwise it uses the Raphael driver.

• error

  this is optional; if it is present, its value should be a function for handling error messages that Multigraph generates. Multigraph will call this function if and when it encounters an error in the course of loading a MUGL file, drawing a graph, or doing anything else that it does. The function should take a single argument which is an instance of a JavaScript Error object. The default behavior, which is what happens if this option is not present, is to use Multigraph's own internal mechanism for displaying user messages.

• warning

  this is optional; if it is present, its value should be a function for handling warning messages, similar to the above description for error messages. (Warning messages are like errors but are less severe.) The default behavior is that warnings are handled using whatever the current mechanism for handling errors is — i.e. either Multigraph's internal message display, or the custom function specified by the value of the error option.

Accessing a Multigraph

You can also use the multigraph jQuery plugin to retrieve and interact with a Multigraph. The plugin defines a method called multigraph (both the plugin and the method are named multigraph). This method returns a jQuery promise object that resolves when the Multigraph object has finished loading, and you can use that promise object to access the graph itself.

If you're not familiar with jQuery promise objects, they're just a convenient way to handle asynchronous code. A promise object is needed in this case because Multigraph doesn't finish constructing the graph until after the MUGL file it references has been loaded, and this generally involves an asynchronous (ajax) request for the file. So it's not possible to directly return the Multigraph object; instead, what is returned is a promise object that can be used to apply functions to the (possibly not-yet-created) Multigraph object through the promise object's done() method.

This is easier to follow with a concrete example:

$('#mygraph').multigraph({ 'mugl' : URL_OF_MUGL_FILE });
var multigraphPromise = $('#mygraph').multigraph('multigraph');
    multigraphPromise.done(function(m) {
    // The promise will call this function once the Multigraph object
    // has been constructed, and pass it in as the argument 'm'.  Here
    // you can put code that accesses the Multigraph API using m.  For
    // example:
    console.log("This graph's first axis has an id of: " + m.graphs().at(0).axes().at(0).id());
});
multigraphPromise.done(function(m) {
    // You can call the promise's done() method as many times as you want; it will execute
    // every function you pass to it, in the same order in which you pass them, once the
    // Multigraph object has been constructed.
    console.log("And its second axis has an id of: " + m.graphs().at(0).axes().at(1).id());
});

The multigraph plugin also defines a convenience method called done, which simply delegates to the underlying promise's done method; you can use this plugin method to avoid having to store a reference to the promise object:

$('#mygraph').multigraph({ 'mugl' : URL_OF_MUGL_FILE });
$('#mygraph').multigraph('done', function(m) {
    console.log("This graph's first axis has an id of: " + m.graphs().at(0).axes().at(0).id());
});
$('#mygraph').multigraph('done', function(m) {
    console.log("And its second axis has an id of: " + m.graphs().at(0).axes().at(1).id());
});

The Multigraph object, m in the examples above, is an instance of the window.multigraph.Multigraph model in the Multigraph JavaScript API. The documentation for this API hasn't been fully written yet, but the beginnings of it are in place.