Dojo Charting: Widgets, Tooltips, and Legend

By on June 12, 2008 12:06 am
Notice: There is a newer version of this post available

According to the previous article (Dojo Charting: Event Support Has Landed!) the next items on our plan for improving Dojo Charting are the widgetization of charting, events, and integration with the Tooltip widget. In addition to all of these features now being available in trunk, the Legend widget was developed. These features will all be available in the release of Dojo 1.2.

Actions

Actions are self-contained objects, which use events to implement certain effects when users interact with a chart. In general they are designed to attract attention and indicate which charting element is selected, or to show additional information.

While you can create your own actions, we took liberty to package some generally useful actions. The default library contains five classes: Highlight, Magnify, MoveSlice, Shake, and Tooltip. All of them take advantage of the Dojo animation support. It is the best to see them live on the demo page (it demonstrates examples of legends as well).

All actions except Tooltip support the following common keyword parameters:

Name Type Default Description
duration Number 400 the time of effect in milliseconds.
easing Function dojox.fx.easing.elasticOut the easing function that specifies how controlled parameter changes over time.

 

You can further experiment with easing functions at DojoCampus.

Highlight

This action highlights (changes a color by modifying a fill) individual elements of a chart, when a user hovers over an element with the mouse. Affected elements include: markers, columns, bars, circles, and pie slices.

Highlight supports one additional parameter:

Name Type Default Description
highlight String, dojo.Color, or Function the default highlight function this parameter defines the highlight color for an individual element.

 

The parameter can be any valid value for a color, e.g., “red”, “#FF0000”, “#F00”, [255, 0, 0], {r: 255, g: 0, b: 0}, and so on. In this case this color will be used to fill an element.

If the parameter is a function, it receives a charting event object (see the previous article for details), and should return a valid color.

The default highlight function uses special heuristics to select the highlight color. It makes it fully saturated, and light for dark colors, or dark for light colors. In many cases this default is more than adequate. But if you feel a need to implement a custom highlighting scheme, you can easily create your own function.

The picture below demonstrates Highlight (with a constant color) and Tooltip actions.

Highlight and Tootltip

Magnify

This action magnifies an individual element of a chart, when users hover over them with the mouse. Affected elements include markers and circles.

Magnify supports one additional parameter:

Name Type Default Description
scale Number 2 the value to scale an element.

 

The picture below demonstrates Magnify and Tooltip actions.

Magnify and Tooltip

MoveSlice

This action moves slices out from a pie chart, when users hover an element with the mouse.

MoveSlice supports the following parameters:

Name Type Default Description
scale Number 1.5 the value to scale an element.
shift Number 7 the value in pixels to move an element from the center.

 

The picture below demonstrates MoveSlice, Highlight (with default highlighting parameter), and Tooltip actions.

MoveSlice, Highlight, and Tooltip

Shake

This action shakes charting elements, when users hover over an element with the mouse. Affected elements include markers, columns, bars, circles, and pie slices.

Shake supports the following parameters:

Name Type Default Description
shiftX Number 3 the maximal value in pixels to move an element horizontally during a shake.
shiftY Number 3 the maximal value in pixels to move an element vertically during a shake.

 

Shake is the highly dynamic effect, so a picture cannot do a justice for it. Please go to the demo page and see it in action.

Tooltip

This action shows a Tooltip, when users hover over a charting element with the mouse. Affected elements include markers, columns, bars, circles, and pie slices.

Tooltip supports the following keyword parameters:

Name Type Default Description
text Function the default text function the function to produce a Tooltip text.

 

The default text function checks if a data point is an object, and uses an optional “Tooltip” member if available — this is a provision for custom Tooltips. Otherwise, it uses a numeric value. Tooltip text can be any valid HTML, so you can specify rich text multi-line Tooltips if desired.

The picture below demonstrates Tooltip, and Highlight actions.

Tooltip and Highlight

Using Actions

All action objects implement the following methods (no parameters are expected by these methods):

Name Description
connect() Connect and start handling events. By default, when an action is created, it is connected. You may need to call fullRender() on your chart object to activate the sending of messages. Typically you create an action object after you define plots, but before the first render() call — it takes care of everything.
disconnect() Disconnect the event handler.
destroy() Call this method when you want to dispose of your action. It disconnects from its event source and destroys all internal structures, if any, preparing to be garbage-collected.

 

All actions can be constructed like this:

var a = new dojox.charting.action2d.Magnify(
  chart1, 
  "default", 
  {duration: 200, scale: 1.1});

The first parameter is a chart. The second parameter is the name of a plot. The third parameter is an object (property bag) with all relevant keyword parameters.

An even easier options is to use the Chart2D widget. The example below is taken from the Dojo Chart2D widget test:

