Dojox Charting Tutorial – Part Three: Column and Bar Charts

In Part One (http://hermes.intec.co.uk/Intec/Blog.nsf/dx/10012010214412HERTH7.htm) I have given some background and generic code quired on any page showing a dojo chart. In Part Two (http://hermes.intec.co.uk/Intec/Blog.nsf/dx/12012010175038HERNX7.htm) I added a series using javascript onto my XPage and generated a pie chart. In Part Three I will cover the other two chart types shown on my first demo page (http://hermes.intec.co.uk/XPagesSamples/Charts.nsf/Chart1.xsp), column charts and bar charts.

Adding the Series

If you try to apply the series we generated for the pie chart to a column or bar chart, you will find you get no data plotted. This is because of a limitation on the column and bar charts, that they will not accept an array of objects (http://trac.dojotoolkit.org/ticket/7992), just a one-dimensional array of values. So you can show your end user, e.g., a bar chart with bars and on your y axis show the numbers. But what does each bar denote? If your y axis has tick steps (the difference between one label and another on the axis) for 100s or 1000s, how do you tell the user the actual value of each bar? If you add a legend to a bar or column chart, as we did for the pie chart, the legend only labels the overall series, not the individual elements of the series. You could add a table as well, but you wouldn’t want to show both on a dashboard of various charts.

If you’ve followed the link and then continued onto the dojo forum, there is a workaround. Even with the answer it took me a little while to understand how to implement it and I couldn’t find an example. So hopefully this will help anyone else get a head-start in using bar or column charts.

So first I add a Computed Field control to hold the values, calling it SeriesB. I’ve used the same approach of looping through view entries, writing a comma-delimited list of numbers, stripping off the final comma:

I then add a second Computed Field control to hold the tooltip I want to attach to each bar, and I call that SeriesBTooltip. The code is identical except for the “output += …” line – I’m getting the Contract Name and appending the value in brackets, so I get something like this:

“ABC DEVELOPMENT (3)”,”ABC SUPPORT (5)”,”ACME EDI/AS2 DEVELOPMENT (1)”,”ACME SALES DOCUMENT REPOSITORY (6)”,

I then just need to push these two series into client-side javascript variables, using an additional Computed Field control with the cape property set to “false” so it is rendered as HTML rather than plain text. This was the Computed Field control from Part One, shown below with the two new series highlighted.

There is no reason why this could not be done with an HTML data table, as shown in Chris Connor’s sample charts (http://www.xsptalk.com/public/website/blog.nsf/dx/13112009111014CCOF4X.htm), or any other method using a repeat control.

Creating the Column Chart

The code to create the bar and column charts is virtually the same – one displays the values horizontally, the other displays them vertically. This shows the same data I displayed in the pie chart.

First I create the chart variable, set the theme, and add the plot with type as “Columns” or “Bars”. An additional parameter is available for these two chart types, called gap, to define the gap between each bar / column. Then I add an axis for whichever axis is measuring the values (y axis for the column chart, x axis for the bar chart). The other axis will only have bars on it.

The axis has two parameters, a name and an array of options. The name corresponds to the name of an axis defined on a plot. The default axis names are x (horizontal) and y (vertical). The optional parameters are listed in the screenshot. Min and max allow you to fix the upper and lower limits of the axis, as I have done in the column chart. However, it seems that a line is still shown where the end of the column would have finished. Instead of “min: 0” I could have used “includeZero: true”. For the parameters affecting ticks, see the bar chart.

Then, at line 172, I add the series of numbers – series2. Finally I add the animation. For column and bar charts the shake, magnify and moveSlice animations don’t seem to work, so all I’m doing is highlighting the default plot on chart2, changing the bar colour to black.

So far the chart will look nice, but will not tell the user what information is being presented. I could add a legend, but as you will see from the bar chart, this is not particularly informative. I could add custom axis labels to the x axis, but the labels are horizontal, so they would not show correctly. Tooltips seem to be the best option, but the default tooltip will just show what is in series2, the number of open calls. Fortunately Eugene Lazutkin posted an answer on the dojotoolkit forum (http://dojotoolkit.org/forum/dojox-dojox/dojox-support/custom-tooltips-clusteredbars-chart), code to override the text function of the dojox.charting.action2d.Tooltip.

As with the normal tooltip code and any other animation, the first two parameters are the javascript variable I’ve used for the chart (chart2) and the plot I’m applying this tooltip to (“default”). Unlike the normal tooltip code I used for the pie chart, but like the other animations, I then add an object containing further properties. Here I override the text parameter with a different function (text: funcon(o) {…}). o is the series that the plot uses, so series2. You can see from the code above the list of parameters o can contain, the important one being o.index. This returns 0 for the first bar, 1 for the second bar etc. So as the code attaches a tooltip, it uses that bar’s index number to get the relevant value from the series2Tooltip javascript array we created earlier. The outcome is that the tooltip, instead of just showing the number of open calls also shows the contract name, helping to clarify the chart for the user.

Creating the Bar Chart

The bar chart is very similar, so I’ve used a few additional settings. The ticks parameters allow you to define parameters for the markers on the axis, as I have for the bar chart example:

So here I’m showing minorTicks, forcing the minorTickStep to be evey 5 and the microTickStep to be every 1. I found that if I set the maximum to 20, bars (or columns) of 1 open call were shown. However, when I allowed the axis to default to the largest bar, bars of 1 open call didn’t show. By forcing the microTickStep to 1, this ensures they do appear. For the majorTick I’m adding an additional object to set the colour of the font, the colour of the stroke and the length. As with all the properties, defaults are used if you dso not explicitly define them, and can be found in the javascript file. By now I’m sure you’ve worked out where to find the files, but if not, it’s Datadominojsdojo-1.3.2dojoxchartingChart2D.js.

I’ve also updated the demo page to show what happens if you add a legend to a bar or column chart. As mentioned, all that is presented is the title for series 1. This makes it somewhat limiting. Also because its a single series all the bars are the same colour, so even if I created the legend manually, it’s going to be difficult to identify the bars.

In the next part I will move onto line charts, created in two different ways.