A Beginner’s Guide to Dojo Charting with AMD, Part 2 of 2

By on November 9, 2012 2:00 am

Part 1of this guide on Dojo Charting covered a basic charting example and the options available in defining our chart type. Now we will examine the options for defining our axes and data sets.

Accessing the Axis

The addAxis() call on a chart has several options for defining axes. Similar to addPlot(), this call takes 2 parameters, a name and an options object. You will need to use “x” and “y” as your axes names unless you gave them custom names in your addPlot() call. Additionally, you don’t have to define the axes if you wish to create charts with one or zero axes, and you can also make charts with more than 2 axes by adding a second plot and attaching axes to it. Using this approach, you can display up to 4 different axes, 2 vertical and 2 horizontal, using 2 to 4 plots. Also, a single axis can be shared by more than 1 plot, meaning you could have 2 plots that use the same horizontal axis, but have different vertical axes. Let’s look at all the addPlot() options that make this and more possible.

The first option is vertical, which determines if the axis is vertical or horizontal, and defaults to false, which of course means the axis would be horizontal. Make sure that your alignment matches with values set for hAxis and vAxis, which are “x” and “y” by default, on your plot or your chart will not render.

chart.addPlot("default", {type: "Lines", hAxis: "x", vAxis: "y"});
chart.addAxis("y", {vertical: true});

Next we have the fixUpper and fixLower parameters, which align the ticks and have 4 available options; “major”, “minor”, “micro”, and “none”. These default to “none”, and when set will force the end bounds to align to the corresponding tick division. If “none” is chosen, the end bounds will be the highest and lowest values in your data set. Another related option is the includeZero option, which will make your lower bound be zero instead of the lowest value. If your lowest data value is negative the includeZero option has no effect.

chart.addAxis("x", {fixUpper: "major", fixLower:"minor"});
chart.addAxis("y", {vertical: true, fixUpper: "major", includeZero: true});