Yes, it is that simple: just define a <div> with the class “action” and supply the type. If you want to specify a plot’s name, use the “plot” parameter: plot=”Plot1″. By default it will connect to the plot named “default”. If you want to change default keyword parameters, just add them to the <div>, e.g., duration=”500″.

As you can see from the example above you can mixin several actions. In order to avoid unnecessary interference between actions, use your best judgment when selecting them. Try to avoid actions that modify the same visual attributes, like geometry. You can safely mix Tooltip, Highlight, and one geometric action (Magnify, MoveSlice, or Shake).

Legend

Finally one of the most requested features has landed: the legend widget. This widget was contributed by Chris Mitchell of IBM. It can handle all existing chart and plot types and supports horizontal and vertical modes.

Charts and Legends

By default it uses the “legend” parameter of a series. It reverts to the “name” parameter if legend is not specified.

For a pie chart, the behavior is different: if the chart was specified with an array of numbers, it will use numbers. Otherwise it will check object properties in the following order: “legend”, “text”, and the numeric value.

Pie Chart and Legend

Coming Attractions

This article on charting may be the last one before the Dojo 1.2 release. We’re starting work on planned features for Dojo 1.3 and future releases.

The next area we plan to explore is financial charts. We will create new plots including the Bullet plot, and the Box plot (a.k.a. the Candle). Financial charting is not complete without the timeline axis. The latter one is extremely complex mostly due to the fact that we need to calculate business days skipping bank holidays, and there are several ways to accomplish this. Thankfully within the Dojo community we have several committers versed in these problems who will help us get there quickly.

Stay tuned!

