YUI Sparkline Widget « Chicken of the Web

Edward Tufte’s sparklines are a nice way to present small minimal graphs in contexts where larger, full charts are not needed or warranted. The growing support for the HTML <canvas> tag gives an opportunity to create these graphs dynamically in Javascript.

(Download yahoo-widget-sparkline-1.0b.zip.)

This widget was built against YUI version 2.7.0 but may work in other versions. It subclasses the “charts” module and is easily loaded via YUILoader. The test.html creates a auto-updating sparkline based on a simple FunctionDataSource within a paragraph of text.

Features:

If passed a height of “font-size” or “line-height” will cause the module to examine the CSS of the element to which it will be rendered to determine its height. This allows you to easily insert a sparkline into blocks of text without worrying about scaling the graph by hand.
By default it will remove all content within the element that will contain the <canvas>. This allows “alt=” type data to be displayed when <canvas> is not available.
Arbitrary highlighting of points with custom colors.
mean, median, standard deviation and arbitrary “normal” range shading.
Uses the Chart object’s polling setup to auto-update charts by re-polling the DataSource.

Usage:

Pull in the module:

var loader = new YAHOO.util.YUILoader();
loader.addModule({ name: 'sparklinecss', type: 'css',
                   fullpath: 'Sparkline.css'});
loader.addModule({ name: 'widget.Sparkline', type: 'js',
                   requires: ['charts', 'sparklinecss'],
                   fullpath: 'Sparkline.js'});
loader.require('widget.Sparkline', 'datasource', 'element');

Then create a sparkline:

var sl = new YAHOO.widget.Sparkline("sparkline-container",
                                    myDataSource,
                                    { height: 20, yField: "value" });
sl.subscribe("sparklineUpdate", updateHandler);

Configuration Options:

max: Force a maximum y-value. Default is the largest value in the data.
min: Force a minimum y-value. Default is the smallest value in the data.
width: Width of the graph. Default is one pixel per data point.
height: A pixel value or “font-size” or “line-height”. Default is 20 pixels.
logscale: Change the y-axis to a logarithmic scale.
clearParent: Remove any children of the node passed to render() before adding the canvas. Default true
zero, mean, median: Add horizontal lines at the appropriate places. Each can have a boolean true value or a string specifying the color for the line.
stddev: Calculate the standard deviation of the data and shade the background between +/- one standard deviation from the mean. Can be true or a color.
normal: An object with two or three fields: min, max, and (optionally) color. A background rectangle covering the range will be drawn in the specified (or default) color.
color: Graph color
highlightPoints: An array of two-field objects: x and color. x is the index of the point in data to highlight and color is the color to use. x-values of max and min highlight the maximum and minimum values. An x-value of -1 highlights the last point in the data.

To Do:

Graceful failure when <canvas> is unavailable.
Allow graphing of data extracted from HTML markup.

(updated 7/7/2009)

Chicken of the Web