== Rgviz-rails

This library makes it easy to implement a Visualization data source so that you can easily chart or visualize your data from ActiveRecord[http://ar.rubyonrails.org/] models or from in-memory arrays. The library implements the {Google Visualization API wire protocol}[http://code.google.com/apis/visualization/documentation/dev/implementing_data_source.html].

It also allows you to {render the visualizations in a view template}[https://github.com/asterite/rgviz-rails/wiki/Showing-a-visualization-in-a-view] in a very simple but powerful way.

This library is built on top of rgviz[https://github.com/asterite/rgviz].

=== Installation

  gem install rgviz-rails

=== Rails 3

In your Gemfile

  gem 'rgviz'
  gem 'rgviz-rails', :require => 'rgviz_rails'

=== Rails 2.x

In your environment.rb

  config.gem "rgviz"
  config.gem "rgviz-rails", :lib => 'rgviz_rails'

=== Usage

To make a method in your controller be a visualization API endpoint:

  class VizController < ApplicationController

    def person
      # Person is an ActiveRecord::Base class
      render :rgviz => Person
    end

  end

So for example if +Person+ has +name+ and +age+, pointing your browser to:

  http://localhost:3000/viz/person?select name where age > 20 limit 5

would render the necessary javascript code that implements the Google Visualization API wire protocol.

=== Extensions

To enable the extensions defined by rgviz you need to specify it in the render method:

  render :rgviz => Person, :extensions => true

=== Associations

If you want to filter, order by or group by columns that are in a model's association you can use underscores. This is better understood with an example:

  class Person < ActiveRecord::Base
    belongs_to :city
  end

  class City < ActiveRecord::Base
    belongs_to :country
  end

  class Country < ActiveRecord::Base
  end

To select the name of the city each person belongs to:

  select city_name

To select the name of the country of the city each person belongs to:

  select city_country_name

A slightly more complex example:

  select avg(age) where city_country_name = 'Argentina' group by city_name

The library will make it in just one query, writing all the SQL joins for you.

=== Extra conditions

Sometimes you want to limit your results the query will work with. You can do it like this:

  render :rgviz => Person, :conditions => ['age > ?', 20]

Or also:

  render :rgviz => Person, :conditions => 'age > 20'

=== Preprocessing

If you need to tweak a result before returning it, just include a block:

  render :rgviz => Person do |table|
    # Modify the Rgviz::Table object
  end

=== Showing a visualization in a view

You can invoke the rgviz method in your views. {Read more about this}[https://github.com/asterite/rgviz-rails/wiki/Showing-a-visualization-in-a-view].

You can always do it the {old way}[http://code.google.com/apis/visualization/documentation/using_overview.html].

=== Executing queries over in-memory arrays

You can also apply a query over an array of arrays that contains your "records" to be queried.

  types = [[:id, :number], [:name, :string], [:age, :number]]
  records = [
    [1, 'John', 23],
    [2, 'Pete', 36]
  ]
  executor = Rgviz::MemoryExecutor.new records, types

  render :rgviz => executor

This is very useful if you need to present visualizations against data coming from a CSV file.

=== Current Limitations
* The *format* clause is ignored (If someone knows of a working icu library for ruby, please tell me)
* Only supports MySQL, PostgreSQL and SQLite adapters
* These scalar functions are not supported for SQLite: *millisecond*, *quarter*
* These scalar functions are not supported for MySQL: *millisecond*
* The function *toDate* doesn't accept a number as its argument
* The *tsv* output format is not supported