googlecharts 1.3.6 → 1.4.0

data/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+log/*
+.manifest
+pkg

data/README.markdown

@@ -0,0 +1,290 @@
+The goal of this Gem is to make the creation of Google Charts a simple and easy task.
+
+    Gchart.line(  :size => '200x300', 
+                  :title => "example title",
+                  :bg => 'efefef',
+                  :legend => ['first data set label', 'second data set label'],
+                  :data => [10, 30, 120, 45, 72])
+              
+
+Check out the [full documentation over there](http://googlecharts.rubyforge.org/)
+
+This gem is fully tested using Rspec, check the rspec folder for more examples.
+
+See at the bottom of this file who reported using this gem.
+
+Chart Type
+-------------
+
+This gem supports the following types of charts:
+  
+  * line, 
+  * line_xy
+  * sparkline
+  * scatter
+  * bar
+  * venn
+  * pie
+  * pie_3d
+  * google meter
+  
+Googlecharts also supports graphical themes and you can easily load your own.
+
+To create a chart, simply require Gchart and call any of the existing type:
+
+    require 'gchart'
+    Gchart.pie
+  
+  
+Chart Title
+-------------
+
+  To add a title to a chart pass the title to your chart:
+  
+    Gchart.line(:title => 'Sexy Charts!')
+    
+You can also specify the color and/or size
+    
+    Gchart.line(:title => 'Sexy Charts!', :title_color => 'FF0000', :title_size => '20')
+
+Colors
+-------------
+
+Specify a color with at least a 6-letter string of hexadecimal values in the format RRGGBB. For example:
+
+    * FF0000 = red
+    * 00FF00 = green
+    * 0000FF = blue
+    * 000000 = black
+    * FFFFFF = white
+
+You can optionally specify transparency by appending a value between 00 and FF where 00 is completely transparent and FF completely opaque. For example:
+
+    * 0000FFFF = solid blue
+    * 0000FF00 = transparent blue
+
+If you need to use multiple colors, check the doc. Usually you just need to pass :attribute => 'FF0000,00FF00'
+
+Some charts have more options than other, make sure to refer to the documentation.
+
+Background options:
+-------------
+
+If you don't set the background option, your graph will be transparent.
+
+* You have 3 types of background  http://code.google.com/apis/chart/#chart_or_background_fill
+
+- solid
+- gradient
+- stripes
+
+By default, if you set a background color, the fill will be solid:
+
+    Gchart.bar(:bg => 'efefef')
+
+However you can specify another fill type such as:
+            
+    Gchart.line(:bg => {:color => 'efefef', :type => 'gradient'})
+  
+In the above code, we decided to have a gradient background, however since we only passed one color, the chart will start by the specified color and transition to white. By the default, the gradient angle is 0. Change it as follows:
+
+    Gchart.line(:title =>'bg example', :bg => {:color => 'efefef', :type => 'gradient', :angle => 90})
+    
+For a more advance use of colors, refer to http://code.google.com/apis/chart/#linear_gradient
+
+    Gchart.line(:bg => {:color => '76A4FB,1,ffffff,0', :type => 'gradient'})
+    
+    
+The same way you set the background color, you can also set the graph background:
+
+    Gchart.line(:graph_bg => 'cccccc')
+    
+or both
+
+    Gchart.line(:bg => {:color => '76A4FB,1,ffffff,0', :type => 'gradient'}, :graph_bg => 'cccccc', :title => 'Sexy Chart')
+    
+    
+Another type of fill is stripes http://code.google.com/apis/chart/#linear_stripes
+
+    Gchart.line(:bg => {:color => 'efefef', :type => 'stripes'})
+    
+You can customize the amount of stripes, colors and width by changing the color value.
+
+
+Themes
+--------
+
+  Googlecharts comes with 4 themes: keynote, thirty7signals, pastel and greyscale. (ganked from [Gruff](http://github.com/topfunky/gruff/tree/master)
+
+
+    Gchart.line(
+                :theme => :keynote, 
+                :data => [[0,40,10,70,20],[41,10,80,50,40],[20,60,30,60,80],[5,23,35,10,56],[80,90,5,30,60]], 
+                :title => 'keynote'
+                )
+
+  * keynote
+
+    ![keynote](http://chart.apis.google.com/chart?chtt=keynote&chco=6886B4,FDD84E,72AE6E,D1695E,8A6EAF,EFAA43&chs=300x200&cht=lc&chd=s:AbGvN,bG2hb,NoUo2,DPXGl,29DUo&chf=c,s,FFFFFF|bg,s,000000)
+
+  * thirty7signals
+
+    ![37signals](http://chart.apis.google.com/chart?chtt=thirty7signals&chco=FFF804,336699,339933,ff0000,cc99cc,cf5910&chs=300x200&cht=lc&chd=s:AbGvN,bG2hb,NoUo2,DPXGl,29DUo&chf=bg,s,FFFFFF)
+
+  * pastel
+
+    ![pastel](http://chart.apis.google.com/chart?chtt=pastel&chco=a9dada,aedaa9,daaea9,dadaa9,a9a9da&chs=300x200&cht=lc&chd=s:AbGvN,bG2hb,NoUo2,DPXGl,29DUo)
+
+  * greyscale
+
+    ![greyscale](http://chart.apis.google.com/chart?chtt=greyscale&chco=282828,383838,686868,989898,c8c8c8,e8e8e8&chs=300x200&cht=lc&chd=s:AbGvN,bG2hb,NoUo2,DPXGl,29DUo)
+
+
+You can also use your own theme. Create a yml file using the same format as the themes located in lib/themes.yml
+
+Load your theme(s):
+
+      Chart::Theme.add_theme_file("#{File.dirname(__FILE__)}/fixtures/another_test_theme.yml")
+
+And use the standard method signature to use your own theme:
+
+      Gchart.line(:theme => :custom_theme, :data => [[0, 40, 10, 70, 20],[41, 10, 80, 50]], :title => 'greyscale')
+
+    
+    
+Legend & Labels
+-------------
+
+You probably will want to use a legend or labels for your graph.
+
+    Gchart.line(:legend => 'legend label')
+or
+    Gchart.line(:legend => ['legend label 1', 'legend label 2'])
+    
+Will do the trick. You can also use the labels alias (makes more sense when using the pie charts)
+
+    chart = Gchart.pie(:labels => ['label 1', 'label 2'])
+
+Multiple axis labels 
+-------------
+
+Multiple axis labels are available for line charts, bar charts and scatter plots.
+
+* x = bottom x-axis
+* t = top x-axis
+* y = left y-axis
+* r = right y-axis
+
+    Gchart.line(:label_axis => 'x,y,r')
+  
+To add labels on these axis:
+
+    Gchart.line(:axis_labels => ['Jan|July|Jan|July|Jan', '0|100', 'A|B|C', '2005|2006|2007'])
+
+    
+Data options
+-------------
+
+Data are passed using an array or a nested array.    
+
+    Gchart.bar(:data => [1,2,4,67,100,41,234])  
+  
+    Gchart.bar(:data => [[1,2,4,67,100,41,234],[45,23,67,12,67,300, 250]])
+  
+By default, the graph is drawn with your max value representing 100% of the height or width of the graph. You can change that my passing the max value.
+
+    Gchart.bar(:data => [1,2,4,67,100,41,234], :max_value => 300)
+    Gchart.bar(:data => [1,2,4,67,100,41,234], :max_value => 'auto')
+  
+or if you want to use the real values from your dataset:
+
+    Gchart.bar(:data => [1,2,4,67,100,41,234], :max_value => false)
+  
+  
+You can also define a different encoding to add more granularity:
+
+    Gchart.bar(:data => [1,2,4,67,100,41,234], :encoding => 'simple') 
+    Gchart.bar(:data => [1,2,4,67,100,41,234], :encoding => 'extended') 
+    Gchart.bar(:data => [1,2,4,67,100,41,234], :encoding => 'text') 
+  
+
+Pies:
+-------------
+  
+you have 2 type of pies:
+  - Gchart.pie() the standard 2D pie
+  _ Gchart.pie_3d() the fancy 3D pie
+  
+To set labels, you can use one of these two options:
+
+    @legend = ['Matt_fu', 'Rob_fu']
+    Gchart.pie_3d(:title => @title, :labels => @legend, :data => @data, :size => '400x200')
+    Gchart.pie_3d(:title => @title, :legend => @legend, :data => @data, :size => '400x200')
+  
+Bars:
+-------------
+
+A bar chart can accept options to set the width of the bars, spacing between bars and spacing between bar groups. To set these, you can either provide a string, array or hash.
+
+The Google API sets these options in the order of width, spacing, and group spacing, with both spacing values being optional. So, if you provide a string or array, provide them in that order:
+
+    Gchart.bar(:data => @data, :bar_width_and_spacing => '25,6') # width of 25, spacing of 6
+    Gchart.bar(:data => @data, :bar_width_and_spacing => '25,6,12') # width of 25, spacing of 6, group spacing of 12
+    Gchart.bar(:data => @data, :bar_width_and_spacing => [25,6]) # width of 25, spacing of 6
+    Gchart.bar(:data => @data, :bar_width_and_spacing => 25) # width of 25
+  
+The hash lets you set these values directly, with the Google default values set for any options you don't include:
+
+    Gchart.bar(:data => @data, :bar_width_and_spacing => {:width => 19})
+    Gchart.bar(:data => @data, :bar_width_and_spacing => {:spacing => 10, :group_spacing => 12})
+
+Sparklines:
+-------------
+
+A sparkline chart has exactly the same parameters as a line chart. The only difference is that the axes lines are not drawn for sparklines by default.
+  
+
+Google-o-meter
+-------------
+
+A Google-o-meter has a few restrictions. It may only use a solid filled background and it may only have one label.
+
+try yourself
+-------------
+
+    Gchart.bar( :data => [[1,2,4,67,100,41,234],[45,23,67,12,67,300, 250]], 
+                :title => 'SD Ruby Fu level', 
+                :legend => ['matt','patrick'], 
+                :bg => {:color => '76A4FB', :type => 'gradient'}, 
+                :bar_colors => 'ff0000,00ff00')
+
+ "http://chart.apis.google.com/chart?chs=300x200&chdl=matt|patrick&chd=s:AAANUIv,JENCN9y&chtt=SDRuby+Fu+level&chf=bg,lg,0,76A4FB,0,ffffff,1&cht=bvs&chco=ff0000,00ff00"  
+ 
+    Gchart.pie(:data => [20,10,15,5,50], :title => 'SDRuby Fu level', :size => '400x200', :labels => ['matt', 'rob', 'patrick', 'ryan', 'jordan'])
+http://chart.apis.google.com/chart?cht=p&chs=400x200&chd=s:YMSG9&chtt=SDRuby+Fu+level&chl=matt|rob|patrick|ryan|jordan
+
+
+People reported using this gem:
+---------------------
+
+![github](http://img.skitch.com/20080627-r14subqdx2ye3w13qefbx974gc.png)
+
+* [http://github.com](http://github.com) 
+
+![stafftool.com](http://stafftool.com/images/masthead_screen.gif)
+
+* [http://stafftool.com/](http://stafftool.com/) Takeo (contributor)
+
+![graffletopia.com](http://img.skitch.com/20080627-g2pp89h7gdbh15m1rr8hx48jep.jpg) 
+
+* [graffleropia.com](http://graffletopia.com) Mokolabs (contributor)
+
+![gumgum](http://img.skitch.com/20080627-kc1weqsbkmxeqhwiyriq3n6g8k.jpg)
+
+* [http://gumgum.com](http://gumgum.com) Mattetti (Author)
+
+![http://img.skitch.com/20080627-n48j8pb2r7irsewfeh4yp3da12.jpg]
+
+* [http://feedflix.com/](http://feedflix.com/) [lifehacker article](http://lifehacker.com/395610/feedflix-creates-detailed-charts-from-your-netflix-use)
+
+* [California State University, Chico](http://www.csuchico.edu/)

data/Rakefile

@@ -1,32 +1,20 @@
-require 'config/requirements'
-require 'config/hoe' # setup Hoe + all gem configuration
+require 'rubygems'  
+require 'rake'
 
-Dir['tasks/**/*.rake'].each { |rake| load rake }
-
-desc %{Update ".manifest" with the latest list of project filenames. Respect\
-.gitignore by excluding everything that git ignores. Update `files` and\
-`test_files` arrays in "*.gemspec" file if it's present.}
-task :manifest do
-  list = Dir['**/*'].sort
-  spec_file = Dir['*.gemspec'].first
-  list -= [spec_file] if spec_file
+begin  
+  require 'jeweler'  
+  Jeweler::Tasks.new do |gemspec|  
+    gemspec.name = "googlecharts"  
+    gemspec.summary = "Generate charts using Google API & Ruby"  
+    gemspec.description = "Generate charts using Google API & Ruby"  
+    gemspec.email = "mattaimonetti@gmail.com"  
+    gemspec.homepage = "http://googlecharts.rubyforge.org/"  
+    gemspec.authors = ["Matt Aimonetti"]  
+  end 
+  Jeweler::GemcutterTasks.new 
+rescue LoadError  
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"  
+end  
   
-  File.read('.gitignore').each_line do |glob|
-    glob = glob.chomp.sub(/^\//, '')
-    list -= Dir[glob]
-    list -= Dir["#{glob}/**/*"] if File.directory?(glob) and !File.symlink?(glob)
-    puts "excluding #{glob}"
-  end
- 
-  if spec_file
-    spec = File.read spec_file
-    spec.gsub! /^(\s* s.(test_)?files \s* = \s* )( \[ [^\]]* \] | %w\( [^)]* \) )/mx do
-      assignment = $1
-      bunch = $2 ? list.grep(/^test\//) : list
-      '%s%%w(%s)' % [assignment, bunch.join(' ')]
-    end
-      
-    File.open(spec_file, 'w') {|f| f << spec }
-  end
-  File.open('.manifest', 'w') {|f| f << list.join("\n") }
-end
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }
+

