Notice: There is a newer version of this post available

As mentioned in Zooming, Scrolling, and Panning in Dojo Charting, our next goal to tackle was charting events. I am happy to announce that event support for Charting has landed in the Dojo trunk, and shipped with Dojo 1.2. It was the most requested dojox.charting feature, and I am excited that it is finally here!

Now you can interact with following elements representing your data points:

Chart Element Comment
Default marker This chart is responsible for lines and areas with markers, and the scatter chart.
Stacked marker This chart is responsible for stacked lines and areas.
Bars bar Horizontal bars.
StackedBars bar  
ClusteredBars bar A clustered version of bars.
Columns column Vertical columns.
StackedColumns column  
ClusteredColumns column A clustered version of columns.
Bubble circle  
Pie slice  

The Following events are supported: onclick, onmouseover, and onmouseout.

Users can attach event handlers to individual plots of a chart:

chart.connectToPlot(
    plotName,    // the unique plot name you specified when creating a plot
    object,      // both object and method are the same used by dojo.connect()
    method       // you can supply a function without an object
);

The event handler receives one argument. While it tries to unify information for different charts, its exact layout depends on the chart type:

Attribute Expected Value Description
type “onclick”, “onmouseover”, or “onmouseout” Use this attribute to differentiate between different types of events.
element “marker”, “bar”, “column”, “circle”, or “slice” Indicates what kind of element has sent the event. Can be used to define highlighting or animation strategies. For details consult the previous table.
x number The “x” value of the point. Can be derived from the index (depends on a chart).
y number The “y” value of the point. Can be derived from the index (e.g., for a bar chart).
index number The index of a data point that caused the event.
run object The data run object that represents a data series. Example: o.run.data[o.index] — returns the original data point value for the event (o is an event handler’s argument).
plot object The plot object that hosts the event’s data point.
hAxis object The axis object that is used as a horizontal axis by the plot.
vAxis object The axis object that is used as a vertical axis by the plot.
event object The original mouse event that started the event processing.
shape object The gfx shape object that represents a data point.
outline object The gfx shape object that represents an outline (a cosmetic shape). Can be null or undefined.
shadow object The gfx shape object that represents a shadow (a cosmetic shape). Can be null or undefined.
cx number The “x” component of the visual center of a shape in pixels. Supplied only for “marker”, “circle”, and “slice” elements. Undefined for all other elements.
cy number The “y” component of the visual center of a shape in pixels. Supplied only for “marker”, “circle”, and “slice” elements. Undefined for all other elements.
cr number The radius in pixels of a “circle”, or a “slice” element. Undefined for all other elements.

Pie chart screenshot

And finally it is time to see it in action: the event demo straight from the Dojo nightly. Hover over markers, bars, columns, bubbles, and pie slices, and click on them as well.

Besides dojox.charting, the demo illustrates some other parts of Dojo as well:

  • dojo.fx — the Dojo Core animation toolkit for creating and combining animations.
    • dojox.fx.easing — a collection of easing functions to spice up visual effects.
    • dojox.gfx.fx — 2D graphics-specific animation helpers.
  • dojox.lang.functional — power of functional programming at your fingertips.

All of these components make it possible to code up the demo rather quickly — the modular nature of Dojo pays off.

Coming Attractions

In working with events, I was acutely aware of the need for animation support. I want to package up some useful animation effects for chart interactions. The demo previews some possibilities.

Other big features waiting for some attention are integration with widgets and markup support. The former includes interactions with the tooltip widget, and the upcoming Chart Legend widget. Markup support allow creation of some simple interactive charts using just marked-up HTML, with virtually no additional JavaScript.

Stay tuned!