Comments

  • Bob Foley

    You’re doing an amazing work!

  • Dan

    Excellent work Eugene! I am really eagerly anticipating dojo 1.2 and the charting updates, it will make such a difference.

    Thanks also for spending time writing these tutorial updates as it makes getting started with the new features much much easier.

    So basically…thanks!!!

  • Thank you guys for encouraging words! Obviously I need to write a formal documentation and it is on my TODO list.

  • David

    Very cool stuff!

    One question, is there anyway to get events working with lines? I’d really like to be able to provide tooltips when the user hovers a line in the graph rather than having to draw markers for every point (there a lot of them).

  • Line-based events are possible but not implemented in this round mostly because the interface to the hover/click information is more complex. If you have good ideas about that, feel free to contact me directly (eugene at this domain), and we will see what we can do about more sophisticated scenarios.

  • NMZ

    Eugene,

    as far as the “extremely complex” part of the financial charts. I think you may be overcomplicating the matter. Financial data tends to come in the form of OHLC associated with a date. Have your user input all of it (OHLA and date) into an index value in an array. Then just display the data in the array assuming its in the right order. I think the complexity of the whole holiday and weekend thing is unnecessarily complex.

  • Sun

    Cool stuff!
    why dojo 1.2 charts(bars,columns etc) doesn’t show the full series values ( if the series count > 12 )? Is there any way to override the default setting

    Excellent Work !

  • Thank you for good words.

    There are no numeric restrictions on number of series nor on their size. Make sure you don’t set any undue restrictions on axes.

    PS: It is better to ask support-level questions in the Dojo forums: http://dojotoolkit.org/forum (use DojoX Support) — more people can help you there.

  • Psy

    What an and awesome job!
    Will be actions for canvas rendering or is it too limited for that?

  • Its a great job, i got a prob here, i could not able to destroy the legend as well flush.

  • @Psy: Canvas doesn’t support events, so, by transition, it doesn’t support actions. I hope it’ll change some day.

  • @rana: please file a bug ticket with a minimalistic example on how to reproduce it. It may be fixed by now, if not, I’ll make sure it will be fast-tracked.

  • Bradley

    Any luck creating the bullet chart?

    (Horizontal stacked bar with a status line showing actual performance)

    I have really been looking for a bullet solution using Dojo and I just landed on your blog. It looks like all the elements are there.

    Thanks for everything – I will start playing with what is available.

  • @Bradley: not yet, but we do accept patches (hint, hint). ;-)

  • Eric

    I’m intrigued by the Chart2D Widget pie example above. Is it possible to pull labels and tooltip values from a store in addition to the raw numeric values? I’ve used Dojo pie charts in a couple of places, and simply hooking them up to a standard store would be quite a bit cleaner than what I’ve been doing.

  • @Eric: right now only simple data is extracted from a store. Anything above that should be done with a special adapter written by a programmer. But the fuller dojo.data store support is in the road map for charting.

  • Luigi

    Hi all,

    any suggestions about update/redraw chart legend ?

    where is the problem in my code?

    Luigi

    Basic Charting

    dojo.require(“dojox.charting.Chart2D”);
    dojo.require(“dojox.charting.widget.Legend”);

    makeCharts = function(){

    chart1 = new dojox.charting.Chart2D(“simplechart”);
    chart1.addPlot(“default”, {type: “Lines”, markers: true, tension:3, shadows: {dx: 2, dy: 2, dw: 2}});
    chart1.addAxis(“x”);
    chart1.addAxis(“y”, {vertical: true});
    chart1.addSeries(“Series 1”, [1, 2, 2, 3, 4, 5, 5, 7]);
    chart1.render();
    legend1 = new dojox.charting.widget.Legend({chart: chart1, horizontal: false}, “legend1”);
    legend1.chart=chart1;
    }
    dojo.addOnLoad(makeCharts);
    function graifco1()
    {
    legend1.destroy();
    chart1.destroy();
    chart1 = new dojox.charting.Chart2D(“simplechart”);
    chart1.addPlot(“default”, {type: “Lines”, markers: true, tension:0, shadows: {dx: 2, dy: 2, dw: 2}});
    chart1.addAxis(“x”);
    chart1.addAxis(“y”, {vertical: true});
    chart1.addSeries(“Series 2”, [1, 2, 2, 3, 4, 5, 5, 7]);
    chart1.render();
    legend1 = new dojox.charting.widget.Legend({chart: chart1, horizontal: false}, “legend1”);
    legend1.chart=chart1;
    }

  • seshank

    I am trying to build a chart which can be edited by user by simply dragging the line in the chart.Is this possible?

  • GoinOff

    This is a nice general overview but gives NO coding examples to
    help newbies out. Please provide more code examples or references
    to them. Tooltip won’t work unless you remember this in your
    html:

    and include class=’tundra’ on the body tag in your html. Anyhow,
    with more coding examples and pointers, it makes it easier to
    implement features in your chart.

  • Jacob_A

    Newbie to dojo/dijit here. Sorry.

    Has anyone tested charting with IE8? I set up a pretty simple pie chart successfully and got it working with FF3.0.13 just fine, and it works with IE8 in “compatibility mode” but not in normal mode.

    One other thing I noticed was that I have a vertical legend set up in a separate TD to the right of the pie chart. In FF3.0.13 it is top-aligned, while in IE8 compatibility mode it is center-aligned. I tried adding style=”vertical-align:middle;” tags to both the DIV and the TD tags, but neither works in FF.

    Any thoughts on either of these?

    Thanks a bunch for your great work, this charting package is really helpful!!!

  • Kadri

    @Eric: i have the same problem.Please if u have any idea tell me. am in a short of idea.

  • Demo page link is broken.

    http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/charting/tests/test_event2d.html

    I remember it was working two days ago. Can you please restore the demo link at the earliest. Thank you.

  • They’ve been temporarily removed as we’re reworking a bit how we do our automated builds… they will be back shortly. In the interim, if you go back about a week, the tests are there for previous nightly builds.

    Regards,
    -Dylan

  • Abhijit

    Hi,
    I tried adding tooltip to a column chart, but it seems the tooltip are displayed at the bottom of the page, please help me….
    Below is my chart code:

    var chart3 = new dojox.charting.Chart2D(“simplechart”);
    chart3.addAxis(“y”, {vertical: true, fixLower: “major”, fixUpper: “major”});
    chart3.addPlot(“default”, {type: “Columns”, gap: 2});
    chart3.addSeries(“Series A”, [1, 2, 3, 4, 5], {stroke: {color: “black”}, fill: “red”});
    chart3.addSeries(“Series B”, [5, 4, 3, 2, 1], {stroke: {color: “black”}, fill: “blue”});
    var anim3a = new dojox.charting.action2d.Highlight(chart3, “default”);
    var anim3b = new dojox.charting.action2d.Tooltip(chart3, “default”);

    chart3.render();

  • Hi, I am using dojo toolkit for generating charts. I have used pie charts, where i gave custom tooltip as

    chart1.addSeries(“Series 1″, [{x:1,y:4,tooltip:”Value is 1″},
    {x:2,y:6,tooltip:”Value is 2”}]);

    Similarly, i want to use this feature in ClusteredBars/ClusteredColumns also.
    Please Please, Can anyone kindly suggest me how to give custom-tooltip in ClusteredBars/ClusteredColumns type charts in dojo? :(

    Thanks in advance, SuryaPavan

  • svatrege

    In order to see tooltips you must add to your head tag :

    – “../../dojo/dijit/themes/” is the arborescence where is situated the folder themes
    – “soria” is one of the differents themes of tooltips (there are also : nihilo, tundra..)

    Moreover you must add to your body tag : class = “name_of_the_theme”,
    here with soria you will write :

    Regards.