The latest addition in the Dojo 1.3 release is the new dojox.charting class, DataChart. Its primary purpose is to make connecting a chart to a Data Store a simple process. There are also other benefits with DataChart: less parameters are needed to create a basic chart, and more defaults and convenience methods get you up and running quickly with Dojox Charting.

The Data Store

Creating a chart is fast and easy, but before we can do so, we need our data. We’ll use dojo.ItemFileWriteStore, since it is the most commonly used, and most standard store. We’ll connect to the dojox/charting/tests/stock.json file which contains a set of imaginary stock market prices. The following code should connect to that JSON file and log all of the store items to the console:

dojo.require("dojo.data.ItemFileWriteStore");
        
var store = new dojo.data.ItemFileWriteStore({ 
	url:dojo.moduleUrl("dojox.charting", "tests/stock.json") 
});
// testing
store.fetch({query:{name:"*"}, onComplete: function(items){
	console.log("fetched:", items);
}});

Fast Chart Setup

Now that we have our Data Store, we can create our chart. Start with an HTML node, formatted to the size you want the chart to be. I’m sizing the node inline, but you could use a style and class name just as well:

We naturally have to wait for the DOM to load, so in dojo.addOnLoad, we’ll place the chart code. In its most basic, default form, it requires no parameters, besides the node id. The store can be set in the parameters or as a separate method as shown. The setStore method is the same as used elsewhere in Dojo, like in the DataGrid. Unlike the Grid, the DataChart needs one additional argument — the store item property that will be charted. In this case, that property is historicPrice.

dojo.require("dojox.charting.DataChart");
dojo.addOnLoad(function(){
	chart = new dojox.charting.DataChart("chartDiv", {});
	chart.setStore(store, {symbol:"*"}, "historicPrice");
});

Chart01

And that’s all it takes to get up and running with charts.

DataChart Mapping

Now let’s look at a (trimmed down) version of the JSON file we are using, as it is important to the next concepts we will discuss:

{ "identifier": "symbol", "idAttribute":"symbol", "label": "symbol","items": [
	{ "symbol":"ANDT", 
		"historicPrice":[0.01,3.52,3.66,3.11,3.90,3.11,3.11], "price":3.52},
	{ "symbol":"ATEU", 
		"historicPrice":[6.72,6.76,6.61,6.41,6.31,6.99,7.20], "price":6.76},
	{ "symbol":"BGCN",
		"historicPrice":[4.11,3.98,4.05,4.20,4.16,4.22,3.80], "price":3.98},
	{ "symbol":"BAYC",
		"historicPrice":[9.79,9.60,9.50,2.23,9.45,9.76,9.99], "price":9.60},
	{ "symbol":"CRCR",
		"historicPrice":[8.44,8.44,8.54,8.60,9.65,8.42,8.44], "price":8.44},
	{ "symbol":"DTOA",
		"historicPrice":[2.11,2.47,3.11,3.06,3.01,3.01,3.00], "price":2.47}
]}

The property we used for our default chart is historicPrice and as you can see, it’s an array. Because the default chart is a line-type, and plots each item separately, more than one bit of data is necessary to span across the x-axis. In our case, there are seven slots in the array, which is why we had an x-axis span of seven. If we charted the price property, we would have seven points all along the y-axis, and the chart x-axis would only have a length of one.

However, the need of the chart may not be a series of individual item properties, it may be single item properties compared to the others. We can compare the price of each item on a line chart using the comparative property:

dojo.addOnLoad(function(){
	chart = new dojox.charting.DataChart("chartDiv", {
		comparative:true
	});
	chart.setStore(store, {symbol:"*"}, "price");  //  <-- single value property
});

Chart02

Chart Labels

Those x-axis labels could stand to be a little more descriptive. Fortunately, DataChart has a convenient method for applying the store item labels. We can edit the chart.xaxis object, which is exposed so that besides the property we will add here, you can edit the standard chart axis properties as shown in the comments of the code.

labelFunc is actually a method that you can tap into to write custom labels. In our case, we are going to give it a string, which tells DataChart to use its seriesLabels method. Simply put, it connects the item labels to the chart labels.

dojo.addOnLoad(function(){
	chart = new dojox.charting.DataChart("chartDiv", {
		comparative:true,
		xaxis:{labelFunc:"seriesLabels"},
	});
	chart.setStore(store, {symbol:"*"}, "price");
});

Chart03

Chart Legends

Let's backtrack for a minute here. What about that first chart we created? The x-axis in that case more closely represented time, not the items (and if you wanted to put different times on the x-axis you could write a custom label function that did that using xaxis.labelFunc — but that is beyond the scope of this article). What we need now is a legend. DojoX Charting comes with dojox.charting.widget.Legend to make it easy to add legends to your charts. Currently however, it isn't designed to handle "live" data — it's expecting that the chart knows the data as it's created. It doesn't mean we can't use it, we just need a little extra code to connect it when the chart has data:

dojo.addOnLoad(function(){
	chart = new dojox.charting.DataChart("chartDiv", {});
	chart.setStore(store, {symbol:"*"}, "historicPrice");
	
	 var c = dojo.connect(chart, "onData", function(){
		dojo.disconnect(c);
		new dojox.charting.widget.Legend({chart:chart}, "legend"); 
	});
});

Chart04

In the previous example, we connected to the chart's onData event (we connected once by disconnecting it immediately after the first call) and then create the legend programatically, now that the chart knows its data.

Different Chart Types

So what about other chart styles? It's a simple matter of passing a type:

dojo.addOnLoad(function(){
	chart = new dojox.charting.DataChart("chartDiv", {
		type: dojox.charting.plot2d.Columns, // <-- chart type
        	scroll:false,
        	xaxis:{labelFunc:"seriesLabels"}
	});
	chart.setStore(store, {symbol:"*"}, "price");
});

Chart05

Hey, wait a minute! What is scroll:false?

Animation

The DataChart supports information updating, which allows it to animate. To update the information, you change the item property in the store. The DataChart is connected to the onSet event in the store and reflects the change. The test in the DojoX trunk demonstrates this with spinner widgets that modify the store item property.

The scroll parameter works in conjunction with two other parameters:

  • stretchToFit: This is how native charts work. If given five bits of data, the x-axis will be five segments long.
  • displayRange: If set, stretchToFit is overridden and the x-axis will not stretch, it will always be that long. This is often used with scroll.
  • scroll: If true and there is more data than fits on the x-axis, it will scroll to the left.

Note that the y-axis is always fixed, having it stretch to fit or scroll is not currently supported.

Demo

I know that the combination of these parameters can be confusing, especially when it comes to different chart types. I've created a demo that you can use to test the different parameters and dynamically build new charts. It not only shows off the features of DataChart, but will get you up and running that much faster!

Note: Learn more about the new DojoX Data Chart and more at one of our upcoming workshops in Sydney, Munich, London, Milan, or Paris.