google_visualr 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2010 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:
+
+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.

data/README.rdoc

@@ -0,0 +1,92 @@
+= 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.
+
+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.
+
+== 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!
+
+== 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.
+
+= Install
+
+Just install 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
+
+This section describes a basic implementation of the GoogleVisualr::AreaChart class.
+
+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.
+
+  @chart = GoogleVisualr::AreaChart.new
+
+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)
+
+Configure visualization with options.
+
+  @chart.width = 400
+  @chart.height = 240
+
+In your Rails view, render visualization.
+
+  <div id='chart'></div>
+  <%= @chart.render('chart') %>
+
+= Support
+
+Please submit all feedback, bugs and feature-requests to {GitHub Issues Tracker}[http://github.com/winston/google_visualr/issues].
+
+Please also feel free to clone/fork the project, and improve it further!
+
+= Author
+
+GoogleVisualr is maintained by {Winston Teo}[mailto:winstonyw+googlevisualr@gmail.com], and his Ninja Penguin.
+
+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].
+
+= License
+
+Copyright © 2010 Winston Teo Yong Wei. Free software, released under the MIT license.

data/Rakefile

@@ -0,0 +1,33 @@
+# Rake Hook
+
+require 'rubygems'
+#Gem::manage_gems
+require 'rake/gempackagetask'
+
+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
+end

data/VERSION

@@ -0,0 +1 @@
+0.6

data/init.rb

@@ -0,0 +1,17 @@
+require File.dirname(__FILE__) + '/lib/base_chart'
+require File.dirname(__FILE__) + '/lib/annotated_time_line'
+require File.dirname(__FILE__) + '/lib/area_chart'
+require File.dirname(__FILE__) + '/lib/bar_chart'
+require File.dirname(__FILE__) + '/lib/column_chart'
+require File.dirname(__FILE__) + '/lib/gauge'
+require File.dirname(__FILE__) + '/lib/geo_map'
+require File.dirname(__FILE__) + '/lib/image_spark_line'
+require File.dirname(__FILE__) + '/lib/intensity_map'
+require File.dirname(__FILE__) + '/lib/line_chart'
+require File.dirname(__FILE__) + '/lib/map'
+require File.dirname(__FILE__) + '/lib/motion_chart'
+require File.dirname(__FILE__) + '/lib/org_chart'
+require File.dirname(__FILE__) + '/lib/pie_chart'
+require File.dirname(__FILE__) + '/lib/scatter_chart'
+require File.dirname(__FILE__) + '/lib/table'
+require File.dirname(__FILE__) + '/lib/formatters'

data/install.rb

@@ -0,0 +1 @@
+# Install Hook

data/lib/annotated_time_line.rb

@@ -0,0 +1,50 @@
+module GoogleVisualr
+
+  # http://code.google.com/apis/visualization/documentation/gallery/annotatedtimeline.html
+  class AnnotatedTimeLine < BaseChart
+
+    attr_accessor :element_id
+
+    # http://code.google.com/apis/visualization/documentation/gallery/annotatedtimeline.html#Configuration_Options
+    attr_accessor :allowHtml
+    attr_accessor :allowRedraw
+    attr_accessor :allValuesSuffix
+    attr_accessor :annotationsWidth
+    attr_accessor :colors
+    attr_accessor :dateFormat
+    attr_accessor :displayAnnotations
+    attr_accessor :displayAnnotationsFilter
+    attr_accessor :displayDateBarSeparator
+    attr_accessor :displayExactValues
+    attr_accessor :displayLegendDots
+    attr_accessor :displayLegendValues
+    attr_accessor :displayRangeSelector
+    attr_accessor :displayZoomButtons
+    attr_accessor :fill
+    attr_accessor :highlightDot
+    attr_accessor :legendPosition
+    attr_accessor :max
+    attr_accessor :min
+    attr_accessor :numberFormats
+    attr_accessor :scaleColumns
+    attr_accessor :scaleType
+    attr_accessor :thickness
+    attr_accessor :wmode
+    attr_accessor :zoomEndTime
+    attr_accessor :zoomStartTime
+
+    def render (element_id)
+
+      options = Hash.new
+
+      options[:package]     = self.class.to_s.split('::').last
+      options[:element_id]  = element_id
+      options[:chart_style] = collect_parameters
+
+      super(options)
+
+    end
+
+  end
+
+end

data/lib/area_chart.rb

