wayneeseguin-dynamic_reports 0.0.2

data/HISTORY

@@ -0,0 +1,7 @@
+0.0.2
+  - Github compaitble gemspec
+  - Passing tests
+0.0.1
+  - Template fixups
+0.0.0
+  - Initial dynamic reports codebase.

data/README

@@ -0,0 +1,189 @@
+= Dynamic Reports
+
+  A dynamic reporting engine for Ruby / Rails
+
+== Reports
+  
+  The dynamic reports gem was created to fill a HUGE hole that we felt existed in the 
+  Ruby community - the ability to QUICKLY create stylized admin reports and charts for 
+  people to use to view key metrics and data. 
+
+  Sample uses include the ability to quickly display sales data if your an eShop, our 
+  site metrics if you are recording your own site visits, or user feedback if you are storing 
+  feedback in a model somewhere.
+
+  Basically, with DR you can create a stylized table of ANY information found in a model 
+  (kind of like looking at the grid output from a GUI query analyzer) as well as add Google 
+  Charts API powered line, pie, bar or column charts of any numeric data.  All this can 
+  be done by simply creating a report definition and feeding it your data.
+
+  While this library is usable in any Ruby application it was made mainly with Rails in mind.
+  Suppose we have an online store and we wish to add reporting to the admin area quickly and easily.
+  First we define a report in app/reports/orders_report.rb, something like:
+  
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      subtitle "All orders recorded in database"
+      columns :total, :created_at
+    end
+  
+  Then in our admin/reports controller (this can be any controller) we define an action to deliver the report:
+  
+    def orders
+      @orders = Order.find(:all, :limit => 25)
+      render :text => OrdersReport.on(@orders).to_html, :layout => "application"
+    end
+    
+  This will render an html table containing some basic styling and containing the columns 'total' and 'created_at' from the order objects.
+  Note that the report Title will be "Orders Report" and it's name will be :orders_report
+  Report#on expects that it receives an object that responds to #each and
+  That each object that it iterates over is either a
+    * An object
+    * A Hash
+  that responds to a method / has keys for each column defined within the report.
+ 
+
+  Templating engines may also be specified, currently :erb and :haml are supported (we will soon be adding :csv and :pdf) like so:
+
+      render :text => OrdersReport.on(@orders).to_html(:engine => :haml), :layout => "application"
+
+  Note that erb is the default templating engine since it is available by default in Ruby.
+
+  Now let us extend our report definition to specify a template to use!
+
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      subtitle "All orders recorded in database"
+      columns :total, :created_at
+
+      template :my_custom_template
+    end
+
+  This will look in app/views/reports/ for a template named "my_custom_template.html.erb" by default.
+  If you specify :engine => :haml then it will look for "my_custom_template.html.haml"
+
+  If you happen to have your report templates in a different location you can specify this as follows:
+
+    class OrdersReport < DynamicReports::Report
+       title "Orders Report"
+      subtitle "All orders recorded in database"
+      columns :total, :created_at
+
+      template :my_custom_template
+      views "app/views/admin/reports/"
+    end
+  
+  And DynamicReports will look for the specified template in app/views/reports as well as app/views/admin/reports.
+
+  It is also worth pointing out that you can have as many dynamic reports in a view as you wish, simply include
+  each report render where desired within the view.
+
+== Charts
+  
+  Charts can be defined on a report easily. Let's say we wish to chart the total versus the item quantity sold for our Orders Report exmaple:
+
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      subtitle "All orders recorded in database"
+      columns :total, :created_at
+
+      chart :total_vs_quantity do
+        columns :total, :quantity
+        label_column "created_at"
+      end
+    end
+
+  This will render a *line* chart by default displaying the columns total and quantity.
+  Chart types may be specified easily:
+  
+        type :bar
+  
+  Available chart types are:
+
+    * :line (default)
+    * :bar
+    * :pie
+
+  Since DynamicReport's charts utilize the Google Chart API, you can easily extend each chart by passing a hash of chart options as part
+  of the block.  The options are appended onto the request to the API so they should follow the Google's API commands (http://code.google.com/apis/chart/)
+
+  For example, to add min, max and average labels to the example chart, you would do something like this:
+
+    chart :total_vs_quantity, {:chxt => "r", :chxl => "0:|min|average|max"} do
+        columns :total, :quantity
+        label_column "created_at"
+    end
+
+== Stylizing
+
+  The reports are, by default, stylized with an inline style sheet.  The styles produce a nicely formatted grid with
+  a white on black header row and black on white columns with a gray border througout.
+
+  You can create your own styles by simply adding a class_name object to the report definition as such:
+
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      subtitle "All orders recorded in database"
+      columns :total, :created_at
+
+      class_name "my_class_name"
+    end
+
+  This will cause DR to simply not include the inline style.  From there you can customer the styles using the
+  following sub-classes for your class name, for example:
+
+    .my_class_name .report_title {}
+    .my_class_name .report_subtitle {}
+    .my_class_name table tr th {}
+    .my_class_name table tr td {}
+    .my_class_name .report_charts {}        // all charts are displayed within this div
+    .my_class_name .report_chart {}         // represents an individual chart
+
+== Rails Usage
+  
+  Inside the initializer block in config/environment.rb 
+
+    config.gem "dynamic_reports"
+
+  Then define your reports (as exampled above) in app/reports/*_report.rb
+  If you would like to customize the default report simply create your report templates 
+  within app/views/reports/*_report.<content-type>.<engine>.
+
+  Two Rails features that we are currently working on are:
+
+    * generator
+    * render extensions
+
+== Optional Dependencies
+
+  We are currently examining solutions for csv, pdf and charting.
+
+    * Fastercsv     # csv
+    * Prawn         # pdf
+    * flying saucer # html => PDF - if jRuby available
+    * amcharts      # Charting, note that default is built in google charts.
+
+  These will be defined/implemented using DynamicReports plugin API (not implemented yet)
+  Which allows for user defined plugins of arbitrary types beyond html,csv,pdf,xml
+
+== Contact / Feedback
+
+  If you have any suggestions on improvement please send us an email.
+
+== Authors (alphabetically)
+
+  Joshua Lippiner (jlippiner@gmail.com)
+
+  Wayne E. Seguin (wayneeseguin@gmail.com, irc: wayneeseguin)
+
+== Thanks To
+
+  * Daniel Neighman
+  * Kenneth Kalmer (And his friend :))
+  * Yehuda Katz
+
+  For their encouragement, feedback and advise.
+
+== Source
+  http://github.com/wayneeseguin/dynamic_reports
+

data/README.rdoc

@@ -0,0 +1,189 @@
+= Dynamic Reports
+
+  A dynamic reporting engine for Ruby / Rails
+
+== Reports
+  
+  The dynamic reports gem was created to fill a HUGE hole that we felt existed in the 
+  Ruby community - the ability to QUICKLY create stylized admin reports and charts for 
+  people to use to view key metrics and data. 
+
+  Sample uses include the ability to quickly display sales data if your an eShop, our 
+  site metrics if you are recording your own site visits, or user feedback if you are storing 
+  feedback in a model somewhere.
+
+  Basically, with DR you can create a stylized table of ANY information found in a model 
+  (kind of like looking at the grid output from a GUI query analyzer) as well as add Google 
+  Charts API powered line, pie, bar or column charts of any numeric data.  All this can 
+  be done by simply creating a report definition and feeding it your data.
+
+  While this library is usable in any Ruby application it was made mainly with Rails in mind.
+  Suppose we have an online store and we wish to add reporting to the admin area quickly and easily.
+  First we define a report in app/reports/orders_report.rb, something like:
+  
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      subtitle "All orders recorded in database"
+      columns :total, :created_at
+    end
+  
+  Then in our admin/reports controller (this can be any controller) we define an action to deliver the report:
+  
+    def orders
+      @orders = Order.find(:all, :limit => 25)
+      render :text => OrdersReport.on(@orders).to_html, :layout => "application"
+    end
+    
+  This will render an html table containing some basic styling and containing the columns 'total' and 'created_at' from the order objects.
+  Note that the report Title will be "Orders Report" and it's name will be :orders_report
+  Report#on expects that it receives an object that responds to #each and
+  That each object that it iterates over is either a
+    * An object
+    * A Hash
+  that responds to a method / has keys for each column defined within the report.
+ 
+
+  Templating engines may also be specified, currently :erb and :haml are supported (we will soon be adding :csv and :pdf) like so:
+
+      render :text => OrdersReport.on(@orders).to_html(:engine => :haml), :layout => "application"
+
+  Note that erb is the default templating engine since it is available by default in Ruby.
+
+  Now let us extend our report definition to specify a template to use!
+
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      subtitle "All orders recorded in database"
+      columns :total, :created_at
+
+      template :my_custom_template
+    end
+
+  This will look in app/views/reports/ for a template named "my_custom_template.html.erb" by default.
+  If you specify :engine => :haml then it will look for "my_custom_template.html.haml"
+
+  If you happen to have your report templates in a different location you can specify this as follows:
+
+    class OrdersReport < DynamicReports::Report
+       title "Orders Report"
+      subtitle "All orders recorded in database"
+      columns :total, :created_at
+
+      template :my_custom_template
+      views "app/views/admin/reports/"
+    end
+  
+  And DynamicReports will look for the specified template in app/views/reports as well as app/views/admin/reports.
+
+  It is also worth pointing out that you can have as many dynamic reports in a view as you wish, simply include
+  each report render where desired within the view.
+
+== Charts
+  
+  Charts can be defined on a report easily. Let's say we wish to chart the total versus the item quantity sold for our Orders Report exmaple:
+
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      subtitle "All orders recorded in database"
+      columns :total, :created_at
+
+      chart :total_vs_quantity do
+        columns :total, :quantity
+        label_column "created_at"
+      end
+    end
+
+  This will render a *line* chart by default displaying the columns total and quantity.
+  Chart types may be specified easily:
+  
+        type :bar
+  
+  Available chart types are:
+
+    * :line (default)
+    * :bar
+    * :pie
+
+  Since DynamicReport's charts utilize the Google Chart API, you can easily extend each chart by passing a hash of chart options as part
+  of the block.  The options are appended onto the request to the API so they should follow the Google's API commands (http://code.google.com/apis/chart/)
+
+  For example, to add min, max and average labels to the example chart, you would do something like this:
+
+    chart :total_vs_quantity, {:chxt => "r", :chxl => "0:|min|average|max"} do
+        columns :total, :quantity
+        label_column "created_at"
+    end
+
+== Stylizing
+
+  The reports are, by default, stylized with an inline style sheet.  The styles produce a nicely formatted grid with
+  a white on black header row and black on white columns with a gray border througout.
+
+  You can create your own styles by simply adding a class_name object to the report definition as such:
+
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      subtitle "All orders recorded in database"
+      columns :total, :created_at
+
+      class_name "my_class_name"
+    end
+
+  This will cause DR to simply not include the inline style.  From there you can customer the styles using the
+  following sub-classes for your class name, for example:
+
+    .my_class_name .report_title {}
+    .my_class_name .report_subtitle {}
+    .my_class_name table tr th {}
+    .my_class_name table tr td {}
+    .my_class_name .report_charts {}        // all charts are displayed within this div
+    .my_class_name .report_chart {}         // represents an individual chart
+
+== Rails Usage
+  
+  Inside the initializer block in config/environment.rb 
+
+    config.gem "dynamic_reports"
+
+  Then define your reports (as exampled above) in app/reports/*_report.rb
+  If you would like to customize the default report simply create your report templates 
+  within app/views/reports/*_report.<content-type>.<engine>.
+
+  Two Rails features that we are currently working on are:
+
+    * generator
+    * render extensions
+
+== Optional Dependencies
+
+  We are currently examining solutions for csv, pdf and charting.
+
+    * Fastercsv     # csv
+    * Prawn         # pdf
+    * flying saucer # html => PDF - if jRuby available
+    * amcharts      # Charting, note that default is built in google charts.
+
+  These will be defined/implemented using DynamicReports plugin API (not implemented yet)
+  Which allows for user defined plugins of arbitrary types beyond html,csv,pdf,xml
+
+== Contact / Feedback
+
+  If you have any suggestions on improvement please send us an email.
+
+== Authors (alphabetically)
+
+  Joshua Lippiner (jlippiner@gmail.com)
+
+  Wayne E. Seguin (wayneeseguin@gmail.com, irc: wayneeseguin)
+
+== Thanks To
+
+  * Daniel Neighman
+  * Kenneth Kalmer (And his friend :))
+  * Yehuda Katz
+
+  For their encouragement, feedback and advise.
+
+== Source
+  http://github.com/wayneeseguin/dynamic_reports
+

data/dynamic_reports.gemspec

@@ -0,0 +1,62 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{dynamic_reports}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Wayne E. Seguin", "Joshua Lippiner"]
+  s.date = %q{2009-07-01}
+  s.description = %q{Dynamic Ruby Reporting Engine with support for Charts.}
+  s.email = %q{wayneeseguin@gmail.com, jlippiner@gmail.com}
+  s.extra_rdoc_files = [
+    "README",
+     "README.rdoc"
+  ]
+  s.files = [
+    "HISTORY",
+     "README",
+     "dynamic_reports.gemspec",
+     "lib/dynamic_reports.rb",
+     "lib/dynamic_reports/charts.rb",
+     "lib/dynamic_reports/reports.rb",
+     "lib/dynamic_reports/templates.rb",
+     "lib/dynamic_reports/vendor/google_chart.rb",
+     "lib/dynamic_reports/vendor/google_chart/bar_chart.rb",
+     "lib/dynamic_reports/vendor/google_chart/base.rb",
+     "lib/dynamic_reports/vendor/google_chart/financial_line_chart.rb",
+     "lib/dynamic_reports/vendor/google_chart/line_chart.rb",
+     "lib/dynamic_reports/vendor/google_chart/pie_chart.rb",
+     "lib/dynamic_reports/vendor/google_chart/scatter_chart.rb",
+     "lib/dynamic_reports/vendor/google_chart/venn_diagram.rb",
+     "lib/dynamic_reports/views.rb",
+     "lib/dynamic_reports/views/default_layout.html.erb",
+     "lib/dynamic_reports/views/default_report.html.erb",
+     "lib/dynamic_reports/views/default_report.html.haml"
+  ]
+  s.homepage = %q{http://dynamicreports.rubyforge.org/}
+  s.rdoc_options = ["--inline-source", "--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{dynamicreports}
+  s.rubygems_version = %q{1.3.3}
+  s.summary = %q{Dynamic Ruby Reporting Engine with support for Charts}
+  s.test_files = [
+    "test/dynamic_reports/charts_test.rb",
+     "test/dynamic_reports/reports_test.rb",
+     "test/dynamic_reports/templates_test.rb",
+     "test/dynamic_reports/views_test.rb",
+     "test/dynamic_reports.rb",
+     "test/factories/records.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/lib/dynamic_reports/charts.rb

@@ -0,0 +1,217 @@
+require 'enumerator'
+
+module DynamicReports
+  class Chart
+    def self.configure(name, *chart_options, &block)
+      chart_options = chart_options.shift || {}
+      chart = new(chart_options)
+      chart.instance_eval(&block)
+      chart.name name
+      chart
+    end
+
+    def initialize(*chart_options)
+      chart_options = chart_options.shift || {}
+      options.merge!(chart_options)
+    end
+
+    def options
+      @options ||= {} ; @options
+    end
+
+    # (Optional) Accessor used to set the chart title:
+    #
+    #   title "Pageviews versus Visits"
+    #
+    # This is displayed above the chart
+    def title(value = nil)
+      value ? options[:title] = value : options[:title]
+    end
+
+    # Accessor used to set or get a specific report.  Must be unique:
+    #
+    #   name "PV_Visits"
+    #
+    def name(value = nil)
+      value ? options[:name] = value.to_sym : options[:name]
+    end
+
+    # (Optional) Accessor used by bar and pie charts to determine the
+    # independent varible chart labels.  Due to size constraints
+    # this is NOT used by column or line charts, but you can add
+    # labels to the X-axis for those charts via chart_options and
+    # passing Google Chart API calls."
+    #
+    # label_column should be a SINGLE column name from the dataset.
+    #
+    #   label_column "recorded_at"
+    #
+    def label_column(value = nil)
+      value ? options[:label_column] = value : options[:label_column]
+    end
+
+    # (Optional - Default = line).  Accessor used to determine the
+    # type of chart to display.  Valid options are line, column, bar
+    # or pie:
+    #
+    #    type "bar"
+    #
+    def type(value = nil)
+      value ? options[:type] = value : (options[:type] || :line)
+    end
+
+    # (Optional - Default = 250).  Accessor used to set the width, in pixels,
+    # of the chart.
+    #
+    #    width "400"
+    #
+    def width(value = nil)
+      value ? options[:width] = value : (options[:width] || "250")
+    end
+
+    # (Optional - Default = 175).  Accessor used to set the height, in pixels,
+    # of the chart.
+    #
+    #    height "350"
+    #
+    def height(value = nil)
+      value ? options[:height] = value : (options[:height] || "175")
+    end
+
+    # (Optional - Default = false).  Accessor used to determine if axis labels
+    # should be shown.  By default y-axis labels are shown.
+    #
+    #    no_labels true
+    #
+    def no_labels(value = nil)
+      value ? options[:no_labels] = value : options[:no_labels]
+    end
+
+    # (Optional) Accessor for columns
+    #
+    # Pass an array of symbols to define columns to chart.  Columns MUST
+    # be numeric in value to chart.
+    #
+    # Example:
+    #
+    #   columns :pageviews, :visits
+    #
+    # You may leave this accessor blank to default to the report columns
+    # specified that are numeric.
+    #
+    def columns(*array)
+      unless array.empty?
+        if (array.class == Array)
+          options[:columns] = array
+        else
+          raise "Report columns must be specified."
+        end
+      else
+        options[:columns]
+      end
+    end
+  end
+
+  # DynamicReports::Charts
+  #
+  #  Class used to display different chart types internally.  Charts are generated
+  #  using Google Charts API
+  #
+  class Charts
+    class << self
+      # Method to select a random color from a list of hex codes
+      #
+      # Example: random_color()
+      # => "ff0000"
+      def random_color()
+        color_list = %w{000000 0000ff ff0000 ffff00 00ffff ff00ff 00ff00}
+        return color_list[rand(color_list.size)]
+      end
+
+      # Method to display a line chart for a given chart definition and report
+      def line_chart(chart, columns, report)
+        ::GoogleChart::LineChart.new("#{chart.width}x#{chart.height}", chart.title, false) do |c|
+          all_data = []
+          columns.each do |column|
+            data = []
+            report.records.each do |record|
+              if record.is_a?(Hash)
+                data << record[column] if record[column].is_a?(Numeric)
+              elsif record.respond_to?(column.to_sym)
+                data << record.send(column.to_sym) if record.send(column.to_sym).is_a?(Numeric)
+              else
+                data << column if column.is_a?(Numeric)
+              end
+            end
+            c.data column, data, random_color() unless data.empty?
+            all_data << data
+          end
+          all_data.flatten!
+          c.axis :y, :range => [all_data.min,all_data.max], :color => 'ff00ff' unless chart.no_labels
+          c.show_legend = columns.size > 1
+
+          return c.to_url(chart.options)
+        end
+      end
+
+      # Method to display a pie chart for a given chart definition and report
+      def pie_chart(chart, columns, report)
+        return if columns.size > 1 || chart.label_column.nil?
+        column = columns.first.to_s
+
+        ::GoogleChart::PieChart.new("#{chart.width}x#{chart.height}", chart.title, false) do |c|
+          report.records.each do |record|
+            if record.is_a?(Hash)
+              c.data record[chart.label_column.to_s], record[column] if record[column].is_a?(Numeric)
+            elsif record.respond_to?(column.to_sym)
+              c.data record.send(chart.label_column.to_s), record.send(column.to_sym) if record.send(column.to_sym).is_a?(Numeric)
+            else
+              c.data chart.label_column.to_s, column if column.is_a?(Numeric)
+            end
+          end
+          c.show_legend = false
+          c.show_labels = true
+
+          return c.to_url(chart.options)
+        end
+      end
+
+      # Method to display a bar or column chart for a given chart definition and report
+      def bar_column_chart(chart, columns, report, orientation)
+        ::GoogleChart::BarChart.new("#{chart.width}x#{chart.height}", chart.title, orientation, true) do |c|
+          all_data = []
+          all_labels = []
+          columns.each do |column|
+            data = []
+            report.records.each do |record|
+              if record.is_a?(Hash)
+                data << record[column] if record[column].is_a?(Numeric)
+                all_labels << record[chart.label_column.to_s] if chart.label_column
+              elsif record.respond_to?(column.to_sym)
+                data << record.send(column.to_sym) if record.send(column.to_sym).is_a?(Numeric)
+                all_labels << record.send(chart.label_column.to_s) if chart.label_column
+              else
+                data << column if column.is_a?(Numeric)
+                all_labels << chart.label_column.to_s if chart.label_column
+              end
+            end
+            c.data column, data, random_color() unless data.empty?
+            all_data << data
+          end
+          all_data.flatten!
+
+          if(orientation==:vertical)
+            c.axis :y, :range => [all_data.min,all_data.max], :color => 'ff00ff' unless chart.no_labels
+          else
+            c.axis :x, :range => [all_data.min,all_data.max], :color => 'ff00ff'  unless chart.no_labels
+            c.axis :y, :labels => all_labels
+          end
+
+          c.show_legend = columns.size > 1
+
+          return c.to_url(chart.options)
+        end
+      end
+    end
+  end
+end