a_la_chart 0.0.2 → 0.0.3

data/History.txt

@@ -1,3 +1,8 @@
+=== 0.0.3 2009-12-18
+
+* 1 major enhancement:
+  * replaced paths to include special formats (chartxml, chartjs, chartjson) for remote data
+
 === 0.0.2 2009-12-17
 
 * 1 major enhancement:

data/README.rdoc

@@ -4,22 +4,118 @@
 
 == DESCRIPTION:
 
-This is a general framework for inserting various type of charting implementations - from grabbing the data, to declaring how those values are mapped to the desired type of chart (pie, line, bar, etc).
+'a la Chart' (ALC) is a framework for managing various chart implementations - from grabbing the data, to declaring how those values are mapped to the desired type of chart (pie, line, bar, etc), and finally rendering them. Note: ALC is very much in alpha development and not recommended for public use.
 
 == SUPPORT:
 
-Note: very much in development
+Note: very much in alpha development
 
-* Fusion Charts (partial)
-* Google Charts (partial)
-* gRaphaël (partial)
+* Google Charts 1.0 (partial)
+* Fusion Charts 3.x (partial)
+* gRaphaël 1.2 (partial)
 
 == INSTALL:
 
-To install this plugin:
+It is recommended to install this as a gem from http://gemcutter.org
+
+    gem sources -a http://gemcutter.org
+    gem install a_la_chart
+
+Set up the gem in your environment.rb
+
+  config.gem "a_la_chart", :source => "http://gemcutter.org"
+
+OR - to install this directly as a Rails plugin (not recommended, but available):
 
     script/plugin install git://github.com/coderoshi/a_la_chart.git
 
+Once you have installed 'a la Chart', you can start creating charts immediately. Since Google Charts can function without any further install (it just hits a Google URL to generate an image inline), you can technically use 'a la Chart' (ALC) without any further install - but that's also kind of boring. If you need to use another supported charting framework, such as Fusion Charts or gRaphaël, you must install them locally, as per their normal install instructions. This generally means placing the required files (javascript, flash) in your project's /public directory, and linking to them via html header tags in your relevant /app/views/layouts files.
+
+For example, in our project we use the gRaphaël dot chart, so populate our /app/views/layouts/reports.html.haml with this HAML javascript tag
+
+    = javascript_include_tag "raphael", "jquery", "g.raphael.js", "g.dot.js"
+
+We also use Fusion charts, and install them in a similar way (along with the necessary flash and javascript files under /public)
+
+    = javascript_include_tag "FusionCharts", "FusionMaps", "FusionChartsDOM"
+
+== USAGE:
+
+ALC logic is in two parts: controller and view. To activate a controller add the 'a_la_chart' directive
+
+  class PeopleController < ApplicationController
+    a_la_chart
+  end
+
+=== Data and Mapping
+
+To declare the style of data returned, you call 'chart' with the style of chart (you can have more than one, eg. 'chart :pie, :line'). Within the chart directive, you return the list of data objects (Objects or Hashes), and finally a 'meta', which describes how to map each object to the relevant chart data. For example, we have a Person model, tied to a city name. We want to build a pie chart which counts the people in each city.
+
+  class PeopleController < ApplicationController
+    a_la_chart
+    
+    chart :pie do
+      data do
+        Person.all(:select => 'city, COUNT(people.*) as total', :group => 'city')
+      end
+      meta :label => :city, :value => :total
+    end
+  end
+
+http://chart.apis.google.com/chart?cht=p&chd=t:6,5,3&chs=300x180&chl=Chicago|Indy|New%20York&.jpg
+
+In a pie chart, there are two kinds of required data per slice: A value (how many people live in each city) and a label (what is the name of the city). meta points the two generic requirements (label and value) to specific methods in the returned objects (or key names, if an array of Hash objects are returned). ALC will effectively call "item.city" for each label.
+
+If your query does not return data which maps to a specific method or key, meta can also map requirements to procedure blocks (Proc.new, proc, or lambda) which procedurally extracts values from each item in the returned list of data values.
+
+    chart :pie do
+      data do
+        Person.count(:group => :gender)
+      end
+      meta :label => proc{|item| item[0].blank? ? 'Unknown' : item[0] }, :value => 1
+    end
+
+ALC will effectively call "item[0].blank? ? 'Unknown' : item[0]" for each label.
+
+=== View Chart
+
+Note that we have yet to define the type of charting engine we wish to use. Since that is a view-level decision, we will place that in the view. Before continuing, let us assume you wish to display a report page with a table of people information - alongside the pie chart which displays the count of people per city.
+
+To start, create a "def index" in the PeopleController which returns the list of people, as you normally would.
+
+  class PeopleController < ApplicationController
+    a_la_chart
+    
+    chart :pie do
+      data do
+        Person.all(:select => 'city, COUNT(people.*) as total', :group => 'city')
+      end
+      meta :label => :city, :value => :total
+    end
+    
+    def index
+      @people = People.all
+    end
+  end
+
+The corresponding index.html.haml (or index.html.erb, or whatever) will look something like this
+
+  = chart_tag :google, :pie
+  %table
+    %tr
+      %th Name
+      %th City
+    - @people.each do |person|
+      %tr
+        %td&= person.name
+        %td&= person.city
+
+Except for the chart_tag, it's pretty normal. Here we pass in the minimum required fields for chart_tag: the chart implementation (:google, :fusion, :raphael are the first to be supported, more to come), and the chart type (dependent on the implementation, see a_la_chart/configs/*/config.yml for the lists). Certain configs are supported by all implementations, such as :width and :height.
+
+  = chart_tag :fusion, :angular, :height => 300, :width => 300, :title => 'My Angular Chart'
+
+More to come...
+
 == LICENSE:
 
 Copyright (c) 2009 Mobi, released under the MIT license

data/configs/fusion/3.0/angular.xml.builder

@@ -1,11 +1,12 @@
 xml.instruct!
 xml.chart(chart_options.merge(:upperLimit => params[:upperLimit] || 100, :caption => params[:title])) do
+  the_case = params[:case]
   xml.colorRange do
     xml.color :minValue => '0', :maxValue => '2', :code => 'FF654F'
     xml.color :minValue => '2', :maxValue => '4', :code => 'F6BD0F'
     xml.color :minValue => '4', :maxValue => '5', :code => '8BBA00'
   end
   xml.dials do
-    xml.dial :value => value(data, :value)
+    xml.dial :value => value(data, :value, the_case)
   end
 end

data/configs/fusion/3.0/bar.xml.builder

@@ -1,6 +1,7 @@
 xml.instruct!
 xml.chart(chart_options.merge(:caption => params[:title])) do
-  data.each do |record|
-    xml.set :value => value(record, :value), :label => value(record, :label), :color => next_color
+  the_case = params[:case]
+  data(the_case).each do |record|
+    xml.set :value => value(record, :value, the_case), :label => value(record, :label, the_case), :color => next_color
   end
 end

data/configs/fusion/3.0/column.xml.builder

@@ -1,6 +1,7 @@
 xml.instruct!
 xml.chart(chart_options.merge(:caption => params[:title])) do
-  data.each do |record|
-    xml.set :value => value(record, :value), :label => value(record, :label), :link => value(record, :link), :color => next_color
+  the_case = params[:case]
+  data(the_case).each do |record|
+    xml.set :value => value(record, :value, the_case), :label => value(record, :label, the_case), :link => value(record, :link, the_case), :color => next_color
   end
 end

data/configs/fusion/3.0/line.xml.builder

@@ -1,7 +1,8 @@
 xml.instruct!
 xml.chart(chart_options.merge(:caption => params[:title])) do
+  the_case = params[:case]
   xml.dataset do |dataset|
-    data.each do |set|
+    data(the_case).each do |set|
       xml.set :value => set
     end
   end

data/configs/fusion/3.0/pie.xml.builder

@@ -1,6 +1,7 @@
 xml.instruct!
 xml.chart(chart_options.merge(:caption => params[:title])) do
-  data.each do |record|
-    xml.set :value => value(record, :value), :label => value(record, :label), :color => next_color
+  the_case = params[:case]
+  data(the_case).each do |record|
+    xml.set :value => value(record, :value, the_case), :label => value(record, :label, the_case), :color => next_color
   end
 end

data/configs/fusion/config.yml

@@ -1,5 +1,6 @@
 default: 3.0
 3.0:
+  format: xml
   angular:
     data: 'angular.xml.builder'
     chart_type: AngularGauge

data/configs/raphael/config.yml