data/VERSION

@@ -0,0 +1 @@
+1.4.0

data/lib/gchart.rb

@@ -3,20 +3,23 @@ require 'gchart/version'
 require 'gchart/theme'
 require "open-uri"
 require "uri"
+require "cgi"
+require 'enumerator'
 
 class Gchart
 
   include GchartInfo
   
   @@url = "http://chart.apis.google.com/chart?"  
-  @@types = ['line', 'line_xy', 'scatter', 'bar', 'venn', 'pie', 'pie_3d', 'jstize', 'sparkline', 'meter']
+  @@types = ['line', 'line_xy', 'scatter', 'bar', 'venn', 'pie', 'pie_3d', 'jstize', 'sparkline', 'meter', 'map']
   @@simple_chars = ('A'..'Z').to_a + ('a'..'z').to_a + ('0'..'9').to_a
   @@chars = @@simple_chars + ['-', '.']
   @@ext_pairs = @@chars.map { |char_1| @@chars.map { |char_2| char_1 + char_2 } }.flatten
   @@file_name = 'chart.png'
   
-  attr_accessor :title, :type, :width, :height, :horizontal, :grouped, :legend, :data, :encoding, :max_value, :bar_colors,
-                :title_color, :title_size, :custom, :axis_with_labels, :axis_labels, :bar_width_and_spacing, :id, :alt, :class
+  attr_accessor :title, :type, :width, :height, :horizontal, :grouped, :legend, :data, :encoding, :min_value, :max_value, :bar_colors,
+                :title_color, :title_size, :custom, :axis_with_labels, :axis_labels, :bar_width_and_spacing, :id, :alt, :class,
+                :range_markers, :geographical_area, :map_colors, :country_codes, :axis_range
     
   # Support for Gchart.line(:title => 'my title', :size => '400x600')
   def self.method_missing(m, options={})
