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

By on November 9, 2012 2:00 am

Welcome! If you are looking for a way to quickly and easily add great looking and functional charts and graphs to your web pages, you’ve found the right place. All you need is a tiny bit of JavaScript skills and a copy of Dojo.

In this two part guide, we look at how easy it is to get Dojo Charting up and running with version 1.8, and then examine in greater detail the options available for different looks for your charts. Today in Part 1, we start with a basic example and then examine all the options available in defining your plot type. Part 2 will cover the options available in defining the axes and data sets for your charts.

Let’s get started. Here is the code for a basic Dojo Chart, with the minimum modules that need to be required. Make sure you have the proper path to your dojo.js file:

<html>
<head>
    <title>Chart</title>
</head>
<body>
    <div id="simplechart" style="width: 250px; height: 150px;"></div>
    <script src='../../dojo/dojo.js' data-dojo-config="async:true"></script>
    <script>
		require([
			"dojox/charting/Chart",
			"dojox/charting/plot2d/Lines",
			"dojox/charting/axis2d/Default",
			"dojo/domReady!"
			],
				function (Chart) {
					var chart = new Chart("simplechart");
					chart.addPlot("default", {type: "Lines"});
					chart.addAxis("x");
					chart.addAxis("y", {vertical: true});
					chart.addSeries("Series 1", [1, 2, 2, 3, 4, 5, 5, 7]);
					chart.render();
                });
    </script>
</body>
</html>

This source code produces the following simple chart.

Simple Chart

Looking at this we can see that most of the work in defining the chart is done in the addPlot(), addAxis(), and addSeries() functions. Today we will examine the addPlot() call, and Part 2 will cover the options for addAxis() and addSeries().

Got Plot?

The addPlot() call determines what type of chart you are going to produce, and there are a variety of options to select. Here are a few examples:

Tutorial Types

addPlot() accepts 2 arguments, a name and an options object. The name is important if you want to have more than 1 plot type on your chart, a concept we will cover shortly. The options object may vary depending on the type of plot you use. Note that your choice of plot type may define appropriate default options.

type is the main option, and the default value is a basic line chart, but it doesn’t hurt to indicate it anyway so that for other developers (or future-you) your intentions are clear:

chart.addPlot("default", {type: "Lines"});

Available 2D chart types include:

  • Areas – Area under data line(s) will be filled
  • Bars – Horizontal bars.
  • ClusteredBars – Horizontal bars with clustered data sets
  • ClusteredColumns – Vertical bars with clustered data sets
  • Columns – Vertical bars
  • Grid – For adding a grid layer to you chart
  • Lines – Basic line chart
  • Markers – Lines with markers
  • MarkersOnly – Markers, sans lines
  • Pie – Goes great with punch!
  • Scatter – Cooler name for MarkersOnly
  • Stacked – Data sets charted in relation to the previous data set.
  • StackedAreas – Stacked data sets with filled areas under chart lines
  • StackedBars – Stacked data sets with horizontal bars
  • StackedColumns – Stacked data sets with vertical bars
  • StackedLines – Stacked data sets using lines

A basic line-type chart includes Lines, Areas or Markers and have 5 specific options including, strangely enough, lines, areas, and markers. These are often defined by the plot type you choose, but can be changed to get your desired behavior. The lines option determines whether or not lines are used to connect your data points. If the areas type is selected, the area below your data line will be filled. The markers option will determine if markers are placed at your data points.

chart.addPlot("default", {type: "StackedAreas", lines: true, areas: true, 
	markers: false});

There are also 2 graphical options, tension and shadows. tension allows you to add some curve to the lines on your plot. By default this option is set to 0 which is off. I found 2-4 to be a good range for natural looking curves. For some crazy effects try setting this to values < 1 or negatives. shadows allow you to add a shadow effect, and consists of an object of 3 parameters, dx, dy and dw, which represent the offset to the right, the offset down, and the width of the shadow line, respectively. You can use negative values for your dx and dy parameters to produce a shadow that is to the left or above your chart line.

chart.addPlot("default", {type: "StackedLines",tension:3, 
	shadows: {dx: 2, dy: 2, dw: 2}});

Bar and Column graph types have 1 unique option: they will accept a gap parameter that determines the spacing between your bars or columns in pixels.

chart.addPlot("default", {type: "Bars", gap: 5});

For any chart type that supports axes, you can also define custom names to your axes here. By default they are “x” and “y”, but this option becomes useful if you wish to have a chart with multiple plots and multiple axes.

chart.addPlot("default", {type: "Bars", hAxis: "cool x", 
	vAxis: "super y"});

Pie charts are very different by nature, and have a separate list of parameters. I’ll leave it up to you to explore the parameters for the pie chart, from Pie.js:

defaultParams: {
	labels: true,
	ticks: false,
	fixed: true,
	precision: 1,
	labelOffset: 20,
	labelStyle: "default",      // default/rows/auto
	htmlLabels: true            // use HTML to draw labels
},
optionalParams: {
	font: "",
	fontColor: "",
	radius: 0
},

One other type with unique options is the Grid. This plot type will draw grid lines along your tick marks and supports the following four boolean options to determine if lines will be displayed at the horizontal or vertical, and major or minor axis tick marks. We will learn more about axes and look at a sample including the Grid type in Part 2. Remember to require dojox/charting/plot2d/Areas.

chart.addPlot("default", {type: "Grid",
        hMajorLines: true, 
        hMinorLines: false,
        vMajorLines: true,
        vMinorLines: false});

Now, let’s go back to our starting example and spruce it up a bit. Let’s add a shadow, some curve to our line, and markers on our data points.

chart.addPlot("default", {type: "Lines", markers: true, 
	tension:3, shadows: {dx: 2, dy: 2, dw: 2}});

And now our chart looks like this:

Tension

One last feature I’d like to touch on is adding multiple plots to the same chart. Multiple plots can be of differing types and can all be configured separately. Each plot you add with addPlot() will be layered behind the previous plot. In addition, plots can have their own axes or share them with other plots on the chart. Now, if we add an areas plot to our lines example, we can create the following effect.

require([
	"dojox/charting/Chart",
	"dojox/charting/plot2d/Lines",
	"dojox/charting/plot2d/Areas",
	"dojox/charting/axis2d/Default",
	"dojo/domReady!"
	],
	function (Chart) {
		var chart = new Chart("simplechart");
		chart.addPlot("default", {type: "Lines"});
		chart.addPlot("someOtherPlot", {type: "Areas"});
		chart.addAxis("x");
		chart.addAxis("y", {vertical: true});
		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"});
		chart.render();
	});

Plots

Continue reading Part 2 of Dojo Charting with AMD where we will cover the options available in the addAxes() and addSeries() calls.