| CARVIEW |
NASDAQ: Loading.. 1353.74 (close 1/28-3/4)
DOW: Loading.. 6875.84 (close 1/29-3/4)
SF Giants: Loading.. Last game 9/28
jQuery Sparklines
About
25 Feb 2009
Version 1.4 Released
This jQuery plugin generates sparklines (small inline charts) directly in the browser using data supplied either inline in the HTML, or via javascript.
The plugin is compatible with most modern browsers and has been tested with Firefox 2+, Safari 3+, Opera 9 and Internet Explorer 6 & 7.
Each example displayed below takes just 1 line of HTML or javascript to generate.
The plugin was written by Gareth Watts for Splunk Inc and released under the New BSD License.
Examples
Pie charts 1,1,2 1,5 20,50,80
Bullet charts
10,12,12,9,7
14,12,12,9,7
10,12,14,9,7
Mouse speed Loading..
Inline 10,8,9,3,5,8,5 line graphs 8,4,0,0,0,0,1,4,4,10,10,10,10,0,0,0,4,6,5,9,10
Bar charts 10,8,9,3,5,8,5 negative values: -3,1,2,0,3,-1
Composite inline 8,4,0,0,0,0,1,4,4,10,10,10,10,0,0,0,4,6,5,9,10
Inline with normal range 8,4,0,0,0,0,1,4,4,10,10,10,10,0,0,0,4,6,5,9,10
Composite bar 4,6,7,7,4,3,2,1,4
Discrete 4,6,7,7,4,3,2,1,4,4,5,6,7,6,6,2,4,5
Discrete with threshold 4,6,7,7,4,3,2,1,4
Customize size and colours 10,8,9,3,5,8,5,7
Tristate charts
1,1,0,1,-1,-1,1,-1,0,0,1,1
(think games won, lost or drawn)
Tristate chart using a colour map: 1,2,0,2,-1,-2,1,-2,0,0,1,1
Box Plot: 4,27,34,52,54,59,61,68,78,82,85,87,91,93,100
Pre-computed box plot Loading..
News
25 February 2009 - Version 1.4 Released
This version adds box plots 4,27,34,52,54,59,61,68,78,82,85,87,91,93,100
suggested by Daniel Kadosh. What's a box plot?.
This release also includes a few bug fixes including one where lines would not always appear crisp in canvas based browsers such as Firefox.
Also at this time IE8 RC1 is out.. It looks like sparklines work fairly well in this release, although the small circles used in line charts, box plots, etc. don't show up.
25 January 2009 - Version 1.3 Released
This version fixes some positioning issues on all platforms and adds some support for
Internet Explorer 8. IE 8 beta 2 (the latest beta release) seems to have some VML bugs though
that I haven't been able to work around yet, so the results aren't perfect.
This version also adds a new function called $.sparkline_display_visible() - Call this anytime sparklines that were drawn into a non-displayed element may have just become visible so that they will be correctly rendered. For example, this site uses the function to make sure sparklines displayed in the various tabbed pages are drawn when the tab is selected.
Finally I updated the site and docs somewhat as the old layout was looking a little cramped.
21 November 2008 - Version 1.2.1 Released
Fixes a couple of pie chart bugs; no new features.
19 November 2008 - Version 1.2 Released
Some important bug fixes amongst some basic new features:
- Added zeroColor option to bar charts
- Line, bart and discrete charts can now be plotted within a fixed value range using chartRangeMin and chartRangeMax - Useful if you want several different charts to use the same scale (though not very sparkline-ish)
- Line charts can now explicitly set the width of each value with defaultPixelsPerValue while allowing the chart as a whole to remain dynamically sized
- The start angle for pie charts can now be modified with an offset option
- Line charts can specify both the x and y values now; previously the x values were assumed to be sequential from 0 (and still are by default)
See the changelog for the complete list of changes.
14 August 2008 - Using Sparklines with Splunk
I gave a quick 5 minute demo at the Splunk Developers Boot Camp
on using the Splunk PHP SDK with jquery.sparkline.js to chart the traffic
this page received within the first few days of its launch.
Check out the short write up i posted to the new Splunk Wiki for the code and data I used to make it work (it was really easy) and if you download your own free copy of Splunk you can try it yourself ;-)
29 July 2008 - Version 1.1 Released
Thanks for the suggestions for improvements - This version fixes several bugs and adds some more features and chart types including
- Composite graphs (overlay one graph on top of another)
- Pie charts
- Bullet graphs
- Discrete charts
- Min/max spots for line charts
- Normal range marking for line charts
See the changelog for the complete list of changes.
17 July 2008 - Version 1.0 Released
Initial version released
Documentation
Quick Start
To add some sparklines to your web page you need four things:
- The jQuery javascript library loaded into the page - At least version 1.2 or higher
- A copy of jquery.sparkline.js loaded into the page which you can download from this site
- An inline tag on the page within which to display the sparkline (eg. <span>)
- A call to the sparkline() function to actually display the sparkline.
Here's a simple web page that will display a couple of sparklines:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<script type="text/javascript" src="jquery-1.2.6.js"></script>
<script type="text/javascript" src="jquery.sparkline.js"></script>
<script type="text/javascript">
$(function() {
$('.inlinesparkline').sparkline();
$('.dynamicsparkline').sparkline([10,8,5,7,4,4,1]);
});
</script>
</head>
<body>
<p>
Inline Sparkline: <span class="inlinesparkline">1,4,4,7,5,9,10</span>.
</p>
<p>
Sparkline with dynamic data: <span class="dynamicsparkline">Loading..</span>
</p>
</body>
</html>
Click here to open this example in a new window.
As the example shows, the values to be used in a sparkline can either be supplied inline, inside the tag to be used as the target or can be passed as the first parameter to the sparkline() function.
To draw different types of charts, or overlay one on top of another, or display charts into hidden layers, read on.
Syntax
$(selector).sparkline(values, options);
Values can either be an array of numbers or "html" which causes the values to be read from from the selected tag:
<span class="sparklines">1,2,3,4,5,4,3,2,1</span>
<span id="ticker"">Loading..</span>
$('.sparklines').sparkline('html');
$('#ticker').sparkline([1,2,3,4,5,4,3,2,1]);
Options is an object that specifies the type of sparkline to draw, colours to use, etc
$('#barchart').sparkline(myvalues, { type:'bar', barColor:'green' });
Common Options
- type - line (default), bar, tristate, discrete, bullet or pie
- width - Width of the chart - Defaults to 'auto' - May be any valid css width - 1.5em, 20px, etc - This option does nothing for bar and tristate chars (see barWidth)
- height - Height of the chart - Defaults to 'auto' (line height of the containing tag)
- lineColor - Used by line and discrete charts
- fillColor
- chartRangeMin - Specify the minimum value to use for the range of the chart - Defaults to the minimum value supplied
- chartRangeMax - Specify the maximum value to use for the range of the chart - Defaults to the maximum value supplied
- composite - If true then don't erase any existing chart attached to the tag, but draw another chart over the top - Note that width and height are ignored if an existing chart is detected.
Hidden Sparklines
If you try to display a sparkline in a tag that's currently not visible (ie. the tag or one of its parents are set to display:none) then you'll find that the sparkline hasn't been rendered when you finally make the tag visisble. This is because a hidden tag has no size so we can't detect the area to draw on.
The solution is to call the $.sparkline_display_visible() function anytime a sparkline may have become visible so that it can be correctly rendered. This is the technique this site uses to handle the sparklines that are hidden in the different tabbed sections.
Line Chart Options
Line charts are the default chart type, but to specify the type explicitly set an option called "type" to "carview.php?tsp=line".
- defaultPixelsPerValue - Defaults to 3 pixels of width for each value in the chart
- spotColor - Set to false or an empty string to hide the final value marker
- minSpotColor - Set to false or an empty string to hide the minimum value marker
- maxSpotColor - Set to false or an empty string to hide the maximum value marker
- spotRadius - In pixels (default: 1.5)
- normalRangeMin, normalRangeMax Specify threshold values between which to draw a bar to denote the "normal" or expected range of values. For example the green bar here 80,85,84,88,98,114,116,104,95,85,84 might denote a normal operating temperature range.
- xvalues - See below
By default the values supplied to line charts are presumed to be y values mapping on to sequential (integer) x values. If you need to specify both the x and y values for your chart, you have a few options:
- Inline: x and y values are separated by a colon: x:y,x:y,x:y - eg. <span class="linechart">1:3,2.7:4,4.8:3</span>
- Array of arrays: An array of [x,y] arrays: $('#linechart').sparkline([ [1,3], [2.7,4], [4.8,3] ]);
- Separate arrays: Pass x values separately: $('#linechart').sparkline([3,4,3], { xvalues: [1,2.7,4.8]});
Bar Chart Options
-3,1,2,0,3,-1
Set the "type" option to "carview.php?tsp=bar" to generate bar charts.
- barColor - Colour used for postive values
- negBarColor - Colour used for negative values
- zeroColor - Colour used for values equal to zero
- barWidth - Width of each bar, in pixels
- barSpacing - Space between each bar, in pixels
- zeroAxis - Centers the y-axis at zero if true (default is to automatically do the right thing)
Tristate Chart Options
Set the "type" option to "carview.php?tsp=tristate" to generate tristate charts.
- posBarColor - Colour for positive (win) values
- negBarColor - Colour for negative (lose) values
- zeroBarColor - Colour for zero (draw) values
- barWidth - Width of each bar, in pixels
- barSpacing - Space between each bar, in pixels
- zeroAxis - Centers the y-axis at zero if true (default is to automatically do the right thing)
- colorMap - Map override colors to certain values - For example if you want all values of -2 to appear yellow, use colorMap: { '-2': '#ff0' }
Discrete Chart Options
Set the "type" option to "carview.php?tsp=discrete" to generate discrete charts.
- lineHeight - Height of each line in pixels - Defaults to 30% of the graph height
- thesholdValue - Values less than this value will be drawn using thresholdColor instead of lineColor
- thresholdColor
Bullet Graph Options
Set the "type" option to "carview.php?tsp=bullet" to generate bullet graphs.
See the wikipedia page for more information on Bullet graphs.
Supplied values must be in this order: target, performance, range1, range2, range3, ...
- targetColor - The colour of the vertical target marker
- targetWidth - The width of the target marker in pixels
- performanceColor - The color of the performance measure horizontal bar
- rangeColors - Colors to use for each qualitative range background color
Pie Chart Options
1,5
20,50,80
Set the "type" option to "carview.php?tsp=pie" to generate pie charts.
These little pie charts tend only to be useful with 2 or 3 values at most
- sliceColors - An array of colors to use for pie slices
- offset - Angle in degrees to offset the first slice - Try -90 or +90
Box Plot Options
Loading..
See the wikipedia page for more information on Box plots
- raw - If set to false (default) then the values supplied are used to caculate the box data points for you. If true then you must pre-calculate the points (see below)
- showOutliers - If true (default) then outliers (values > 1.5x the IQR) are marked with circles and the whiskers are placed at Q1 and Q3 instead of the least and greatest value
- outlierIQR - Set the inter-quartile range multipler used to calculate values that qualify as an outlier - Defaults to 1.5x
- boxLineColor - Line colour used to outline the box
- boxFillColor - Fill colour used for the box
- whiskerColor - Colour used to draw the whiskers
- outlierLineColor - Colour used to draw the outlier circles
- outlierFillColor - Colour used to fill the outlier circles
- spotRadius - Radius to draw the outlier circles
- medianColor - Colour used to draw the median line
- target - If set to a value, then a small crosshair is drawn at that point to represent a target value
- targetColor - Colour used to draw the target crosshair, if set
- minValue - If minvalue and maxvalue are set then the scale of the plot is fixed. By default minValue and maxValue are deduced from the values supplied
- maxValue - See minValue
Set the "type" option to "box" to generate box plots.
As noted in the options above, by default "raw" is set to false. This means that you can just pass an arbitrarily long list of values to the sparkline function and the corresponding box plot will be calculated from those values. This is probably the behaviour you want most of the time.
If, on the other hand, you have thousands of values to deal with you may want to pre-compute the points needed for the box plot. In that case, set raw=true and pass in
the computed values. If showing outliers, supplied values of:
low_outlier, low_whisker, q1, median, q3, high_whisker, high_outlier
Omit the outliers and set showOutliers to false to omit outlier display.
License
This plugin is copyright Splunk Inc and licensed using the New BSD License
Download
Note: jquery.sparkline.js is a plugin for jQuery - You need to include both on your page to generate sparklines.
Version 1.4:
- jquery.sparkline.js (Uncompressed - 41KB)
- jquery.sparkline.min.js (Minified - 22kB)
- jquery.sparkline.min.js.gz (Minified & gzipped - 4.7KB)
Version 1.3:
- jquery.sparkline.js (Uncompressed - 34kB)
- jquery.sparkline.min.js (Minified - 18kB)
- jquery.sparkline.min.js.gz (Minified & gzipped - 4.0KB)
Version 1.2.1:
- jquery.sparkline.js (Uncompressed - 33kB)
- jquery.sparkline.min.js (Minified - 18kB)
- jquery.sparkline.min.js.gz (Minified & gzipped - 3.9Kb)
Who's Using It
Are you using jquery.sparkline on your project or site? Send me a quick email and I'll add a link here!
Current users include: