Multigraph - Using JavaScript in Multigraph

Using Multigraph with JavaScript

Multigraph 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. 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.

Multigraph and jQuery

Multigraph requires jQuery. When you load Multigraph into your web page, you can either load a version of it that includes a copy of JQuery, or (starting with Multigraph release 5.0.1) you can load your own copy of jQuery and then load a version of Multigraph that does not include jQuery. Versions of the Multigraph JavaScript file that do not have the string "nojq" in their name (such as "multigraph.js", "multigraph-min.js", "multigraph-5.0.1.js", "multigraph-min-5.0.1.js", etc) include a copy of jQuery. If you load one of these Multigraph files in your page with a <script> tag such as

<script type="text/javascript" src="http://multigraph.org/download/multigraph-min.js"></script>

you can refer to the global $ or jQuery variables in subsequent JavaScript code on your page as if you had included jQuery itself.

[Note: releases of Multigraph prior to 5.0 include jQuery in a way that does not define the global $ or jQuery variables. For these releases, the jQuery object included by Multigraph is available in the global variable multigraph.jQuery.]

At the time of this writing, the version of jQuery that is included with Multigraph is 1.8.2, but you can examine the value of $.fn.jquery at any time to discover the jQuery version.

Starting with Multigraph version 5.0.1, there are also versions of the Multigraph JavaScript file that include the string "nojq" in the filename; these versions of Multigraph do not include a copy of jQuery, and if you use one of these versions, you must include jQuery in your page before loading Multigraph:

<script type="text/javascript" src="https://code.jquery.com/jquery-1.10.2.min.js"></script>
<script type="text/javascript" src="http://multigraph.org/download/multigraph-nojq-min.js"></script>

Multigraph should work with any version of jQuery greater than or equal to 1.8.2. It may also work with older versions of jQuery, but has not been tested with them.

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 interface that automatically inserts a Multigraph instance into all divs in the page having a class of multigraph.

Plugin Options

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:

Attributes

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.
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. Unfortunately, documentation for this API hasn't been written yet, but the source code itself is liberally commented and is hopefully fairly readable.