google_visualr 0.0.1 → 2.0.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+*.gem
+.bundle/*

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format nested

data/.rvmrc

@@ -0,0 +1 @@
+rvm use ruby-1.9.2-p180@google_visualr --create

data/Gemfile

@@ -0,0 +1,4 @@
+source :gemcutter
+
+# Specify your gem's dependencies in gv.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,25 @@
+PATH
+  remote: .
+  specs:
+    google_visualr (2.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.0.15)
+  google_visualr!
+  rspec (>= 2.6.0)

data/MIT-LICENSE

@@ -1,21 +1,22 @@
 The MIT License
 
-Copyright (c) 2010 Winston Teo Yong Wei
+Copyright (c) 2011 Winston Teo Yong Wei
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
+and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in
 all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
+OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -1,92 +1,103 @@
 = Overview
 
-This Ruby library, GoogleVisualr, is a wrapper around the {Google Visualization API}[http://code.google.com/apis/visualization/documentation/] and allows you to create the same visualizations with just pure Ruby;
-you don't have to write any JavaScript at all.
+This Ruby gem, GoogleVisualr, is a wrapper around the {Google Chart Tools}[http://code.google.com/apis/chart/interactive/docs/index.html] that allows anyone to create the same beautiful charts with just plain Ruby.
+
+You don't have to write any JavaScript at all!
 
 Good for any Ruby on Rails setup whereby you prefer to work your logic in models or controllers.
 
-Please refer to the {GoogleVisualr reference site}[http://googlevisualr.heroku.com/] for a complete list of visualizations that you can create with GoogleVisualr.
+Please refer to the {GoogleVisualr API Reference site}[http://googlevisualr.heroku.com/] for a complete list of Google charts that you can create with GoogleVisualr.
+
+== Differences Between Gem and Plugin
+
+Gem
+* is Rails 3 compatible.
+* implements many of the newer versions of Google Charts E.g. Core Charts.
+* enjoyed a major refactoring, and also now has Tests!
+
+Plugin
+* has not been tested for Rails 3 compatibility
+* implements the older versions of Google Charts.
+* has deprecated methods.
+
+This gem, however, is not a drop-in replacement for the plugin, as there are numerous changes in its usage.
+
+Notably, you will have to interact mostly with GoogleVisualr::DataTable which was absent in the plugin.
 
 == The Gist
 
-* In your model or controller, write Ruby code to create your visualization (e.g. Area Chart, Bar Chart, even Spark Lines etc).
-* Configure your visualization with all the options as listed in Google Visualization API Docs. E.g. {Area Chart's configuration options}[http://code.google.com/apis/visualization/documentation/gallery/areachart.html#Configuration_Options].
-* In your view, just call a <em>visualization.render(div_id)</em> method that will magically generate and insert JavaScript into the final HTML output.
-* You get your visualization, and you didn't write any JavaScript!
+* In your model or controller, write Ruby code to create your chart (e.g. Area Chart, Bar Chart, even Spark Lines etc).
+* Configure your chart with any of the options as listed in Google Chart Tools' API Docs. E.g. {Area Chart's Configuration Options}[http://code.google.com/apis/chart/interactive/docs/gallery/areachart.html#Configuration_Options].
+* In your view, invoke a <em>chart.to_js(div_id)</em> method and that will magically generate and insert JavaScript into the final HTML output.
+* You get your awesome Google chart, and you didn't write any JavaScript!
 
 == Limitations
 
-Do note that GoogleVisualr is not a 100% complete wrapper for the Google Visualization API. These are not implemented for sake of simplicity:
-* JavaScript Methods for use after a visualization has been rendered in a view. E.g. {Area Chart's methods}[http://code.google.com/apis/visualization/documentation/gallery/areachart.html#Methods].
-* JavaScript Events for use after a visualization has been rendered in a view. E.g. {Area Chart's events}[http://code.google.com/apis/visualization/documentation/gallery/areachart.html#Events].
-* Visualizations not created by Google, and a few image-only charts.
+GoogleVisualr is created solely for the aim of simplifying the display of a chart, and not the interactions.
+
+Hence, do note that GoogleVisualr is not a 100% complete wrapper for Google Chart Tools.
+
+For example, Methods and Events as described in Google Chart Tools' API Docs, for use after a chart has been rendered, are not implemented because they felt more native being written as JavaScript functions, within views or .js files.
 
 = Install
 
-Just install the GitHub repository into your app/vendor/plugin folder.
+Assuming you are on Rails 3, include the gem in your Gemfile.
 
-  > rails my_app; cd my_app;
-  > script/plugin install git://github.com/winston/google_visualr.git
+  gem "google_visualr", ">= 2.0"
 
 = Basics
 
-This section describes a basic implementation of the GoogleVisualr::AreaChart class.
+This section describes a basic implementation of the GoogleVisualr::DataTable and GoogleVisualr::AreaChart classes.
+
+For detailed documentation and advanced implementations, please refer to the {GoogleVisualr API Reference site}[http://googlevisualr.heroku.com/] or read the source.
 
-Please review the {Docs}[http://googlevisualr.heroku.com/docs] for detailed documentation and advanced implementation of constructors and methods.
 ---
 
 In your Rails layout, load Google Ajax API in the head tag, at the very top.
 
   <script src='http://www.google.com/jsapi'></script>
 
-In your Rails controller, initialize a visualization (area chart) with an empty constructor.
+In your Rails controller, initialize a GoogleVisualr::DataTable object with an empty constructor.
 
-  @chart = GoogleVisualr::AreaChart.new
+  data_table = GoogleVisualr::DataTable.new
 
-Populate visualization with column headers, and row values.
+Populate data_table with column headers, and row values.
 
   # Add Column Headers
-  @chart.add_column('string', 'Year' )
-  @chart.add_column('number', 'Sales')
-  @chart.add_column('number', 'Expenses')
+  data_table.new_column('string', 'Year' )
+  data_table.new_column('number', 'Sales')
+  data_table.new_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)
-
-Configure visualization with options.
-
-  @chart.width = 400
-  @chart.height = 240
-
-In your Rails view, render visualization.
+  data_table.add_rows([
+    ['2004', 1000, 400],
+    ['2005', 1170, 460],
+    ['2006', 660, 1120],
+    ['2007', 1030, 540]
+  ])
+
+Create a GoogleVisualr::AreaChart with data_table and configuration options.
+
+  option = { width: 400, height: 240, title: 'Company Performance' }
+  @chart = GoogleVisualr::Interactive::AreaChart.new(data_table, option)
+
+In your Rails view, render the Google chart.
 
   <div id='chart'></div>
-  <%= @chart.render('chart') %>
+  <%= raw @chart.to_js('chart') %>
 
 = Support
 
-Please submit all feedback, bugs and feature-requests to {GitHub Issues Tracker}[http://github.com/winston/google_visualr/issues].
+Please feel free to fork the project, make improvements or bug fixes and submit pull requests. Ideally, all pull requests should also come with tests!
 
-Please also feel free to clone/fork the project, and improve it further!
+Please submit all feedback, bugs and feature-requests to {GitHub Issues Tracker}[http://github.com/winston/google_visualr/issues].
 
 = Author
 
-GoogleVisualr is maintained by {Winston Teo}[mailto:winstonyw+googlevisualr@gmail.com], and his Ninja Penguin.
+GoogleVisualr is maintained by {Winston Teo}[mailto:winstonyw+googlevisualr@gmail.com].
 
-Who is Winston Teo? Find out more on {WinstonYW}[http://www.winstonyw.com], {LinkedIn}[http://sg.linkedin.com/in/winstonyw], or {follow Winston on Twitter}[http://www.twitter.com/winstonyw].
+Who is Winston Teo? {You should follow Winston on Twitter}[http://www.twitter.com/winstonyw], or find out more on {WinstonYW}[http://www.winstonyw.com] and {LinkedIn}[http://sg.linkedin.com/in/winstonyw].
 
 = License
 
-Copyright © 2010 Winston Teo Yong Wei. Free software, released under the MIT license.
+Copyright © 2011 Winston Teo Yong Wei. Free software, released under the MIT license.

data/Rakefile

@@ -1,33 +1,12 @@
-# Rake Hook
+# Bundler Gem Tasks
+require 'bundler'
+Bundler::GemHelper.install_tasks
 
-require 'rubygems'
-#Gem::manage_gems
-require 'rake/gempackagetask'
+# RSpec Tasks
+require 'rspec/core/rake_task'
 
-PKG_FILES = FileList[
-  '[a-zA-Z]*',
-  'generators/**/*',
-  'lib/**/*',
-  'rails/**/*',
-  'tasks/**/*',
-  'test/**/*'
-]
- 
-spec = Gem::Specification.new do |s|
-  s.name = "google_visualr"
-  s.version = "0.0.1"
-  s.author = "Winston Teo"
-  s.email = "winston.yongwei+spam at gmail.com"
-  s.homepage = "https://github.com/winston/google_visualr"
-  s.platform = Gem::Platform::RUBY
-  s.summary = "Wrapper around the Google Visualization API."
-  s.files = PKG_FILES.to_a
-  s.require_path = "lib"
-  s.has_rdoc = false
-  s.extra_rdoc_files = ["README.rdoc"]
-end
- 
-desc 'Turn this plugin into a gem.'
-Rake::GemPackageTask.new(spec) do |pkg|
-  pkg.gem_spec = spec
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = ['--options', '.rspec']
 end
