One of the most powerful pieces of Dojo is also one of the most underutilized: Charting.  The Dojo Charting library lives within the DojoX (extensions) branch of Dojo, and features numerous chart types, options, and a variety of themes. This post introduce you to the charting library and show you how you can take a mundane data collection and make it a beautiful visual chart in any modern web browser.

Requiring Charting Classes

Most of a programmatic Chart is created with chained methods; you rarely will create instances from constructors aside from the Chart itself. However, the underlying code still needs to be required with AMD for the functionality to work. A basic dependency array may look like this:


Two Ways to Play

Much like most of the widgets within the Dijit and DojoX libraries, the charting library allows you to create charts programmatically and declaratively.  Let’s take a look at an example of each approach.

Declarative Chart Creation

The declarative method of creating charts is done with HTML markup.  All chart data such as type, axis, plot, and other chart information is created within the chart container.  Here’s a simple pie chart:

<div data-dojo-type="dojox/charting/widget/Chart" id="chart" style="width:300px; height:300px; margin:10px;"
	data-dojo-props="theme: dojox.charting.themes.PlotKit.green">
	<div class="plot" name="default" type="Pie" fontColor="#000"></div>
	<div class="series" name="A" data="5,8,10,40,20"></div>
	<div class="action" type="Tooltip"></div>
	<div class="action" type="MoveSlice" shift="2"></div>

Note that nested chart properties do not yet support HTML5 data-dojo-* attributes, and theme names still use pre-AMD identifiers. These inconsistencies will be resolved in Dojo 1.9.

Pie Chart with Tooltip

Programmatic Chart Creation

Programmatic chart creation is also quite easy.  The JavaScript code below reproduces the chart above:

], function(Chart, Pie, Tooltip, MoveSlice, PlotKitGreen){

	var pieChart = new Chart("pieChartNode");
	pieChart.addPlot("default", {
		type: "Pie",
		fontColor: "#000"
	pieChart.addSeries("Series A", [5,8,10,40,20]);
	new MoveSlice(pieChart,"default");
	new Tooltip(pieChart,"default");

Take a moment to compare the two methods and you will quickly notice how similar the structures are. It’s the developer’s choice which method, declarative or programmatic, to use. This tutorial will focus on the programmatic method of chart creation though all examples work with both approaches.

Creating a Simple Chart

Now that the fundamental pieces of the charting puzzle have been explained, let’s create a very basic chart.  This chart will depict website visits over 3 months time.  The chart will be a basic StackedAreas chart with different colors to denote the different months. We’ll take it step by step.

The first step is to place our data in the format with which the chart works. The data for our StackedArea chart must hold each value in one array:

var json = {
	January: [9420,10126,9803,15965,17290, /* ... */  13165,12390],
	February: [23990,32975,23477,22513,18069, /* ... */ 12956,12815],
	March: [22477,24014,21116,20404,19142, /* ... */ 22077,20263]

The next step is to create the chart programatically.

//we have a DIV element with an ID of "chartNode";  that's the argument
var chart = new Chart('chartNode'); 

Then it’s time to add the plot.

//add the default plot
chart.addPlot("default", {
	//type of chart
	type: "StackedAreas",
	//show markers at number points?
	markers: true,
	//curve the lines on the plot?
	tension: "S",
	//show lines?
	lines: true,
	//fill in areas?
	areas: true,
	//offset position for label
	labelOffset: -30,
	//add shadows to lines
	shadows: { dx:2, dy:2, dw:2 }

Since the numbers in this type of chart are significant, we want to add an X axis (representing days) and a Y axis (representing traffic / views).

chart.addAxis("y", { vertical:true });

Now that the frame of the chart has been created, it is time to add the information for each month. Since we want to fill areas, we’ll need to pass a stroke and fill color within the series:

chart.addSeries("January Visits",json["January"], { stroke: "red", fill: "pink" });
chart.addSeries("February Visits",json["February"], { stroke: "green", fill: "lightgreen" });
chart.addSeries("March Visits",json["March"], { stroke: "blue", fill: "lightblue" });

Now that our chart is built and the data is in place, we can render the chart:


The result is a beautiful chart:

Basic Chart

Chart Animations, Legends, and Extras

As with every other piece of the Dojo library, the Dojo charting library is flexible enough to incorporate other Dojo classes and widgets.  The basic chart we created above is nice but could use a few useful enhancements.


Adding a legend to the chart is very simple:

// get our Legend dependency...
require(["dojox/charting/widget/Legend"], function(Legend) ...
	//this legend is created within an element with a "legendNode" ID.
	new Legend({chart:chart}, 'legendNode');

Chart Animations

As with basic content on a web page, animation adds some flare and shows focus on an element. Each chart type supports different sets of animations. To keep it simple, we can add a “magnify” animation to the markers on our chart so that the marker grows when the mouse enters it:

// get our Magnify dependency...
require(["dojox/charting/action2d/Magnify"], function(Magnify) ...
	//add the magnification animation to our chart for the default plot
	new Magnify({chart:chart}, 'default');


Our chart features markers at the designated x/y axis numbers but we can enhance those markers with tooltips so that the user can see the exact number the marker represents.

var tip = new dojox.charting.action2d.Tooltip(chart1, "default");
// get our Tooltip dependency...
require(["dojox/charting/action2d/Tooltip"], function(Tooltip) ...
	//add the Tooltip to our chart for the default plot
	new Tooltip({chart:chart}, 'default');

Enhanced Chart

You may also pair Dijit themes with your chart to style the tooltip; I’ve added the “tundra” theme’s CSS file to enhance the style of my tooltip.

Zooming, Scrolling, and Panning

As you would expect from a vector graphic generation tool, Dojo’s charting library provides a method by which you may flawlessly zoom in and out on any chart. You may also accommodate panning and scrolling on your charts. Read Zooming, Scrolling, and Panning in Dojo Charting to learn more about these features or view a great example of panning, scrolling, and zooming!

Chart Events

Dojo’s charting library also has its own event connection method: connectToPlot.  This method allows you to add event listeners to your chart and trigger functionality based on the given event.

chart1.connectToPlot("default",function(e) {
	/* do something */

Chart events provide you a wealth of information, including the type of event, coordinates, plot, shape, and more. Visit the Dojo Charting Reference Guide to get detailed information about chart events.

Chart Themes

The Dojo charting library provides over 30 themes to make your charts stand out. You may see a complete list of bundled themes (with preview) in the Dojo Nightly Theme Previewer. Or visit Dive Into Dojo Chart Theming to learn more.

charting themes

Chart Families

This tutorial showed you how to create a basic, but beautiful 2D chart; Dojo’s charting library has many advanced charting capabilities though. The different families of Dojo charts includes:

  • 2D Charts: The basic two-dimensional chart. (examples)
  • 3D Charts: Three-dimensional representations of data. (example)
  • StoreSeries: Connect to a Dojo Object Store (tutorial)

New Charting Features

Dojo introduces new features to the charting library constantly. Some of the more recent additions include:

  • Linear and radial gradients can be used with virtually all chart types (and yes, they work in IE).
  • Flexible data sourcing via StoreSeries (to work with dojo/store) adds the ability to back charts with practically any sort of data source your would like, even supplying secondary information like tooltips.
  • Plot and series order manipulations enable one to programmatically shuffle plots and series as needed.
  • Indirect events that effectively make it possible for linked plots to share events.
  • External events allow a developer to programmatically generate things like mouseovers and apply them to charting objects.
  • The default axis is now smarter regarding scaling and sizing.
  • A new lightweight invisible axis type allows the user to control plot scale and alignment without displaying an axis.

Great Charting Resources

The concept of charting can seem difficult, but Dojo’s charting library is a breeze to dive into!