---

title: Using JavaScript in Multigraph

docs: selected

permalink: /docs/js/

layout: master

---

<h2>Using Multigraph with JavaScript</h2>

Multigraph lets you create a graph in an HTML page

by simply putting a <code>div</code> in the page which

has <code>class="multigraph"</code>, and a <code>data-src</code>

attribute that gives the location of the MUGL file to load. Multigraph

scans through the entire page looking for all <code>div</code>s of

class <code>multigraph</code>, 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.

<h3>Multigraph and jQuery</h3>

Multigraph requires <a href='http://jquery.com'>jQuery</a>.

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 <code>&lt;script&gt;</code> tag such as

<pre class="syntaxhighlight"><code>&lt;script type="text/javascript" src="http://multigraph.org/download/multigraph-min.js"&gt;&lt;/script&gt;

you can refer to the global <code>$</code> or <code>jQuery</code>

variables in subsequent JavaScript code on your page

as if you had included jQuery itself.

</p>

[Note: releases of Multigraph prior to 5.0 include jQuery in a way that

does not define the global <code>$</code> or <code>jQuery</code> variables.

For these releases, the jQuery object included by Multigraph is available in

the global variable <code>multigraph.jQuery</code>.]

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 <code>$.fn.jquery</code>

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:

<pre class="syntaxhighlight"><code>&lt;script type="text/javascript" src="https://code.jquery.com/jquery-1.10.2.min.js"&gt;&lt;/script&gt;

&lt;script type="text/javascript" src="http://multigraph.org/download/multigraph-nojq-min.js"&gt;&lt;/script&gt;

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.

</p>

<h3>The Multigraph jQuery Plugin</h3>

Multigraph is implemented as a jQuery plugin &#8212; it defines a

function named <code>multigraph</code> that you can call on a jQuery

collection. You can use this function to create and/or access

instances of Multigraph in <code>div</code>s in the page. For example,

suppose your HTML page contains the following div:

<pre class="syntaxhighlight"><code>&lt;div id='#mygraph' style="width:500px; height:300px"/&gt;</code></pre>

<p>You can insert a Multigraph into this <code>div</code> by calling</p>

<pre class="syntaxhighlight"><code>$('#mygraph').multigraph({ 'mugl' : <strong>URL-OF-MUGL-FILE-HERE</strong> });</code></pre>

<p>This is in fact exactly what Multigraph itself does to implement the normal interface that automatically inserts a Multigraph instance into all <code>div</code>s in the page having a class of <code>multigraph</code>.</p>

<h3>Plugin Options</h3>

<p>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:</p>

<div class="panel panel-default">

<div class="panel-heading">

<h4 class="panel-title">Attributes</h4>

</div>

<ul class="list-group">

<li class="list-group-item">

<div class="row">

<div class="col-md-2">

<code>mugl</code>

</div>

<div class="col-md-10">

<p>This should be the URL of a MUGL file to load. Exactly one of mugl or muglString must be present.</p>

</div>

</div>

</li>

<li class="list-group-item">

<div class="row">

<div class="col-md-2">

<code>muglString</code>

</div>

<div class="col-md-10">

<p>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.</p>

</div>

</div>

</li>

<li class="list-group-item">

<div class="row">

<div class="col-md-2">

<code>width</code>

</div>

<div class="col-md-10">

<p>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.</p>

</div>

</div>

</li>

<li class="list-group-item">

<div class="row">

<div class="col-md-2">

<code>height</code>

</div>

<div class="col-md-10">

<p>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.</p>

</div>

</div>

</li>

<li class="list-group-item">

<div class="row">

<div class="col-md-2">

<code>error</code>

</div>

<div class="col-md-10">

<p>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.</p>

</div>

</div>

</li>

<li class="list-group-item">

<div class="row">

<div class="col-md-2">

<code>warning</code>

</div>

<div class="col-md-10">

<p>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.</p>

</div>

</div>

</li>

</ul>

<h3>Accessing a Multigraph</h3>

<p>You can also use the multigraph jQuery plugin to retrieve and interact with a Multigraph. The plugin defines a method called <code>multigraph</code> (both the plugin and the method are named <code>multigraph</code>). 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.</p>

<p>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 <code>done()</code> method.</p>

<p>This is easier to follow with a concrete example:</p>

<pre class="syntaxhighlight"><code>$('#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());

});

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

<pre class="syntaxhighlight"><code>$('#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, <code>m</code> 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

<a href="https://github.com/multigraph/js-multigraph">source code</a>

itself is liberally commented and is hopefully fairly readable.