Winston{yw}

These are the slides I presented at Singapore Ruby Brigade meetup on 14th April 2010, updated and uploaded to SlideShare. Enjoy!

Resources

• GoogleVisualr Source
• GoogleVisualr Reference/Examples

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:

• Annotated Time Line
• Area Chart
• Bar Chart
• Column Chart
• Gauge
• Spark Line (Image)
• Intensity Map
• Line Chart
• Map
• Motion Chart
• Organizational Chart
• Pie Chart
• Scatter Chart
• Table

Contribution and Support

The source of GoogleVisualr is available on GitHub. Go head and clone/fork it!

Please also submit all feedback, bugs and feature-requests to GitHub Issues Tracker.

Resources

• Google Visualization API
• GoogleVisualr Slides

Ruby comes with an implementation of SOAP (SOAP4R), a protocol for exchanging XML-based messages, and recently, I had a chance to use this library. Having no knowledge of the SOAP4R library, I conveniently consulted the Pickaxe book which was on my table, and it presented me with an excellent overview of the library.

Now, I’m going to document the two different approaches of connecting to a SOAP API which I have learned from the book, so that I don’t forget them easily. I recommend the Pickaxe book if you are interested in more detailed explanations.

Xurrency is an online currency conversion service which I am using in one of my projects and Xurrency’s API is based in SOAP. The API has several methods exposed and I’ll only be using one of them in my examples, but the principle is the same for other method invocations.

The method that I’ll be using is: float getValue(float $amount, string $base, string target) which returns a float value for a currency conversion.

First Example

#Require The Library
require 'soap/rpc/driver'

#Connections
endpoint = 'http://www.xurrency.com/servidor_soap.php'
proxy    = SOAP::RPC::Driver.new(endpoint)

#Add Method
proxy.add_method('getValue', 'amount', 'base', 'target')

#Call API Method and Get Exchange Rate
rate = proxy.getValue('1','usd','eur')
puts 'Rate: #{rate}'

The output:

sh> ruby currency.rb
Rate: 0.6787

Second Example

#Require The Library
require 'soap/wsdlDriver'

#Connections
wsdl_url = 'http://xurrency.com/api.wsdl'
proxy    = SOAP::WSDLDriverFactory.new(wsdl_url).create_rpc_driver

#Call API Method and Get Exchange Rate
rate = proxy.getValue(1,'usd','eur')
puts 'Rate: #{rate}'

The output:

sh> ruby currency.rb
Rate: 0.6787

In the first example, I created a local proxy for the Xurrency API, adds the method which I want to use, and then invokes it.

In the second example, I made use of a WSDL (Web Services Description Language) document available at http://xurrency.com/api.wsdl. This WSDL document describes the Xurrency API, and so SOAP can read this WSDL and perform dynamic discovery of the API interfaces which removes the need to add the getValue method explicitly.

To quote from the Pickaxe book, a WSDL document is:

..an XML document that describes the types, methods, and access mechanisms for a Web services interface. SOAP clients can read WSDL file to create the interfaces to a server automatically..

Despite the differences when connecting to the SOAP API, the underlying concept is similar for both the examples. The SOAP library creates local proxies that SOAP uses to connect to the remote server API (which is published by a SOAP server). When a method is invoked on the local proxy, the invocation is passed to the corresponding API interface on the server via XML. The server then processes the method invocation, and the returned values are passed back to the client through the proxy.

What I have written are just some basic concepts of using SOAP with Ruby. But it’s really simple right? For further reading, please refer to the RubyDoc, or the Trac (which has some great examples too).

For a rubygem that wraps Xurrency’s API, there’s one on GitHub, authored by Keita. Alternatively, my colleague Douglas has also created a simple currency converter which uses the data from Yahoo Finance.

For those who are on Windows, but yet wish to install Ruby Thin Server on your PC, here’s a short how-to.

Ruby Thin Server requires the following dependencies:

• Rack
• EventMachine

Unfortunately, the latest version of EventMachine (0.10.0 at the time of this post) is not a Win32 binary release, so it’s a hassle trying to get it installed on Windows. Instead, your best choice would be to download an earlier version of EventMachine 0.8.1, which is a Win32 binary release.

Even though it’s an earlier version, I have not encountered any problems with it. Of course, I am using Windows only for development purposes, and not for production purposes.

Install each dependency by following the steps below before you install Thin.

1. Install Rack.

c:\> gem install rack

2. Download EventMachine 0.8.1

Download. Install EventMachine locally.
c:\> gem install eventmachine -l

3. Install Ruby Thin Server, but ignore dependencies.

c:\> gem install thin –ignore-dependencies

Following these steps should install Ruby Thin Server successfully on your Windows machine.

Update from Google Groups:
Thin has been updated to install EventMachine 0.8.1 if you are on Windows. But you can always rely on the steps above if something fails.