Check out the awesome demos

demo1 Demo 1 · Fill

demo2 Demo 2 · Bars

demo3 Demo 3 · Bubbles

GraphUp is flexible jQuery plugin that allows you to spice up your plain data tables in a snap. Table data is visualized using colors, bar charts or bubbles right in the table itself.

Installation

Step 1 · Load the script

For starters, you include the required javascript files in the <head> of your HTML document.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.2/jquery.min.js"></script>
<script src="path/to/your/jquery.graphup.min.js"></script>

Note that in the snippet above, I am loading a Google hosted jQuery copy. You can host it yourself too. Then, you load the GraphUp Plugin. Remember to change the src path to match the location of the file on your server.

Step 2 · Showtime!

All that is left to do, is to connect your table cells (not the whole table) with the GraphUp Plugin. Append the following piece of javascript to the <head> of your HTML file. Alternatively, you could move it to an external file.

<script>
$(document).ready(function() {

	// Here we're "graphing up" only the cells with the "data" class
	$('#your_table td.data').graphup({
		// Define any options here
		colorMap: 'thermometer',
		painter: 'bubbles',
		bubblesDiameter: 80 // px
		// ...
	});

});
</script>

Have a look at the demos to see some real code in action. Have fun!

Options

Options listed in alphabetical order

Option Description
barsAlign string · Default: 'left'
This option is related to the bars painter. Use it to set the alignment of the bar charts. The following settings are available:
  • left
  • right
  • top
  • bottom
  • hcenter (horizontally centered)
  • vcenter (vertically centered)
bubblesDiameter number · Default: null
This option is related to the bubbles painter. Use it to set the maximum diameter (in pixels) of a bubble. By default the maximum diameter will be the double of the cell height.
callBeforePaint callback · Default: null
Callback that is fired right before a cell will be painted. At this point the cell has been cleaned and its value and percentage are stored with it. You can access those using the jQuery.data method: this.data('value') and this.data('percent'). The whole cell element itself is available as this in your callback function.
classBar string · Default: 'bar'
The CSS class that will be used for each bar.
classBubble string · Default: 'bubble'
The CSS class that will be used for each bubble.
cleaner string or function · Default: 'basic'
A cleaner is a function that will look at the contents of cell and turn it into a clean number. The following cleaners are available out of the box:
  • basic: whitespace will be trimmed, but no other operations are done on the cell value. Use this if your table contains clean numeric data.
  • strip: all non-numeric characters will be deleted before converting the cell's value to a number. Handy in case your cells contain a unit of measurement, e.g. $15.99, 16,50 euro, 1024 kB, etc.
  • seconds: a duration in seconds will be calculated for time values like hh:mm:ss or mm:ss. The last parts (seconds) may even be followed by milliseconds. E.g. marathon world record: 2:03:59.671.
  • minutes: a duration in seconds will be calculated for time values like hh:mm, without a part for seconds.
You can create your own cleaners too.
colorMap string or array · Default: 'heatmap'
Many painters will use a color map to colorize their graphs. A color map basically defines a gradient (going from 0% to 100%) from which a color will be picked according to a cell's percentage. The following color maps are available out of the box:
  • burn:
  • grayPower:
  • greenPower:
  • heatmap:
  • thermometer:
You can also provide a custom color map by providing an array of one or more RGB colors. Note that the gradient will always be evenly spaced out.
E.g.: [[255,255,255], [0,0,0]] (white to black).
You can predefine your own color maps too.
decimalPoint string · Default: '.'
The separator for the decimal point, either . (period) or , (comma).
defaultValue number · Default: null
It may happen that some cell values can't be cleaned properly. By default those cells will be ignored and won't be painted. However, if you provide a default value for those cells, they will be treated normally.
max number · Default: null
In order to calculate a percentage we need to know the highest value. By default this will be the highest value GraphUp can find in the provided cells. However, the highest value might not be present in any cell. This option allows you to set it manually.
min number · Default: null
In order to calculate a percentage we need to know the lowest value. By default this will be the lowest value GraphUp can find in the provided cells. However, the lowest value might not be present in any cell. This option allows you to set it manually.
painter string or function · Default: 'fill'
This function makes the magic happen. It visualizes the cell's value. The following painters are available out of the box:
  • bars: draws a bar chart in a cell. Make sure your cells have the same size, otherwise the bars will not be in good proportion to each other.
    You can define the CSS class and alignment of the bars.
  • bubbles: draws a circle in the middle of a cell. If the browser doesn't support CSS border‑radius, it will be squares. This is the case for IE8 and below.
    You can define the CSS class and diameter for the circles.
  • fill: paints the background of a cell.
You can create your own painters too.

Global defaults

You can easily change the default values for the options listed above. Just include the following javascript. This only needs to be called once. Of course, you can set all options to whatever you like.

$.fn.graphup.defaults = {
	cleaner: 'strip',
	painter: 'bars'
	// Etcetera
}

Custom cleaners

You can create a custom cleaner by defining a new method for the $.fn.graphup.cleaners object. Then simply set the cleaner option to the name of your method.

$.fn.graphup.cleaners.myCleaner = function(value, options) {
	// The value argument contains the uncleaned cell value.
	// The options argument contains the options object.
	// The function should simply return the cleaned value.
	return parseFloat(value);
}

Custom painters

You can create a custom painter by defining a new method for the $.fn.graphup.painters object. Then simply set the painter option to the name of your method.

$.fn.graphup.painters.myPainter = function($cell, options) {
	// The $cell argument contains the cell as jQuery object.
	// The options argument contains the options object.
	// Demo: we're replacing the cell's content with its percentage value.
	$cell.text($cell.data('percent') + '%');
}

Have a look at the unpacked source code of the plugin for more examples. The code is well documented.

Custom predefined colorMaps

You can provide an array with a custom color map to the colorMap option. However, if you end up using the same color scheme again, it is a good idea to predefine your own colorMap.

$.fn.graphup.colorMaps.myColorMap = [[255,255,255], [0,0,0]];