mlnsvbd / jquery-visualize Goto Github PK

Accessible data visualization in HTML has always been tricky to achieve, particularly because elements such as images allow only the most basic features for providing textual information to non-visual users. A while back, we wrote an article describing a technique we came up with to use JavaScript to scrape data from an HTML table and generate charts using the HTML 5 Canvas element. The technique is particularly useful because the data for the visualization already exists in the page in structured tabular format, making it accessible to people who browse the web with a screen reader or other assistive technology.

We've now rewritten and extended the code behind this technique and packaged it up as a new jQuery plugin called "visualize", which you can download below. The plugin provides a simple method for generating bar, line, area, and pie charts from an HTML table, and allows you to configure them in a variety of ways.

First, a quick demo

In the example below, we have an HTML table populated with sample data of a number of employees and their sales by store department. We've generated 4 charts from this table, which are shown below.

View this example in a new window So how does it work?

First, you'll need to create the table markup:

Note that we've used a caption element to summarize the table data. This will be used by the visualize plugin to create a title on your graph. We've also defined our table headings using th elements, letting the script know which cells it should use as the titles for a data set.

Now that we have our HTML table, we can generate a chart. Just attach jQuery and our visualize plugin's JavaScript and CSS files to your page, and call the visualize() method on the table, like this:

$('table').visualize();

That's it! By default, the visualize plugin will generate the first bar chart shown above and append it to your page directly after the table.

Working with a generated chart

Finding the generated chart on the page

Once you call the visualize() method on a table, the new chart element will be returned to the method, allowing you to continue your jQuery chain acting upon the chart instead of the table. Charts generated by this plugin are contained within a div element with a class of "visualize" as well as a class of the chart type, such as "visualize-pie". These classes make it easy to find your chart after it's generated, for additional presentation and behavioral modifications. Another nice way to do this is to store your generated chart in a variable, like this: var myChart = $('table').visualize();. Then you can simply reference myChart later on in your script to make any modifications to it, or to remove it from the page.

Updating a chart

Every chart generated by the visualize plugin has a custom event that can be used to refresh itself using its original settings, including which table it should pull data from. This is handy for dynamic pages with charts that can update frequently. In fact, we made use of this event when creating the editable table example above. To refresh an existing chart, simple trigger the visualizeRefresh event on the generated chart element, like this:

$('.visualize').trigger('visualizeRefresh');

Appending the chart to other areas of the page

Since calling the visualize() method returns the new chart element, it's easy to immediately append the chart to another area of the page using jQuery's appendTo method. However, once you move the chart to another area in the DOM, you must trigger the visualizeRefresh method on it in order for it to display properly in Internet Explorer 6 and 7. The following code demonstrates appending the chart to the end of the page, and then triggering the visualizeRefresh method on it:

$('table') .visualize() .appendTo('body') .trigger('visualizeRefresh');

Use CSS to Configure the Text

The CSS file that accompanies the visualize plugin handles much of the presentation for the key, title, grid lines, and axis labels. So for instance, if you need to change the placement of the key, simply edit the CSS rules that apply to it (we customized the key in the pie chart example above using this same approach).

Configuring Visualize with options

The following options are available in this plugin:

* type: string. Accepts 'bar', 'area', 'pie', 'line'. Default: 'bar'.
* width: number. Width of chart. Defaults to table width
* height: number. Height of chart. Defaults to table height
* appendTitle: boolean. Add title to chart. Default: true.
* title: string. Title for chart. Defaults to text of table's Caption element.
* appendKey: boolean. Add the color key to the chart. Default: true.
* colors: array. Array items are hex values, used in order of appearance. Default: ['#be1e2d','#666699','#92d5ea','#ee8310','#8d10ee','#5a3b16','#26a4ed','#f45a90','#e9e744']
* textColors: array. Array items are hex values. Each item corresponds with colors array. null/undefined items will fall back to CSS text color. Default: [].
* parseDirection: string. Direction to parse the table data. Accepts 'x' and 'y'. Default: 'x'.
* pieMargin: number. Space around outer circle of Pie chart. Default: 20.
* pieLabelPos: string. Position of text labels in Pie chart. Accepts 'inside' and 'outside'. Default: 'inside'.
* lineWeight: number. Stroke weight for lines in line and area charts. Default: 4.
* barGroupMargin: number. Space around each group of bars in a bar chart. Default: 10.
* barMargin: number. Creates space around bars in bar chart (added to both sides of each bar). Default: 1

To use the options, simply pass them as an argument to the visualize() method using object literal notation, just like most other jQuery plugins you're used to ( for example: visualize({ optionA: valueA, optionB: valueB});).

Live Options Configuration Demo

To experiment with these options, try out the following configuration demo:

View this example in a new window

Download the Code!

You can download the scripts and a demo page in the following zip file: visualize.filamentgroup.zip. The plugin itself is licensed for free distribution with MIT and GPL licenses, just like jQuery itself.

Browser Support

We have tested this plugin in the following browsers: IE6, IE7, IE8, Firefox 2, Firefox 3.5, Safari 3 and 4, Opera 9.

Note for Internet Explorer support

This plugin uses the HTML 5 canvas element, which is not supported in an version of Internet Explorer at this time. Fortunately, Google maintains a library that translates canvas scripting into VML, allowing it to work in all versions of internet explorer. The script is included in the zip. To use it, just be sure to include the script in your page using a conditional comment, like this:

Still to-do

While this plugin is fairly feature-complete and works well across the major browsers, we would like to consider implementing the following features:

* Key text formatting: The ability to configure the text in the keys to show member title, total percentage, total amount, and more
* Interactivity: We may experiment with adding datapoint tooltips, and other ways to interact with the visualization.
* Support for data subsets: The ability to specify a subset of the table rows and columns for visualizing.