@@ -0,0 +1,54 @@
+module GoogleVisualr
+
+  # http://code.google.com/apis/visualization/documentation/gallery/areachart.html
+  class AreaChart < BaseChart
+
+    attr_accessor :element_id
+
+    # http://code.google.com/apis/visualization/documentation/gallery/areachart.html#Configuration_Options
+    attr_accessor :axisColor
+    attr_accessor :axisBackgroundColor
+    attr_accessor :axisFontSize
+    attr_accessor :backgroundColor
+    attr_accessor :borderColor
+    attr_accessor :colors
+    attr_accessor :enableTooltip
+    attr_accessor :focusBorderColor
+    attr_accessor :height
+    attr_accessor :isStacked
+    attr_accessor :legend
+    attr_accessor :legendBackgroundColor
+    attr_accessor :legendFontSize
+    attr_accessor :legendTextColor
+    attr_accessor :lineSize
+    attr_accessor :logScale
+    attr_accessor :max
+    attr_accessor :min
+    attr_accessor :pointSize
+    attr_accessor :reverseAxis
+    attr_accessor :showCategories
+    attr_accessor :title
+    attr_accessor :titleX
+    attr_accessor :titleY
+    attr_accessor :titleColor
+    attr_accessor :titleFontSize
+    attr_accessor :tooltipFontSize
+    attr_accessor :tooltipHeight
+    attr_accessor :tooltipWidth
+    attr_accessor :width
+
+    def render (element_id)
+
+      options = Hash.new
+
+      options[:package]     = self.class.to_s.split('::').last
+      options[:element_id]  = element_id
+      options[:chart_style] = collect_parameters
+
+      super(options)
+
+    end
+
+  end
+
+end

data/lib/bar_chart.rb

@@ -0,0 +1,53 @@
+module GoogleVisualr
+
+  # http://code.google.com/apis/visualization/documentation/gallery/barchart.html
+  class BarChart < BaseChart
+
+    attr_accessor :element_id
+
+    # http://code.google.com/apis/visualization/documentation/gallery/barchart.html#Configuration_Options
+    attr_accessor :axisColor
+    attr_accessor :axisBackgroundColor
+    attr_accessor :axisFontSize
+    attr_accessor :backgroundColor
+    attr_accessor :borderColor
+    attr_accessor :colors
+    attr_accessor :enableTooltip
+    attr_accessor :focusBorderColor
+    attr_accessor :height
+    attr_accessor :is3D
+    attr_accessor :isStacked
+    attr_accessor :legend
+    attr_accessor :legendBackgroundColor
+    attr_accessor :legendFontSize
+    attr_accessor :legendTextColor
+    attr_accessor :logScale
+    attr_accessor :max
+    attr_accessor :min
+    attr_accessor :reverseAxis
+    attr_accessor :showCategories
+    attr_accessor :title
+    attr_accessor :titleX
+    attr_accessor :titleY
+    attr_accessor :titleColor
+    attr_accessor :titleFontSize
+    attr_accessor :tooltipFontSize
+    attr_accessor :tooltipHeight
+    attr_accessor :tooltipWidth
+    attr_accessor :width
+
+    def render (element_id)
+
+      options = Hash.new
+
+      options[:package]     = self.class.to_s.split('::').last
+      options[:element_id]  = element_id
+      options[:chart_style] = collect_parameters
+
+      super(options)
+
+    end
+
+  end
+
+end

data/lib/base_chart.rb