+
+task :default => :spec

data/google_visualr.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path("../lib/google_visualr/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "google_visualr"
+  s.version     = GoogleVisualr::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Winston Teo"]
+  s.email       = ["winston.yongwei+google_visualr@gmail.com"]
+  s.homepage    = "https://github.com/winston/google_visualr"
+  s.summary     = "A Ruby wrapper around the Google Chart Tools that allows anyone to create the same beautiful charts with just plain Ruby."
+  s.description = "This Ruby gem, GoogleVisualr, is a wrapper around the Google Chart Tools that allows anyone to create the same beautiful charts with just Ruby; you don't have to write any JavaScript at all."
+  s.extra_rdoc_files = ["README.rdoc"]
+
+  s.required_rubygems_version = ">= 1.3.6"
+  s.rubyforge_project         = "google_visualr"
+
+  s.add_development_dependency "bundler", ">= 1.0.15"
+  s.add_development_dependency "rspec"  , ">= 2.6.0"
+
+  s.files        = `git ls-files`.split("\n")
+  s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+  s.require_path = 'lib'
+end

data/lib/google_visualr.rb

@@ -0,0 +1,39 @@
+lib_path = File.dirname(__FILE__)
+
+# Common
+require "#{lib_path}/google_visualr/param_helpers"
+
+# Base Classes
+require "#{lib_path}/google_visualr/data_table"
+
+require "#{lib_path}/google_visualr/packages"
+require "#{lib_path}/google_visualr/base_chart"
+
+require "#{lib_path}/google_visualr/formatters"
+
+# Interactive Charts
+
+## Main
+require "#{lib_path}/google_visualr/interactive/area_chart"
+require "#{lib_path}/google_visualr/interactive/bar_chart"
+require "#{lib_path}/google_visualr/interactive/candlestick_chart"
+require "#{lib_path}/google_visualr/interactive/column_chart"
+require "#{lib_path}/google_visualr/interactive/combo_chart"
+require "#{lib_path}/google_visualr/interactive/gauge"
+require "#{lib_path}/google_visualr/interactive/geo_chart"
+require "#{lib_path}/google_visualr/interactive/line_chart"
+require "#{lib_path}/google_visualr/interactive/pie_chart"
+require "#{lib_path}/google_visualr/interactive/scatter_chart"
+require "#{lib_path}/google_visualr/interactive/table"
+require "#{lib_path}/google_visualr/interactive/treemap"
+
+## Additional
+require "#{lib_path}/google_visualr/interactive/annotated_time_line"
+require "#{lib_path}/google_visualr/interactive/intensity_map"
+require "#{lib_path}/google_visualr/interactive/map"
+require "#{lib_path}/google_visualr/interactive/motion_chart"
+require "#{lib_path}/google_visualr/interactive/org_chart"
+
+# Image Charts
+require "#{lib_path}/google_visualr/image/spark_line"
+

data/lib/google_visualr/base_chart.rb

@@ -0,0 +1,40 @@
+module GoogleVisualr
+
+  class BaseChart
+    include GoogleVisualr::Packages
+    include GoogleVisualr::ParamHelpers
+
+    attr_accessor :data_table
+
+    def initialize(data_table, options={})
+      @data_table = data_table
+      send(:options=, options)
+    end
+
+    def options
+      @options
+    end
+
+    def options=(options)
+      @options = stringify_keys!(options)
+    end
+
+    # Generates JavaScript and renders the Google Chart in the final HTML output.
+    #
+    # Parameters:
+    #  *div_id            [Required] The ID of the DIV element that the Google Chart should be rendered in.
+    def to_js(element_id)
+      js  = "\n<script type='text/javascript'>"
+      js << "\n  google.load('visualization','1', {packages: ['#{package_name}'], callback: function() {"
+      js << "\n    #{@data_table.to_js}"
+      js << "\n    var chart = new google.visualization.#{class_name}(document.getElementById('#{element_id}'));"
+      js << "\n    chart.draw(data_table, #{js_parameters(@options)});"
+      js << "\n  }});"
+      js << "\n</script>"
+
+      js
+    end
+
+  end
+
+end

data/lib/google_visualr/data_table.rb

@@ -0,0 +1,277 @@
+module GoogleVisualr
+
+  class DataTable
+
+    attr_accessor :cols
+    attr_accessor :rows
+
+    ##############################
+    # Constructors
+    ##############################
+    #
+    # GoogleVisualr::DataTable.new
+    # Creates an empty data_table instance. Use new_column/s, add_row/s and set_cell methods to populate the data_table.
+    #
+    # GoogleVisualr::DataTable.new(data_object)
+    # Creates a data_table by passing a JavaScript-string-literal like data object into the data parameter. This object can contain formatting options.
+    #
+    ##############################
+    # Syntax Description of a Data Object
+    ##############################
+    #
+    # The data object consists of two required top-level properties, cols and rows.
+    #
+    # * cols property
+    #
+    #   cols is an array of objects describing the ID and type of each column. Each property is an object with the following properties (case-sensitive):
+    #
+    #   * type            [Required] The data type of the data in the column. Supports the following string values:
+    #     - 'string'    : String value. Example values: v:'foo', :v:'bar'
+    #     - 'number'    : Number value. Example values: v:7, v:3.14, v:-55
+    #     - 'boolean'   : Boolean value ('true' or 'false'). Example values: v:true, v:false
+    #     - 'date'      : Date object, with the time truncated. Example value: v:Date.parse('2010-01-01')
+    #     - 'datetime'  : DateTime/Time object, time inclusive. Example value: v:DateTime.parse('2010-01-01 14:20:25')
+    #     - 'timeofday' : Array of 3 numbers or 4 numbers, [Hour,Minute,Second,(Optional) Milliseconds]. Example value: v:[8, 15, 0]
+    #   * label           [Optional] A string value that some visualizations display for this column. Example: label:'Height'
+    #   * id              [Optional] A unique (basic alphanumeric) string ID of the column. Be careful not to choose a JavaScript keyword. Example: id:'col_1'
+    #
+    # * rows property
+    #
+    #   The rows property holds an array of row objects. Each row object has one required property called c, which is an array of cells in that row.
+    #
+    #   Each cell in the table is described by an object with the following properties:
+    #
+    #   * v               [Optional] The cell value. The data type should match the column data type.
+    #   * f               [Optional] A string version of the v value, formatted strictly for display only. If omitted, a string version of v will be used.
+    #
+    #   Cells in the row array should be in the same order as their column descriptions in cols.
+    #
+    #   To indicate a null cell, you can either specify null, or set empty string for a cell in an array, or omit trailing array members.
+    #   So, to indicate a row with null for the first two cells, you could specify [ '', '', {cell_val}] or [null, null, {cell_val}].
+    def initialize(options = {})
+      @cols = Array.new
+      @rows = Array.new
+
+       unless options.empty?
+         cols = options[:cols]
+         new_columns(cols)
+
+         rows = options[:rows]
+         rows.each do |row|
+           add_row(row[:c])
+         end
+      end
+    end
+
+    # Adds a new column to the data_table.
+    #
+    # Parameters:
+    #   * type            [Required] The data type of the data in the column. Supports the following string values:
+    #     - 'string'    : String value. Example values: v:'hello'
+    #     - 'number'    : Number value. Example values: v:7 , v:3.14, v:-55
+    #     - 'date'      : Date object, with the time truncated. Example values: v:Date.parse('2010-01-01')
+    #     - 'datetime'  : Date object including the time. Example values: v:Date.parse('2010-01-01 14:20:25')
+    #     - 'boolean'   : Boolean value ('true' or 'false'). Example values: v: true
+    #   * label           [Optional] A string value that some visualizations display for this column. Example: label:'Height'
+    #   * id              [Optional] A unique (basic alphanumeric) string ID of the column. Be careful not to choose a JavaScript keyword. Example: id:'col_1'
+    def new_column(type, label="", id ="")
+      @cols << { :type => type, :label => label, :id => id }
+    end
+
+    # Adds multiple columns to the data_table.
+    #
+    # Parameters:
+    #   * columns         [Required] An array of column objects {:type, :label, :id}. Calls new_column for each column object.
+    def new_columns(columns)
+      columns.each do |column|
+        new_column(column[:type], column[:label], column[:id])
+      end
+    end
+
+    # Sets a column in data_table, specified by column_index with an array of column_values. column_index starts from 0.
+    #
+    # Parameters
+    #   * column_index    [Required] The column to assign column_values. column_index starts from 0.
+    #   * column_values   [Required] An array of cell values.
+    def set_column(column_index, column_values)
+      if @rows.size < column_values.size
+        1.upto(column_values.size - @rows.size) { @rows << Array.new }
+      end
+
+      column_values.each_with_index do |column_value, row_index|
+        set_cell(row_index, column_index, column_value)
+      end
+    end
+
+    # Gets a column of cell values from the data_table, at column_index. column_index starts from 0.
+    #
+    # Parameters
+    #   * column_index    [Required] The column to retrieve column values. column_index starts from 0.
+    def get_column(column_index)
+      @rows.transpose[column_index].collect(&:v)
+    end
+
+    # Adds a new row to the data_table.
+    # Call method without any parameters to add an empty row, otherwise, call method with a row object.
+    #
+    # Parameters:
+    #   * row             [Optional] An array of cell values specifying the data for the new row.
+    #     - You can specify a value for a cell (e.g. 'hi') or specify a formatted value using cell objects (e.g. {v:55, f:'Fifty-five'}) as described in the constructor section.
+    #     - You can mix simple values and cell objects in the same method call.
+    #     - To create an empty cell, use nil or empty string.
+    def add_row(row_values=[])
+      @rows    << Array.new
+      row_index = @rows.size-1
+
+      row_values.each_with_index do |row_value, column_index|
+        set_cell(row_index, column_index, row_value)
+      end
+    end
+
+    # Adds multiple rows to the data_table. You can call this method with data to populate a set of new rows or create new empty rows.
+    #
+    # Parameters:
+    #   * array_or_num    [Required] Either an array or a number.
+    #     - Array: An array of row objects used to populate a set of new rows. Each row is an object as described in add_row().
+    #     - Number: A number specifying the number of new empty rows to create.
+    def add_rows(array_or_num)
+      if array_or_num.is_a?(Array)
+        array_or_num.each do |row|
+          add_row(row)
+        end
+      else
+        array_or_num.times do
+          add_row
+        end
+      end
+    end
+
+    # Gets a row of cell values from the data_table, at row_index. row_index starts from 0.
+    #
+    # Parameters
+    #   * row_index       [Required] The row to retrieve row values. row_index starts from 0.
+    def get_row(row_index)
+      @rows[row_index].collect(&:v)
+    end
+
+    # Sets the value (and formatted value) of a cell.
+    #
+    # Parameters:
+    #   * row_index       [Required] A number greater than or equal to zero, but smaller than the total number of rows.
+    #   * column_index    [Required] A number greater than or equal to zero, but smaller than the total number of columns.
+    #   * value           [Required] The cell value.
+    #                       The data type should match the column data type.
+    #                       You can specify a value for a cell (e.g. 'hi').
+    #                       Or specify a formatted value using cell objects (e.g. {v:55, f:'Fifty-five'}).
+    def set_cell(row_index, column_index, value)
+      if within_range?(row_index, column_index)
+        verify_against_column_type( @cols[column_index][:type], value )
+        @rows[row_index][column_index] = GoogleVisualr::DataTable::Cell.new(value)
+      else
+        raise RangeError, "row_index and column_index MUST be < @rows.size and @cols.size", caller
+      end
+    end
+
+    # Gets a cell value from the visualization, at row_index, column_index. row_index and column_index start from 0.
+    #
+    # Parameters:
+    #   * row_index       [Required] row_index starts from 0.
+    #   * column_index    [Required] column_index starts from 0.
+    def get_cell(row_index, column_index)
+      if within_range?(row_index, column_index)
+        @rows[row_index][column_index].v
+      else
+        raise RangeError, "row_index and column_index MUST be < @rows.size and @cols.size", caller
+      end
+    end
+
+    # Applies one or more formatters to the data_table to format the columns as specified by the formatter/s.
+    #
+    # Parameters:
+    #   * formatter/s     [Required] One, or an array of formatters.
+    def format(*formatters)
+      @formatters ||= Array.new
+      @formatters  += formatters
+    end
+
+    # Returns the JavaScript equivalent for this data_table instance.
+    def to_js
+      js = "var data_table = new google.visualization.DataTable();"
+
+      @cols.each do |column|
+        js << "data_table.addColumn('#{column[:type]}', '#{column[:label]}', '#{column[:id]}');"
+      end
+
+      @rows.each do |row|
+        js << "data_table.addRow("
+        js << "[ #{row.collect { |cell| cell.to_js }.join(", ")} ]" unless row.empty?
+        js << ");"
+      end
+
+      if @formatters
+        @formatters.each do |formatter|
+          js << formatter.to_js
+        end
+      end
+
+      js
+    end
+
+    private
+
+    def within_range?(row_index, column_index)
+      row_index < @rows.size && column_index < @cols.size
+    end
+
+    def verify_against_column_type(type, value)
+      v = value.is_a?(Hash) ? value[:v] : value
+
+      case
+        when type == "string"
+          raise ArgumentError, "cell value '#{v}' is not a String", caller              unless v.is_a?(String)
+        when type == "number"
+          raise ArgumentError, "cell value '#{v}' is not an Integer or a Float", caller unless v.is_a?(Integer)   || v.is_a?(Float)
+        when type == "date"
+          raise ArgumentError, "cell value '#{v}' is not a Date", caller                unless v.is_a?(Date)
+        when type == 'datetime'
+          raise ArgumentError, "cell value '#{v}' is not a DateTime", caller            unless v.is_a?(DateTime)
+        when type == "boolean"
+          raise ArgumentError, "cell value '#{v}' is not a Boolean", caller             unless v.is_a?(TrueClass) || v.is_a?(FalseClass)
+      end
+    end
+
+
+    class Cell
+      include GoogleVisualr::ParamHelpers
+
+      attr_accessor :v # value
+      attr_accessor :f # formatted
+      attr_accessor :p # properties
+
+      def initialize(*args)
+        options = args.pop
+
+        if options.is_a?(Hash)
+          @v = options[:v]
+          @f = options[:f]
+          @p = options[:p]
+        else
+          @v = options
+        end
+      end
+
+      def to_js
+        js  = "{"
+        js << "v: #{typecast(@v)}"
+        js << ", f: '#{@f}'"  unless @f.nil?
+        js << ", p: #{@p}"    unless @p.nil?
+        js << "}"
+
+        js
+      end
+
+    end
+
+  end
+
+end