@@ -1,8 +1,9 @@
 default: 1.2
 1.2:
+  format: js
   impact:
     data: 'impact.js.erb'
     inline: 'inline.html.erb'
-    url: 'impact.js'
+    # url: '.chartjs'
   dot:
     inline: 'dot.html.erb'

data/lib/a_la_chart/a_la_chart.rb

@@ -1,26 +1,32 @@
 module ALaChart
   
   module HelperMethods
-    def meta
-      @metadata ||= defined?(get_meta) ? get_meta : {}
-    end
-
-    def fields
-      @fields ||= defined?(get_fields) ? get_fields : []
+    def meta(the_case=nil)
+      if the_case.blank?
+        @metadata ||= defined?(get_meta) ? get_meta : {}
+      else
+        @metadata ||= respond_to?("get_meta_#{the_case.to_s}") ? send("get_meta_#{the_case.to_s}") : []
+      end
     end
-  
-    def data
-      @data ||= defined?(get_data) ? get_data : []
+    
+    def data(the_case=nil)
+      if the_case.blank?
+        @data ||= defined?(get_data) ? get_data : []
+      else
+        @data ||= respond_to?("get_data_#{the_case.to_s}") ? send("get_data_#{the_case.to_s}") : []
+      end
     end
-  
-    def value(object, key)
-      return '' if object.blank?
     
+    def value(object, key, the_case=nil)
+      return '' if object.blank?
+      
       # if there is a meta map, use it. else try the key itself
-      key_field = meta[key] || key
-    
+      key_field = meta(the_case)[key] || key
+      
       if key_field.class == Proc
         val = key_field.call(object)
+      elsif key_field.class == Fixnum
+        val = object[key_field] if object.respond_to?('[]')
       else
         val = object.respond_to?(key_field) ? object.send(key_field) : nil
         val = object[key_field] if object.respond_to?('[]')
@@ -52,8 +58,8 @@ module ALaChart
     include HelperMethods
     
     def provide_chart_data
-      chart_make = params[:chart_make]
-      chart_type = params[:id]
+      chart_make = params[:cm]
+      chart_type = params[:ct]
       
       chart_type_config, chart_make_version = nil, nil
       if !chart_make.nil? && (chart_make_config = a_la_chart_config[chart_make.to_sym])
@@ -65,9 +71,9 @@ module ALaChart
       return if chart_type_config.nil? || !respond_to?("set_chart_#{chart_type}")
       
       respond_to do |format|
-        # format.html # index.html.erb
-        format.xml { render_style chart_make, chart_type, chart_make_version, chart_type_config }
-        format.js { render_style chart_make, chart_type, chart_make_version, chart_type_config }
+        format.chartxml  { render_style(chart_make, chart_type, chart_make_version, chart_type_config) }
+        format.chartjs   { render_style(chart_make, chart_type, chart_make_version, chart_type_config) }
+        format.chartjson { render_style(chart_make, chart_type, chart_make_version, chart_type_config) }
       end
     end
 
@@ -100,7 +106,10 @@ module ALaChart
     def a_la_chart
       include ALaChart::InstanceMethods
       
-      self.before_filter(:provide_chart_data, :only => [:show])
+      # TODO: We should ensure this is for inherited_resources
+      self.respond_to(:chartxml, :chartjs, :chartjson) if defined?(self.respond_to)
+      
+      self.before_filter(:provide_chart_data, :only => [:index, :show])
       
       # Namespace this stuff??
       [:data, :fields, :meta, :value, :a_la_chart_config, :set_chart].each do |method|
@@ -120,19 +129,44 @@ module ALaChart
       end
     end
   
-    def data(&block)
-      define_method("get_data") do
-        # note: instance_eval binds scope variables, call does not
-        instance_eval(&block) || []
-        # block.call(binding)
+    def data(*attrs, &block)
+      if attrs.size == 1
+        attrs = attrs[0]
+        if attrs.class == Hash
+          options = attrs
+        elsif attrs.class == Symbol || attrs.class == String
+          cases = [attrs]
+        end
+      elsif attrs.size > 1
+        cases = attrs[0...-1]
+        options = attrs[-1]
       end
-    end
-  
-    def fields(*attrs)
-      field_ary = attrs.map{|d| d.to_sym }
-    
-      define_method("get_fields") do
-        field_ary
+      
+      cases ||= []
+      options ||= {}
+      
+      if cases.blank?
+        define_method("get_data") do
+          # note: instance_eval binds scope variables, call does not
+          instance_eval(&block) || []
+          # block.call(binding)
+        end
+        unless options.blank?
+          define_method("get_meta") do
+            options
+          end
+        end
+      else
+        cases.each { |caze|
+          define_method("get_data_#{caze}") do
+            # note: instance_eval binds scope variables, call does not
+            instance_eval(&block) || []
+            # block.call(binding)
+          end
+          define_method("get_meta_#{caze}") do
+            options
+          end
+        }
       end
     end
   

data/lib/a_la_chart/a_la_chart_helper.rb

@@ -20,16 +20,18 @@ module ALaChartHelper
     chart_type = chart_style.to_s if chart_type.blank?
     inline_template = chart_type_config['inline']
     
-    append_url = chart_type_config['url']
-    append_url = "#{chart_style.to_s}.xml" if append_url.blank?
-    url += "/#{append_url}?"
+    data_format = chart_type_config['format'] || chart_make_config['format']
+    
+    append_url = chart_type_config['url'] || ".chart#{data_format}"
+    url += "#{append_url}?"
     
     explicit_args = args[:args].present? ? params.merge(args[:args]) : params
     args.reject!{ |k,v| [:name,:width,:height,:base_url].include?(k) }
     args.merge!(explicit_args)
     # Can I do this? Or does it make me look like...
     args.reject!{ |k,v| ['action','controller'].include?(k) }
-    args[:chart_make] = chart_make
+    args[:cm] = chart_make.to_s
+    args[:ct] = chart_style.to_s
     
     url += args.to_param
     
@@ -38,7 +40,8 @@ module ALaChartHelper
     inline = ERB.new(File.read(File.join(File.dirname(__FILE__), '..', '..', 'configs', chart_make.to_s, chart_make_version.to_s, inline_template)))
     inline.result(binding)
   end
-    
+  
+  # TODO: REMOVE all of this stuff... make this all external configurations
   def color_palette
     ["7BB465","B2B4B6","FEC35A","65A4B5","9E65B5","B57765","F7DF65","8F866C","B6A65F","C99D60","C1727A","8AABB9","65B584"]
   end

data/lib/a_la_chart.rb

@@ -1,5 +1,5 @@
 module ALaChart
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end
 
 require File.join(File.dirname(__FILE__), 'a_la_chart', 'a_la_chart')
@@ -9,3 +9,7 @@ ActionController::Base.class_eval do
   include ALaChart
 end
 ActionView::Base.send :include, ALaChartHelper
+
+Mime::Type.register "application/xml", :chartxml, %w( text/xml application/x-xml ) unless defined?(Mime::CHARTXML)
+Mime::Type.register "text/javascript", :chartjs, %w( application/javascript application/x-javascript ) unless defined?(Mime::CHARTJS)
+Mime::Type.register "application/json", :chartjson, %w( text/x-json application/jsonrequest ) unless defined?(Mime::CHARTJSON)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: a_la_chart
 version: !ruby/object:Gem::Version 
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors: 
 - Eric Redmond
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-17 00:00:00 -05:00
+date: 2009-12-18 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,7 +22,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 2.3.3
     version: 
-description: This is a general framework for inserting various type of charting implementations - from grabbing the data, to declaring how those values are mapped to the desired type of chart (pie, line, bar, etc).
+description: "'a la Chart' (ALC) is a framework for managing various chart implementations - from grabbing the data, to declaring how those values are mapped to the desired type of chart (pie, line, bar, etc), and finally rendering them. Note: ALC is very much in alpha development and not recommended for public use."
 email: 
 - eric.redmond@gmail.com
 executables: []
@@ -89,7 +89,7 @@ rubyforge_project: a_la_chart
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: This is a general framework for inserting various type of charting implementations - from grabbing the data, to declaring how those values are mapped to the desired type of chart (pie, line, bar, etc).
+summary: "'a la Chart' (ALC) is a framework for managing various chart implementations - from grabbing the data, to declaring how those values are mapped to the desired type of chart (pie, line, bar, etc), and finally rendering them"
 test_files: 
 - test/test_a_la_chart.rb
 - test/test_helper.rb