Now let’s examine the leftBottom parameter. This parameter defaults to true, and along with the vertical parameter, determines the side of the chart in wihch the axis is placed. At the end of Part 1 we examined adding a second plot to our chart. Let’s use that sample and give the second plot its own set of axes and anchor them on the top and right using leftBottom.

	function (Chart) {
		var chart = new Chart("simplechart");
		chart.addPlot("default", {type: "Lines"});
		chart.addPlot("someOtherPlot", {type: "Areas", hAxis: "someOtherPlot x", vAxis: "someOtherPlot y"});
		chart.addAxis("y", {vertical: true});
		chart.addAxis("someOtherPlot x", {leftBottom: false});
		chart.addAxis("someOtherPlot y", {vertical: true, leftBottom: false});
		chart.addSeries("Series 1", [1, 2, 2, 3, 4, 5, 5, 7]);
		chart.addSeries("Series 2", [1, 1, 4, 2, 1, 6, 4, 3],
				{plot: "someOtherPlot", stroke: {color:"blue"}, fill: "blue"}

Multiple Plots

The one thing you may have noticed is that this changes the perspective because the second data set is now charted against a different axis. You are in luck because you have full control to adjust the axis in almost every way possible. For example, you can set min and max parameters.

chart.addAxis("y", {

You can turn on and off the tick marks at the minor and micro level, and turn labels on and off for the major and minor levels

chart.addAxis("y", {
        majorLabels: true,
        minorTicks: true,
        minorLabels: true,
        microTicks: false

There’s natural, which forces all ticks to be on natural numbers, and fixed which will fix the precision on your labels.

chart.addAxis("y", {
        natural: false,
        fixed: true 

If you want you can define the step between the ticks.

chart.addAxis("y", {
        majorTickStep: 4,
        minorTickStep: 2,
        microTickStep: 1

You can control the color of the axis, the color and length of your tick marks, and the font and color of your labels.

var chart = new Chart("simplechart");
chart.addPlot("default", {type: "Lines"});
chart.addPlot("someOtherPlot", {type: "Areas", hAxis: "someOtherPlot x", vAxis: "someOtherPlot y"});
chart.addAxis("y", {vertical: true, leftBottom: true});
chart.addAxis("someOtherPlot x", {leftBottom: false});
chart.addAxis("someOtherPlot y", {
	vertical: true,
	leftBottom: false,
	max: 7,
	stroke: "green",
	font: "normal normal bold 14pt Tahoma",
	fontColor: "red",
	majorTick: {color: "red", length: 6},
	minorTick: {stroke: "black", length: 3}
chart.addSeries("Series 1", [1, 2, 2, 3, 4, 5, 5, 7]);
chart.addSeries("Series 2", [1, 1, 4, 2, 1, 6, 4, 3],
		{plot: "someOtherPlot", stroke: {color:"red"}, fill: "blue"}

When added to our previous example, the result is:

Styled Axis

You can also add a grid at your tick marks to your entire chart by adding a Grid plot. The grid plot allows you to turn the grid on and off for major and minor ticks in both directions, and you can assign axes names if you have multiple axes. Let’s add a grid to the other axes in our above example. Insert the following code somewhere before render().

chart.addPlot("gridPlot", {type: "Grid",
	hAxis: "someOtherPlot x",
	vAxis: "someOtherPlot y",
	hMajorLines: true,
	hMinorLines: false,
	vMajorLines: true,
	vMinorLines: false

Grid Plot

Last but not least, you have the ability to assign custom labels to your axis. Make sure to allow sufficient space in your div for the text to display properly. Here is an example using abbreviated month names with a Columns plot.

var chart = new Chart("simplechart");
chart.addPlot("default", {type: "Columns", gap:2});
chart.addAxis("x", {
	labels: [
		{value: 1, text: "Jan"}, {value: 2, text: "Feb"},
		{value: 3, text: "Mar"}, {value: 4, text: "Apr"},
		{value: 5, text: "May"}, {value: 6, text: "Jun"},
		{value: 7, text: "Jul"}, {value: 8, text: "Aug"},
		{value: 9, text: "Sep"}, {value: 10, text: "Oct"},
		{value: 11, text: "Nov"}, {value: 12, text: "Dec"}]
chart.addAxis("y", {vertical: true, leftBottom: true, min:1});
chart.addSeries("Series 1", [3, 2, 2, 3, 4, 5, 5, 7, 10, 2, 3, 14],
	{plot: "default", stroke: {color:"#466C89"}, fill: "#00E9FF"});


Data, it’s Series(ous) Business

Finally, we get to addSeries(), where we define the data sets that will be displayed on our chart. addSeries() accepts 3 parameters, a name, a data array and an options object. There is also an updateSeries() call that takes a name and data array for when you want to refresh your data. Let’s run through the parameters available in the addSeries() call, then look at the data array.

There are only a few parameters to cover for the addSeries() call. First up is stroke, which covers the color and width of your line or the border of your bar and column type graphs. Along with stroke we have fill, and it determines the color under the line in Areas type line graphs and determines the bar fill color for Bar and Column type graphs. If you are familiar with SVG or dojox.gfx, stroke and fill should be very familiar.

	"Series 1", 
	[1, 2, 4, 5, 5, 7], 
	{stroke: {color: "red", width: 2}, fill: "blue"}

The other option is marker and it allows you to define custom markers using SVG path segments. Here are the marker types as defined in dojox/charting/SimpleTheme. Note that each is just defined internally as an SVG path:

CIRCLE:		"m-3,0 c0,-4 6,-4 6,0 m-6,0 c0,4 6,4 6,0", 
SQUARE:		"m-3,-3 l0,6 6,0 0,-6 z", 
DIAMOND:	"m0,-3 l3,3 -3,3 -3,-3 z", 
CROSS:		"m0,-3 l0,6 m-3,-3 l6,0", 
X:		"m-3,-3 l6,6 m0,-6 l-6,6", 
TRIANGLE:	"m-3,3 l3,-6 3,6 z", 
TRIANGLE_INVERTED:"m-3,-3 l3,6 3,-6 z"

The marker style is handled by the theme you choose for your chart. However, if you did wish to add custom markers, you might do something like this:

chart.addSeries("Series 1", [1, 2, 2, 3, 4, 5, 5, 7], {
		stroke: { color: "purple", width: 2 },
		fill: "yellow",
		marker: "m0,-5 l5,5 -5,5 -5,-5 z"
chart.addSeries("Series 2", [1, 1, 4, 2, 1, 6, 4, 3],{
		plot: "someOtherPlot",
		stroke: {color:"#FFA100", width:1},
		fill: "blue",
		marker: (new SimpleTheme()).markers.TRIANGLE_INVERTED

Now take a look at these options in action using our above example:


The only thing we have left is the data array, and it’s just that, an array of data. All plot types can accept a one dimensional array, but there are some additional format options available based on the type of chart. With a 1 dimensional array for Line type graphs the X axis will be integers; [1,2,3…] and the data will be the Y axis. For Bar type plots the data is the length of the bar and the choice between Column or Bar type determines the orientation. And for Pie type charts the sum of the array is your whole pie. All the plot types except Pie can have multiple series.

chart.addSeries("Series A", [1, 2, 3, 4, 5]);

For any non-stacked Line plot type you can specify coordinate pairs. You need to use keys that correspond to the hAxis and vAxis parameters defined in the addPlot() call. These default to x and y.

chart.addSeries("Series A", 
	[{x: 1, y: 5}, {x: 1.5, y: 1.7}, {x: 2, y: 9}, {x: 5, y: 3}]);
chart.addSeries("Series B", 
	[{x: 3, y: 8.5}, {x: 4.2, y: 6}, {x: 5.4, y: 2}]);

Here is an example of using coordinate pairs with a Scatter plot:


With any of the stacked plot types each data set added with addSeries() is placed relative to the previous set. Here is a simple example that shows this concept. Instead of the second data set being a straight line across at 1, all the points are 1 above the point from the first data set.

chart.addPlot("default", {type:'Stacked'});
chart.addSeries("Series 1", [1, 2, 3, 4, 3]);
chart.addSeries("Series 2", [1, 1, 1, 1, 1], {stroke: {color: "red"}});

For Pie type charts you can specify additional information: the text label for each slice, the color of the slice and even a font color that overrides the font color definable in the addPlot() call.

chart.addPlot("default", {type:'Pie'});
chart.addSeries("Series A", [
	{y: 4, color: "#FFDBDB"},
	{y: 2, color: "#D0F2D2"},
	{y: 1, color: "#DBF1FF"},
	{y: 1, text: "Other", color: "white", fontColor: "red", size:14}


Charting your own course

That’s it! You now know all the basics of Dojo Charting. Congratulations! If you are wondering where to go from here, you will want to check out charting themes. They are simple to use with your charts by just calling setTheme(). There are dozens available and pretty straight forward if you want to make your own.

	function (Chart, Columns, PlotKitBlue) {
		var chart = new Chart("simplechart");
		chart.addPlot("default", {type: Columns, gap:2});
		chart.addAxis("y", {vertical: true, min:1});
		chart.addSeries("Series 1", [3, 2, 2, 3, 4, 5, 5, 7, 10, 2, 3, 14]);

You’ll also want to check out the Advanced Charting tutorial to learn more about Charting, as well as our charting blog posts on zomming, scrolling and panning, events and actions and tooltips themes, and legends.

Have fun!