When evaluating the Dojo Charting library as an option for my CruiseControl statistics page replacement it was very evident that the Dojo team hadn't gotten around to providing documentation for this donated library. If you are unfamiliar with what the features the library offers you should take a look at this Ajaxian post. There is also a test page for the library which I could have sworn was down a day or two ago.
In the interest of possibly helping others save some time getting into the chrting library I wanted to post a basic introductory example. Please be aware that I do not know this library in depth, nor have I worked with the Dojo libraries extensively.
What is great about the Dojo charting implementation is that it is very versatile. This however comes at the cost of a slightly more involved structure which makes it somewhat more tedious to use than PlotKit. The composition of the various graphing objects is illustrated in the diagram below. As you can see from the relationships in the diagram they have allowed for features such as the ability to render multiple different graphs, using different plotters, in one plot area. They also have different implementations of the Axis, PlotArea and Plotter objects for VML and SVG rendering.
The Example
So to create a graph one would start off by including a reference to the dojo library and the required namespaces:
<script type="text/javascript" src="dojo/dojo.js"></script>
<script type="text/javascript">
//Include the required dojo libraries/namespaces
dojo.require("dojo.collections.Store");
dojo.require("dojo.charting.Chart");
dojo.require('dojo.json');
</script>
You then define or retrieve the graph data and store it in the collection store. This then will be fed into your graph as a series, defined like this:
var exampleData =
[
{ time: 10, count: 7382 },
{ time: 20, count: 1852 },
{ time: 35, count: 2397 },
{ time: 50, count: 1442 },
{ time: 55, count: 1854 }
];
var store = new dojo.collections.Store();
store.setData(exampleData);
var timeSeries = new dojo.charting.Series({
dataSource: store,
bindings: { x: "time", y: "count" },
label: "Example Series"
});
Next come the axis definitions where you can specify the data display range, data source and the tick labels:
//Define the x-axis
var xAxis = new dojo.charting.Axis();
//Set the upper and lower data range values
xAxis.range = { lower: exampleData[0].time, upper: exampleData[exampleData.length-1].time };
xAxis.origin = "max";
xAxis.showTicks = true;
xAxis.label = "Example chart";
//Setup the x tick marks on the chart
xAxis.labels = [
{ label: 'First', value: 20 },
{ label: 'Second', value: 25 },
{ label: 'Third', value: 35 },
{ label: 'Fourth', value: 50 },
{ label: 'Fifth', value: 55 }
];
//Define the y-axis
var yAxis = new dojo.charting.Axis();
yAxis.range = { lower: 0, upper: 5000 };
yAxis.showLines = true;
yAxis.showTicks = true;
yAxis.label = "Time Taken";
//Setup the y tick marks on the chart
yAxis.labels = [
{ label: "0s", value: 0 },
{ label: "1s", value: 1000 },
{ label: "2s", value: 2000 },
{ label: "3s", value: 3000 },
{ label: "4s", value: 4000 },
{ label: "5s", value: 5000 }
];
You then define how the data will be plotted by defining a Plot and assigning the series with a plotter to render it:
var chartPlot = new dojo.charting.Plot(xAxis, yAxis);
chartPlot.addSeries({
data: timeSeries,
plotter: dojo.charting.Plotters.CurvedArea
});
This then needs to be rendered into a specific area, so one defines the PlotArea and adds the Plot to it:
var chartPlotArea = new dojo.charting.PlotArea();
chartPlotArea.size = { width: 380, height: 170 };
chartPlotArea.padding = { top: 20, right: 20, bottom: 30, left: 50 };
//Add the plot to the area
chartPlotArea.plots.push(chartPlot);
Finally one needs to create the chart and add the PlotArea to it. The chart also needs to have a container element, which one assigns to the chart.node.
var chart = new dojo.charting.Chart(null, "Example chart", "This is the example chart description");
//Add the plot area at an offset of 10 pixels from the top left
chart.addPlotArea({ x: 10, y: 10, plotArea: chartPlotArea });
//Setup the chart to be added to the DOM on load
dojo.addOnLoad(function()
{
chart.node = dojo.byId("GraphContainerArea");
chart.render();
});
And voila, you have a graph that looks like this:
To see the graph in action, take a look at this demo page.