@@ -0,0 +1,285 @@
+module GoogleVisualr
+
+  class BaseChart
+
+    attr_accessor :chart_data
+    attr_accessor :formatters
+
+    ##############################
+    # Constructors
+    ##############################
+    #
+    # GoogleVisualr::visualization.new:
+    # Creates an empty visualization instance. Use add_columns, add_rows and set_value or set_cell methods to populate the visualization.
+    #
+    # GoogleVisualr::visualization.new(data object):
+    # reates a visualization by passing a JavaScript-string-literal like data object into the data parameter. This object can contain formatting options.
+    #
+    ##############################
+    # Syntax Description of 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={})
+
+      @chart_data  = "var chart_data = new google.visualization.DataTable();"
+
+      if !options.empty?
+
+        cols = options[:cols]
+        add_columns(cols)
+
+        rows = options[:rows]
+        rows.each do |row|
+          add_row(row[:c])
+        end
+
+      end
+
+    end
+
+    # Adds a new column to the visualization.
+    #
+    # 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 add_column (type, label="", id="")
+      @chart_data << "chart_data.addColumn('#{type}', '#{label}', '#{id}');"
+    end
+
+    # Adds multiple columns to the visualization.
+    #
+    # Parameters:
+    #   * columns         [Required] An array of column objects {:type, :label, :id}. Calls add_column for each column object.
+    def add_columns(columns)
+
+      columns.each do |column|
+        add_column(column[:type], column[:label], column[:id])
+      end
+
+    end
+
+    # Adds a new row to the visualization.
+    # 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)
+
+      if row.empty?
+        @chart_data << "chart_data.addRow();"  # Empty Row
+      else
+
+        attributes = Array.new
+        row.each do |cell|
+          attributes << add_row_cell(cell)
+        end
+
+        @chart_data << "chart_data.addRow( [" +  attributes.join(",")  + "] );"
+
+      end
+
+    end
+
+    # Adds multiple rows to the visualization. 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
+        @chart_data << "chart_data.addRows(#{array_or_num});"
+      end
+
+    end
+
+    # Sets the value and/or 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.
+    #   * formatted_value [Optional] A string version of value, formatted strictly for display only. If omitted, a string version of value will be used.
+    def set_cell  (row_index, column_index, value, formatted_value=nil, properties=nil)
+
+      @chart_data << "chart_data.setCell("
+      @chart_data << "#{row_index}, #{column_index}, #{typecast(value)}"
+      @chart_data << ", '#{formatted_value}'" unless formatted_value.blank?
+      @chart_data << ", '#{properties}'"      unless properties.blank?
+      @chart_data << ");"
+
+    end
+
+    # Sets the value of a cell. Overwrites any existing cell value, and clear out any formatted value for the 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.
+    def set_value (row_index, column_index, value)
+
+      @chart_data << "chart_data.setCell(#{row_index}, #{column_index}, #{typecast(value)});"
+
+    end
+
+    # Applies one or more formatters to the visualization 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
+
+    # Sets chart configuration options with a hash.
+    #
+    # Parameters:
+    #  *options            [Required] A hash of configuration options.
+    def set_options(options)
+
+      options.each_pair do | key, value |
+        send "#{key}=", value
+      end
+
+    end
+
+    # Generates JavaScript and renders the visualization in the final HTML output.
+    #
+    # Parameters:
+    #  *div_id            [Required] The ID of the DIV element that the visualization should be rendered in.
+    #
+    # Note: This is the super method.
+    def render(options)
+
+      script  = "\n<script type='text/javascript'>"
+      script << "\n  google.load('visualization','1', {packages: ['#{options[:package].downcase}'], callback: function() {"
+      script << "\n    #{@chart_data}"
+      if @formatters
+        @formatters.each do |formatter|
+          script << formatter.script
+        end
+      end
+      script << "\n    var chart = new google.visualization.#{options[:package]}(document.getElementById('#{options[:element_id]}'));"
+      script << "\n    chart.draw(chart_data, #{options[:chart_style]});"
+      script << "\n  }});"
+      script << "\n</script>"
+
+      return script
+
+    end
+
+    private
+
+    def add_row_cell(cell)
+
+      if cell.is_a?(Hash)
+
+        attributes = Array.new
+        cell.each_pair do |key, value|
+          attributes << "#{key}: #{typecast(value)}"
+        end
+
+        return "{" + attributes.join(",") + "}"
+
+      else
+        return "#{typecast(cell)}"
+      end
+
+    end
+
+    # If the column type is 'string'    , the value should be a string.
+    # If the column type is 'number'    , the value should be a number.
+    # If the column type is 'boolean'   , the value should be a boolean.
+    # If the column type is 'date'      , the value should be a Date object.
+    # If the column type is 'datetime'  , the value should be a DateTime or Time object.
+    # If the column type is 'timeofday' , the value should be an array of three or four numbers: [hour, minute, second, optional milliseconds].
+    def typecast(value)
+
+      case
+        when value.is_a?(String)
+          return "'#{escape_single_quotes(value)}'"
+        when value.is_a?(Integer)   || value.is_a?(Float)
+          return value
+        when value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          return "#{value}"
+        when value.is_a?(Date)
+          return "new Date(#{value.year}, #{value.month-1}, #{value.day})"
+        when value.is_a?(DateTime)  ||  value.is_a?(Time)
+          return "new Date(#{value.year}, #{value.month-1}, #{value.day}, #{value.hour}, #{value.min}, #{value.sec})"
+        when value.is_a?(Array)
+          return "[" + value.collect { |item| typecast(item) }.join(",") + "]"
+        else
+          return value
+      end
+
+    end
+
+    def collect_parameters
+
+      attributes = Array.new
+      instance_variable_names.each do |instance_variable|
+        next if instance_variable == "@chart_data" || instance_variable == "@formatters"
+        key         = instance_variable.gsub("@", "")
+        value       = instance_variable_get(instance_variable)
+        attribute   = "#{key}:#{typecast(value)}"
+        attributes << attribute
+      end
+
+      return "{" + attributes.join(",") + "}"
+
+    end
+
+    def escape_single_quotes(str)
+
+      str.gsub(/[']/, '\\\\\'')
+
+    end
+
+  end
+
+end