A Ruby Library For Google Visualization API, GoogleVisualr

Date

Friday, Apr 16th, 2010

Buzz

Comments

5e56870f668a3cf2fead554c30adaa73 Del.icio.us

Post

In Wego, we have our own analytics and billing tool that I started building 2 years ago. This tool, in short, observes and logs user behaviour, digitizes and processes the data, then reports it on a Ruby on Rails front-end.

I named the tool aptly, Wegonomics.

Anyway, the very first version of Wegonomics only has numbers in rows and columns, and the metrics displayed were simply just a count of actions grouped by date.

However, I soon realized that a good and useful analytics dashboard is not only about the visual diarrhea of every possible numbers in tables.

What is a good analytics dashboard?

A good analytics dashboard provides insight to the numbers.
A good analytics dashboard highlights patterns and trends.
A good analytics dashboard helps one digests the numbers easily/quickly, and draws brilliant conclusions and decisions about them.

What’s essentially missing are charts – visual helpers for the numbers!

My initial search for a great-looking charting tool brought me to Open Flash Charts. Indeed, a useful charting tool! However, the Ruby on Rails libraries were disappointing, and it’s actually a hassle to integrate OFC into my system.

In the end, I found Google Visualization API, a Google developed JavaScript library that enables adding of charts into any web page.

In fact, the API actually powers quite a number of visuaizations in Google Analytics, which means I can recreate a Google Analytics look for my dashboard easily too.

This is the perfect solution for a great-looking and full-featured charting tool!

However, I need an easier way to integrate Google Visualization API into my system, without having to write data manipulation logic into RoR’s views or JavaScript files.

GoogleVisualr

Therefore, I created GoogleVisualr – a Ruby library for the Google Visualization API.

The Gist

In your model or controller, write Ruby code to create your visualization.

Configure your visualization with any options as listed in Google Visualization API Docs.

In your view, just call a visualization.render(div_id) method and the library will magically generate and insert JavaScript into the final HTML output.

You get your visualization, and you didn’t write any JavaScript!

Limitations

GoogleVisualr is created solely for the aim of simplifying the display of a visualization, and not the interactions.

Hence, do note that GoogleVisualr is not a 100% complete wrapper for the API.

To be precise, visualization-specific Methods and Events for use after a visualization has been rendered in a View have not been implemented (and may never be?), because they felt more native being written as JavaScript functions, in views/.js files.

Install

Clone the GitHub repository into your app/vendor/plugin folder.

> rails my_app
> cd my_app
> script/plugin install git://github.com/winston/google_visualr.git

Basics

1. In your Rails layout, load Google Ajax API in the head tag, at the very top.

<script src='http://www.google.com/jsapi'></script>

2. In your Rails controller, initialize a visualization with an empty constructor.

@chart = GoogleVisualr::AreaChart.new

3. Populate visualization with column headers, and row values.

# Add Column Headers
@chart.add_column('string', 'Year' )
@chart.add_column('number', 'Sales')
@chart.add_column('number', 'Expenses') 

# Add Rows and Values
@chart.add_rows(4)
@chart.set_value(0, 0, '2004')
@chart.set_value(0, 1, 1000)
@chart.set_value(0, 2, 400)
@chart.set_value(1, 0, '2005')
@chart.set_value(1, 1, 1170)
@chart.set_value(1, 2, 460)
@chart.set_value(2, 0, '2006')
@chart.set_value(2, 1, 1500)
@chart.set_value(2, 2, 660)
@chart.set_value(3, 0, '2007')
@chart.set_value(3, 1, 1030)
@chart.set_value(3, 2, 540)

4. Configure visualization with options.

@chart.width  = 400
@chart.height = 240

5. In your Rails view, render visualization.

<div id='chart'></div>
<%= @chart.render('chart') %>

Documentation and Example

The above is a basic example of getting started with the GoogleVisualr Ruby library. For more alternatives and examples in instantiating/configuring your visualization, please visit the reference site at http://googlevisualr.heroku.com.

Current available visualizations are: