cyberfox-gchart 0.5.2 → 0.5.4

data/lib/gchart.rb

@@ -1,9 +1,15 @@
 require File.expand_path(File.dirname(__FILE__) + "/version")
+require File.expand_path(File.dirname(__FILE__) + "/gchart/colors")
+require File.expand_path(File.dirname(__FILE__) + "/gchart/axis")
 
 %w(base bar line map meter pie pie_3d scatter sparkline venn xy_line).each do |type|
   require File.expand_path(File.dirname(__FILE__) + "/gchart/#{type}")
 end
 
+%w(horizontal vertical top right bottom left).each do |type|
+  require File.expand_path(File.dirname(__FILE__) + "/gchart/axis/#{type}_axis")
+end
+
 module GChart
   URL   = "http://chart.apis.google.com/chart"
   SIMPLE_CHARS = ('A'..'Z').to_a + ('a'..'z').to_a + ('0'..'9').to_a
@@ -32,25 +38,47 @@ module GChart
     # Convenience constructor for GChart::Pie3D.
     def pie3d(*args, &block); Pie3D.new(*args, &block) end    
     
-    # Convenience constructor for GChart::Line.
+    # Convenience constructor for GChart::Scatter.
+    def scatter(*args, &block); Scatter.new(*args, &block) end
+    
+    # Convenience constructor for GChart::Sparkline.
     def sparkline(*args, &block); Sparkline.new(*args, &block) end
 
     # Convenience constructor for GChart::Venn.
     def venn(*args, &block); Venn.new(*args, &block) end    
-    
-    # Convenience constructor for GChart::Scatter.
-    def scatter(*args, &block); Scatter.new(*args, &block) end
-    
+
+    def encoding=(new_encoding)
+      @encoding = new_encoding if [:text, :simple, :extended].include? new_encoding
+    end
+
+    def encode_datasets(sets, force_max=nil)
+      max = force_max || sets.collect { |s| s.max }.max
+
+      join_character = @encoding == :text ? ',' : ''
+
+      output = sets.collect do |set|
+        set.collect { |n| GChart.encode(@encoding || :extended, n, max) }.join(join_character)
+      end
+
+      if @encoding == :text
+        "t:#{output.join('|')}"
+      else
+        "e:#{output.join(',')}"
+      end
+    end
+
     # Encode +n+ as a string. +n+ is normalized based on +max+.
     # +encoding+ can currently only be :extended.
     def encode(encoding, n, max)
+      encoding = @encoding if @encoding
+
       case encoding
       when :simple
         return "_" if n.nil?
         SIMPLE_CHARS[((n/max.to_f) * (SIMPLE_CHARS.size - 1)).round]
       when :text
         return "-1" if n.nil?
-        n.to_s
+        n.to_f.to_s
       when :extended
         return "__" if n.nil?
         EXTENDED_PAIRS[max.zero? ? 0 : ((n/max.to_f) * (EXTENDED_PAIRS.size - 1)).round]

data/lib/gchart/axis.rb

@@ -0,0 +1,139 @@
+module GChart
+  class Axis
+
+    # Array of axis labels. Can be exactly placed along the axis with
+    # +label_positions+, otherwise are evenly spaced.
+    attr_accessor :labels
+
+    # Array of float positions for +labels+. Without +labels+, the
+    # +label_positions+ are self-labeling.
+    attr_accessor :label_positions
+
+    # Takes a +Range+ of float values. With +labels+, defines +labels+
+    # context, meaning the +labels+ will be spaced at their proper
+    # location within the +range+. Without +labels+, smart-labeling
+    # occurs for +range+.
+    attr_accessor :range
+
+    # An rrggbb color for axis text.
+    attr_accessor :text_color
+
+    # Size of font in pixels. To set +font_size+, +text_color+ is also
+    # required.
+    attr_accessor :font_size
+
+    # +TEXT_ALIGNMENT+ property for axis labeling. To set
+    # +text_alignment+, both +text_color+ and +font_size+ must also be
+    # set.
+    attr_accessor :text_alignment
+
+    # Array of 2-element sub-arrays such that the 1st element in each
+    # sub-array is a +Range+ of float values which describe the start
+    # and end points of the range marker, and the 2nd element in each
+    # sub-array is an rrggbb color for the range marker.  For +:top+
+    # and +:bottom+ +AXIS_TYPES+, markers are vertical. For +:right+
+    # and +:left+ +AXIS_TYPES+, markers are horizontal.
+    attr_accessor :range_markers
+
+    AXIS_TYPES = [ :top, :right, :bottom, :left ]
+
+    # Defaults: +:left+ for +RightAxis+, +:center+ for +TopAxis+ and
+    # for +BottomAxis+, and +:right+ for +LeftAxis+.
+    TEXT_ALIGNMENT = { :left => -1, :center => 0, :right => 1 }
+
+    class << self
+      # Instantiates the proper +GChart::Axis+ subclass based on the
+      # +axis_type+.
+      def create(axis_type, &block)
+        raise ArgumentError.new("Invalid axis type '#{axis_type}'") unless AXIS_TYPES.include?(axis_type)
+
+        axis = Object.module_eval("GChart::#{axis_type.to_s.capitalize}Axis").new
+
+        yield(axis) if block_given?
+        axis
+      end
+
+      private :new
+    end
+
+    def initialize
+      @labels          = []
+      @label_positions = []
+      @range_markers   = {}
+    end
+
+    # Returns a one-character label of the axis according to its type.
+    def axis_type_label
+      raise NotImplementedError.new("Method must be overridden in a subclass of this abstract base class.")
+    end
+
+    # Returns a one-character label to indicate whether
+    # +ranger_markers+ are vertical or horizontal.
+    def range_marker_type_label
+      raise NotImplementedError.new("Method must be overridden in a subclass of this abstract base class.")
+    end
+
+    # Ensures that all combinations of attributes which have been set
+    # will work with each other. Raises +ArgumentError+ otherwise.
+    def validate!
+      if labels.size > 0 and label_positions.size > 0 and labels.size != label_positions.size
+        raise ArgumentError.new(
+          "Both labels and label_positions have been specified, but their " +
+          "respective counts do not match (labels.size = '#{labels.size}' " +
+          "and label_positions.size = '#{label_positions.size}')"
+        )
+      end
+
+      unless label_positions.all? { |pos| pos.is_a?(Numeric) }
+        raise ArgumentError.new(
+          "The label_positions attribute requires numeric values for each position specified"
+        )
+      end
+
+      if range
+        unless range.is_a?(Range)
+          raise ArgumentError.new("The range attribute has been specified with a non-Range class")
+        end
+
+        unless range.first.is_a?(Numeric)
+          raise ArgumentError.new("The range attribute has been specified with non-numeric range values")
+        end
+      end
+
+      if font_size and not text_color
+        raise ArgumentError.new("To specify a font_size, a text_color must also be specified")
+      end
+
+      if text_alignment and not (text_color and font_size)
+        raise ArgumentError.new(
+          "To specify a text_alignment, both text_color and font_size must also be specified"
+        )
+      end
+
+      if text_color and not GChart.valid_color?(text_color)
+        raise ArgumentError.new("The text_color attribute has been specified with an invalid color")
+      end
+
+      if font_size and not font_size.is_a?(Numeric)
+        raise ArgumentError.new("The font_size must have a numeric value")
+      end
+
+      if text_alignment and not TEXT_ALIGNMENT[text_alignment]
+        raise ArgumentError.new(
+          "The text_alignment attribute has been specified with a non-TEXT_ALIGNMENT"
+        )
+      end
+
+      if not range_markers.all? { |array| array.is_a?(Array) and array.size == 2 and
+                                          array[0].is_a?(Range) and array[0].first.is_a?(Numeric) and
+                                          GChart.valid_color?(array[1]) }
+        raise ArgumentError.new(
+          "The range_markers attribute must be an array of 2-element sub-arrays such that " +
+          "the first element in each sub-array is a Range of numeric values and the second " +
+          "element in each sub-array is a valid color"
+        )
+      end
+    end
+
+  end
+end

data/lib/gchart/axis/bottom_axis.rb

@@ -0,0 +1,10 @@
+module GChart
+  class BottomAxis < HorizontalAxis
+    # Returns 'x'.
+    def axis_type_label
+      'x'
+    end
+
+    class << self ; public :new ; end
+  end
+end

data/lib/gchart/axis/horizontal_axis.rb

@@ -0,0 +1,11 @@
+module GChart
+  class HorizontalAxis < Axis
+    # Returns 'R' to indicate a vertical +range_marker+ (stemming
+    # from a horizontal axis).
+    def range_marker_type_label
+      'R'
+    end
+
+    class << self ; private :new ; end
+  end
+end

data/lib/gchart/axis/left_axis.rb

@@ -0,0 +1,10 @@
+module GChart
+  class LeftAxis < VerticalAxis
+    # Returns 'y'.
+    def axis_type_label
+      'y'
+    end
+
+    class << self ; public :new ; end
+  end
+end

data/lib/gchart/axis/right_axis.rb

@@ -0,0 +1,10 @@
+module GChart
+  class RightAxis < VerticalAxis
+    # Returns 'r'.
+    def axis_type_label
+      'r'
+    end
+
+    class << self ; public :new ; end
+  end
+end

data/lib/gchart/axis/top_axis.rb

@@ -0,0 +1,10 @@
+module GChart
+  class TopAxis < HorizontalAxis
+    # Returns 't'.
+    def axis_type_label
+      't'
+    end
+
+    class << self ; public :new ; end
+  end
+end

data/lib/gchart/axis/vertical_axis.rb

@@ -0,0 +1,11 @@
+module GChart
+  class VerticalAxis < Axis
+    # Returns 'r' to indicate a horizontal +range_marker+ (stemming
+    # from a vertical axis).
+    def range_marker_type_label
+      'r'
+    end
+
+    class << self ; private :new ; end
+  end
+end

data/lib/gchart/base.rb

@@ -5,31 +5,44 @@ module GChart
   class Base
     # Array of chart data. See subclasses for specific usage.
     attr_accessor :data
-    
+
     # Hash of additional HTTP query params.
     attr_accessor :extras
-    
+
     # Chart title.
     attr_accessor :title
-    
+
     # Array of rrggbb colors, one per data set.
     attr_accessor :colors
-    
+
     # Array of legend text, one per data set.
     attr_accessor :legend
-    
+
     # Max data value for quantization.
     attr_accessor :max
 
     # Chart width, in pixels.
-    attr_reader :width    
-    
+    attr_reader :width
+
     # Chart height, in pixels.
     attr_reader :height
 
+    # Background rrggbb color of entire chart image.
+    attr_accessor :entire_background
+
+    # Background rrggbb color of just chart area of chart image.
+    attr_accessor :chart_background
+
+    # Array of +GChart::Axis+ objects.
+    attr_accessor :axes
+
     def initialize(options={}, &block)
-      @data = []
+      @data   = []
+      @colors = []
+      @legend = []
+      @axes   = []
       @extras = {}
+
       @width = 300
       @height = 200
   
@@ -51,9 +64,9 @@ module GChart
     # if +height+ is less than 1 or greater than 1,000.
     def height=(height)
       if height.nil? || height < 1 || height > 1_000
-        raise ArgumentError, "Invalid height: #{height.inspect}"         
+        raise ArgumentError, "Invalid height: #{height.inspect}"
       end
-      
+
       @height = height
     end
 
@@ -66,7 +79,7 @@ module GChart
     # if +width+ * +height+ is greater than 300,000 pixels.
     def size=(size)
       self.width, self.height = size.split("x").collect { |n| Integer(n) }
-      
+
       if (width * height) > 300_000
         raise ArgumentError, "Invalid size: #{size.inspect} yields a graph with more than 300,000 pixels"
       end
@@ -90,6 +103,14 @@ module GChart
       open(io_or_file, "w+") { |io| io.write(fetch) }
     end
 
+    # Adds an +axis_type+ +GChart::Axis+ to the chart's set of
+    # +axes+. See +GChart::Axis::AXIS_TYPES+.
+    def axis(axis_type, &block)
+      axis = GChart::Axis.create(axis_type, &block)
+      @axes.push(axis)
+      axis
+    end
+
     protected
     
     def query_params(raw_params={}) #:nodoc:
@@ -99,6 +120,13 @@ module GChart
       render_title(params)
       render_colors(params)
       render_legend(params)
+      render_backgrounds(params)
+
+      unless @axes.empty?
+        if is_a?(GChart::Line) or is_a?(GChart::Bar) or is_a?(GChart::Scatter) # or is_a?(GChart::Radar)
+          render_axes(params)
+        end
+      end
 
       params.merge(extras)
     end
@@ -106,28 +134,129 @@ module GChart
     def render_chart_type #:nodoc:
       raise NotImplementedError, "override in subclasses"
     end
-    
+
     def render_data(params) #:nodoc:
       raw = data && data.first.is_a?(Array) ? data : [data]
-      max = self.max || raw.collect { |s| s.max }.max
-  
-      sets = raw.collect do |set|
-        set.collect { |n| GChart.encode(:text, n, max) }.join(',')
-      end
-  
-      params["chd"] = "t:#{sets.join("|")}"
+
+      encoded = GChart.encode_datasets(raw, max)
+
+      params["chd"] = encoded
     end
     
     def render_title(params) #:nodoc:
       params["chtt"] = title.tr("\n ", "|+") if title
     end
-    
+
     def render_colors(params) #:nodoc:
-      params["chco"] = colors.join(",") if colors  
+      unless colors.empty?
+        params["chco"] = colors.collect{ |color| GChart.expand_color(color) }.join(",")
+      end
     end
-    
+
     def render_legend(params) #:nodoc:
-      params["chdl"] = legend.join("|") if legend
-    end    
+      params["chdl"] = legend.join("|") unless legend.empty?
+    end
+
+    def render_backgrounds(params) #:nodoc:
+      if entire_background || chart_background
+        if entire_background and not GChart.valid_color?(entire_background)
+          raise ArgumentError.new("The entire_background attribute has an invalid color")
+        end
+        if chart_background and not GChart.valid_color?(chart_background)
+          raise ArgumentError.new("The chart_background attribute has an invalid color")
+        end
+
+        separator = entire_background && chart_background ? "|" : ""
+        params["chf"]  = entire_background ? "bg,s,#{GChart.expand_color(entire_background)}" : ""
+        params["chf"] += "#{separator}c,s,#{GChart.expand_color(chart_background)}" if chart_background
+      end
+    end
+
+    def render_axes(params) #:nodoc:
+      @axes.each do |axis|
+        axis.validate!
+      end
+
+      render_axis_type_labels(params)
+      render_axis_labels(params)
+      render_axis_label_positions(params)
+      render_axis_ranges(params)
+      render_axis_styles(params)
+      render_axis_range_markers(params)
+    end
+
+    def render_axis_type_labels(params) #:nodoc:
+      params["chxt"] = @axes.collect{ |axis| axis.axis_type_label }.join(',')
+    end
+
+    def render_axis_labels(params) #:nodoc:
+      if @axes.any?{ |axis| axis.labels.size > 0 }
+        chxl = []
+
+        @axes.each_with_index do |axis, index|
+          if axis.labels.size > 0
+            chxl.push("#{index}:")
+            chxl += axis.labels
+          end
+        end
+
+        params["chxl"] = chxl.join('|')
+      end
+    end
+
+    def render_axis_label_positions(params) #:nodoc:
+      if @axes.any?{ |axis| axis.label_positions.size > 0 }
+        chxp = []
+
+        @axes.each_with_index do |axis, index|
+          chxp.push("#{index}," + axis.label_positions.join(',')) if axis.label_positions.size > 0
+        end
+
+        params["chxp"] = chxp.join('|')
+      end
+    end
+
+    def render_axis_ranges(params) #:nodoc:
+      if @axes.any?{ |axis| axis.range }
+        chxr = []
+
+        @axes.each_with_index do |axis, index|
+          chxr.push("#{index},#{axis.range.first},#{axis.range.last}") if axis.range
+        end
+
+        params["chxr"] = chxr.join('|')
+      end
+    end
+
+    def render_axis_styles(params) #:nodoc:
+      if @axes.any?{ |axis| axis.text_color }
+        chxs = []
+
+        @axes.each_with_index do |axis, index|
+          if axis.text_color
+            chxs.push(
+              "#{index}," +
+              [GChart.expand_color(axis.text_color), axis.font_size, axis.text_alignment].compact.join(',')
+            )
+          end
+        end
+
+        params["chxs"] = chxs.join('|')
+      end
+    end
+
+    def render_axis_range_markers(params) #:nodoc:
+      if @axes.any?{ |axis| axis.range_markers.size > 0 }
+        chmr = []
+
+        @axes.each do |axis|
+          axis.range_markers.each do |range, color|
+            chmr.push("#{axis.range_marker_type_label},#{color},0,#{range.first},#{range.last}")
+          end
+        end
+
+        params["chm"] = chmr.join('|')
+      end
+    end
   end
 end