@@ -28,6 +31,8 @@ class Gchart
     @@file_name = options[:filename] unless options[:filename].nil?
     options.delete(:format)
     options.delete(:filename)
+    #update map_colors to be bar_colors
+    options.update(:bar_colors => options[:map_colors]) if options.has_key?(:map_colors)
     # create the chart and return it in the format asked for
     if @@types.include?(m.to_s)  
       chart = new(options.merge!({:type => m}))
@@ -109,6 +114,26 @@ class Gchart
     end
   end
   
+  # returns the full data range as an array
+  # it also sets the data range if not defined
+  def full_data_range(ds)
+    return [@min, @max] unless (@min.nil? || @max.nil?)
+    @max = (max_value.nil? || max_value == 'auto') ? ds.compact.map{|mds| mds.compact.max}.max : max_value
+    if (min_value.nil? || min_value == 'auto') 
+      min_ds_value = ds.compact.map{|mds| mds.compact.min}.min || 0
+      @min = (min_ds_value < 0) ? min_ds_value : 0
+    else
+      @min = min_value  
+    end 
+    @axis_range = [[@min,@max]]
+  end
+  
+  def dataset
+    @dataset ||= prepare_dataset(data)
+    full_data_range(@dataset) unless @axis_range
+    @dataset
+  end
+  
   def self.jstize(string)
     string.gsub(' ', '+').gsub(/\[|\{|\}|\||\\|\^|\[|\]|\`|\]/) {|c| "%#{c[0].to_s(16).upcase}"}
   end    
@@ -155,7 +180,7 @@ class Gchart
   #
   def jstize(string)
     Gchart.jstize(string)
-  end
+  end 
   
   private
   
@@ -174,7 +199,7 @@ class Gchart
   end
   
   def set_data
-    data = send("#{@encoding}_encoding", @data)
+    data = send("#{@encoding}_encoding")
     "chd=#{data}"
   end
   
@@ -191,6 +216,11 @@ class Gchart
     "chco=#{@bar_colors}"
   end
   
+  def set_country_codes
+    @country_codes = @country_codes.join() if @country_codes.is_a?(Array)
+    "chld=#{@country_codes}"
+  end
+  
   # set bar spacing
   # chbh=
   # <bar width in pixels>,
@@ -213,6 +243,21 @@ class Gchart
     "chbh=#{width_and_spacing_values}"
   end
   
+  def set_range_markers
+    markers = case @range_markers
+    when Hash
+      set_range_marker(@range_markers)
+    when Array
+      range_markers.collect{|marker| set_range_marker(marker)}.join('|')
+    end
+    "chm=#{markers}"
+  end
+  
+  def set_range_marker(options)
+    orientation = ['vertical', 'Vertical', 'V', 'v', 'R'].include?(options[:orientation]) ? 'R' : 'r'
+    "#{orientation},#{options[:color]},0,#{options[:start_position]},#{options[:stop_position]}#{',1' if options[:overlaid?]}"  
+  end
+  
   def fill_for(type=nil, color='', angle=nil)
     unless type.nil? 
       case type
@@ -238,7 +283,7 @@ class Gchart
     return set_labels if @type == :pie || @type == :pie_3d || @type == :meter
     
     if @legend.is_a?(Array)
-      "chdl=#{@legend.map{|label| "#{label}"}.join('|')}"
+      "chdl=#{@legend.map{|label| "#{CGI::escape(label)}"}.join('|')}"
     else
       "chdl=#{@legend}"
     end
@@ -270,6 +315,24 @@ class Gchart
     "chxl=#{labels_arr.join('|')}"
   end
   
+  # http://code.google.com/apis/chart/labels.html#axis_range
+  # Specify a range for axis labels
+  def set_axis_range
+    # a passed axis_range should look like:
+    # [[10,100]] or [[10,100,4]] or [[10,100], [20,300]]
+    # in the second example, 4 is the interval 
+    dataset # just making sure we processed the data before
+    if axis_range && axis_range.respond_to?(:each) && axis_range.first.respond_to?(:each)
+     'chxr=' + axis_range.enum_for(:each_with_index).map{|range, index| [index, range[0], range[1], range[2]].compact.join(',')}.join("|")
+    else
+      nil
+    end
+  end
+  
+  def set_geographical_area
+    "chtm=#{@geographical_area}"
+  end
+  
   def set_type
     case @type
       when :line
@@ -290,6 +353,8 @@ class Gchart
         "cht=ls"
       when :meter
         "cht=gom"
+      when :map
+        "cht=t"
       end
   end
   
@@ -323,8 +388,7 @@ class Gchart
   # Simple encoding has a resolution of 62 different values. 
   # Allowing five pixels per data point, this is sufficient for line and bar charts up
   # to about 300 pixels. Simple encoding is suitable for all other types of chart regardless of size.
-  def simple_encoding(dataset=[])
-    dataset = prepare_dataset(dataset)
+  def simple_encoding
     @max_value = dataset.compact.map{|ds| ds.compact.max}.max if @max_value == 'auto'
     
     if @max_value == false || @max_value == 'false' || @max_value == :false || @max_value == 0
@@ -336,14 +400,19 @@ class Gchart
   end
   
   # http://code.google.com/apis/chart/#text
-  # Text encoding has a resolution of 1,000 different values, 
-  # using floating point numbers between 0.0 and 100.0. Allowing five pixels per data point, 
-  # integers (1.0, 2.0, and so on) are sufficient for line and bar charts up to about 500 pixels. 
-  # Include a single decimal place (35.7 for example) if you require higher resolution. 
-  # Text encoding is suitable for all other types of chart regardless of size.
-  def text_encoding(dataset=[])
-    dataset = prepare_dataset(dataset)
-    "t:" + dataset.map{ |ds| ds.join(',') }.join('|')
+  # Text encoding with data scaling lets you specify arbitrary positive or
+  # negative floating point numbers, in combination with a scaling parameter
+  # that lets you specify a custom range for your chart. This chart is useful
+  # when you don't want to worry about limiting your data to a specific range,
+  # or do the calculations to scale your data down or up to fit nicely inside
+  # a chart.
+  #
+  # Valid values range from (+/-)9.999e(+/-)100, and only four non-zero digits are supported (that is, 123400, 1234, 12.34, and 0.1234 are valid, but 12345, 123.45 and 123400.5 are not).
+  #
+  # This encoding is not available for maps.
+  #
+  def text_encoding
+    "t:" + dataset.map{ |ds| ds.join(',') }.join('|') + "&chds=#{@min},#{@max}"
   end
   
   def convert_to_extended_value(number)
@@ -354,16 +423,15 @@ class Gchart
       value.nil? ? "__" : value
     end
   end
+
   
   # http://code.google.com/apis/chart/#extended
   # Extended encoding has a resolution of 4,096 different values 
   # and is best used for large charts where a large data range is required.
-  def extended_encoding(dataset=[])
-    
-    dataset = prepare_dataset(dataset)
+  def extended_encoding
     @max_value = dataset.compact.map{|ds| ds.compact.max}.max if @max_value == 'auto'
     
-    if @max_value == false || @max_value == 'false' || @max_value == :false
+    if @max_value == false || @max_value == 'false' || @max_value == :false || @max_value == 0
       "e:" +  dataset.map { |ds| ds.map { |number| number.nil? ? '__' : convert_to_extended_value(number)}.join }.join(',')
     else
       "e:" + dataset.map { |ds| ds.map { |number| number.nil? ? '__' : convert_to_extended_value( (@@ext_pairs.size - 1) * number / @max_value) }.join }.join(',')
@@ -373,8 +441,11 @@ class Gchart
   
   
   def query_builder(options="")
-    query_params = instance_variables.map do |var|
+    dataset 
+    query_params = instance_variables.sort.map do |var|
       case var
+      when '@data'
+        set_data unless @data == []  
       # Set the graph size  
       when '@width'
         set_size unless @width.nil? || @height.nil?
@@ -388,16 +459,22 @@ class Gchart
         set_colors
       when '@chart_color'
         set_colors if @bg_color.nil?
-      when '@data'
-        set_data unless @data == []
       when '@bar_colors'
         set_bar_colors
       when '@bar_width_and_spacing'
         set_bar_width_and_spacing
       when '@axis_with_labels'
         set_axis_with_labels
+      when '@axis_range'
+        set_axis_range if dataset
       when '@axis_labels'
         set_axis_labels
+      when '@range_markers'
+        set_range_markers
+      when '@geographical_area'
+        set_geographical_area
+      when '@country_codes'
+        set_country_codes
       when '@custom'
         @custom
       end