dynamic_reports 0.0.0

data/HISTORY

@@ -0,0 +1,2 @@
+0.0.0
+  - Initial dynamic reports codebase.

data/README

@@ -0,0 +1,146 @@
+= 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
+      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.
+
+  One may also surpress the default rendered styles you may specify that as an option as well:
+
+      render :text => OrdersReport.on(@orders).to_html(:style => false), :layout => "application"
+
+  Now let us extend our report definition to specify a template to use!
+
+    class OrdersReport < DynamicReports::Report
+      columns :total, :created_at
+      template :orders_report
+    end
+
+  This will look in app/views/reports/ for a template named "orders_report.html.erb" by default. 
+  If you specify :engine => :haml then it will look for "orders_report.html.haml"
+
+  If you happen to have your report templates in a different location you can specify this as follows:
+
+    class OrdersReport < DynamicReports::Report
+      columns :total, :created_at
+      template :orders_report
+      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.
+
+== 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
+      columns :total, :created_at
+
+      chart :total_vs_quantity do
+        columns :total, :quantity
+      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
+
+  Other chart types are planned.
+
+== 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/gemspec.rb

@@ -0,0 +1,24 @@
+require "rubygems"
+
+library="dynamic_reports"
+version="0.0.0"
+
+Gem::Specification::new do |spec|
+  $VERBOSE             = nil
+  spec.name            = library
+  spec.summary         = library
+  spec.version         = version
+  spec.description     = "Dynamic Ruby Reporting Engine with support for Charts"
+  spec.platform        = Gem::Platform::RUBY
+  spec.files           = ["HISTORY", "README", "gemspec.rb", Dir::glob("lib/**/**")].flatten
+  spec.executables     = Dir::glob("bin/*").map{ |script| File::basename script }
+  spec.require_path    = "lib"
+  spec.has_rdoc        = File::exist?("doc")
+  spec.author          = "Wayne E. Seguin & Joshua Lippiner"
+  spec.email           = "wayneeseguin@gmail.com, jlippiner@gmail.com"
+  spec.homepage        = "http://github.com/wayneeseguin/direct_reports"
+  # spec.test_suite_file = "test/#{library}.rb" if File::directory?("test")
+  #spec.add_dependency  "gchartrb", ">= 0.8"
+  spec.extensions      << "extconf.rb" if File::exists?("extconf.rb")
+  spec.rubyforge_project = library
+end

data/lib/dynamic_reports.rb

@@ -0,0 +1,47 @@
+# :include: README
+
+# Library Files
+module DynamicReports
+  @@default_view_paths = ["#{File::dirname(File::expand_path(__FILE__))}/dynamic_reports/views/"]
+  def self.default_view_paths
+    @@default_view_paths
+  end
+  def self.default_view_paths=(paths)
+    @@default_view_paths = paths
+  end
+end
+
+require "dynamic_reports/charts"
+require "dynamic_reports/reports"
+require "dynamic_reports/templates"
+require "dynamic_reports/views"
+require "dynamic_reports/vendor/google_chart"
+
+
+# TODO: Figure out why this will not load:
+# require "dynamic_reports/rails"
+# For now placing the code right here:
+if defined?(Rails)
+  # Load all defined reports. 
+  # Question: How to get Rails to reload files other than ones matching the requested constant...
+  #Dir.glob("#{File.join(Rails.root, "app", "reports")}/*.rb").each { |file| require file }
+  ActiveSupport::Dependencies.load_paths << File.join(Rails.root, "app", "reports")
+  # Question: Should we allow for report directory nesting ?
+
+  # Set default views directory
+  # TODO: These should be added to Rails views directories?
+  DynamicReports.default_view_paths += [
+    File.join(Rails.root, "app", "views", "reports"),
+    File.join(Rails.root, "app", "views", "layouts")
+  ]
+
+  # TODO: Render extension
+
+  # TODO: AR extensions:
+  #       has_report :daily, :columns => [...], :options => {...}, :title => ...
+  #         Which will generate a report object DailyReport with the given definition.
+  #         Everything after the name corresponds to options available in the configuration block.
+
+  # TODO: Generator
+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

data/lib/dynamic_reports/reports.rb

@@ -0,0 +1,252 @@
+# DynamicReports
+#
+# Dynamic Reporting Engine for Ruby / Rails
+module DynamicReports
+
+  # DynamicReports::Report
+  # 
+  class Report
+    @@default_engine = "erb"
+
+    attr_accessor :name, :title, :sub_title, :columns, :charts, :records, :template, :style_name, :styles
+
+    # views accessor, array of view paths.
+    def views
+      @views
+    end
+
+    # options accessor, all report options and configuration is stored in this.
+    def options
+      @options
+    end
+
+    class << self
+      # Views setter and accessor.
+      def views(*array)
+        @views ||= ["#{File::dirname(File::expand_path(__FILE__))}/views/"]
+        array ? @views += array : @views
+      end
+     
+      # class level options accessor
+      def options
+        @options ||= {}
+      end
+
+      # class level name accessor & setter
+      # 
+      # Set the name of the report, for example: 
+      #
+      #   name "Orders Report"
+      #
+      def name(value = nil)
+        if value 
+          options[:name] = value
+        else 
+          # TODO: snake_case_the_name
+          options[:name] || self.class.name
+        end
+      end
+      
+      # Accessor used to set the title:
+      #
+      #   title "All orders for the account"
+      #
+      # Or to access the already set title:
+      #
+      #   OrdersReport.title
+      # 
+      #   #=> "All orders for the account"
+      #
+      def title(value = nil)
+        value ? options[:title] = value : options[:title]
+      end
+      
+      # Accessor used to set the sub title:
+      #
+      #   sub_title "All orders for the account"
+      #
+      # Or to access the already set sub title:
+      #
+      #   OrdersReport.sub_title
+      # 
+      #   #=> "All orders for the account"
+      #
+      def sub_title(value = nil)
+        value ? options[:sub_title] = value : options[:sub_title]
+      end
+
+      def styles
+        options[:styles] ||= false
+      end
+
+      def style_name(value = nil)
+        if value
+          options[:style_name] = value
+        elsif options[:style_name].empty?
+          options[:style_name] = self.to_s
+        else
+          options[:style_name]
+        end
+      end
+      
+      # Accessor for the template to use for the report.
+      #
+      # Example:
+      #
+      #   template :orders # => renders orders.html.erb (erb is the default engine)
+      #
+      # Used without argument returns the template set for the report.
+      #
+      #   OrdersReport.template # => :orders
+      #
+      def template(value = nil)
+        value ? options[:template] = value : options[:template]
+      end
+
+      # Accessor for columns
+      #
+      # Pass an array of symbols to define columns on the report
+      #
+      # Example:
+      #
+      #   columns :total, :created_at
+      #
+      # Calling the class method with no arguments will return an array with the defined columns.
+      #
+      # Example:
+      #
+      #   OrdersReport.columns
+      #
+      #   # => [:total, :created_at]
+      #
+      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
+
+      # Return the chart with the specified name, if it exists. nil otherwise.
+      def chart_with_name(name)
+        options[:charts].to_a.detect{ |c| c.name == name.to_sym }
+      end
+
+      # Return an array of charts defined for the report.
+      def charts(object=nil)
+        options[:charts] ||= [] 
+        options[:charts] << object if object
+        options[:charts]
+      end
+
+      # Define a chart for the report
+      #
+      # Example:
+      #   chart :PV_Visits, {:grxl => 'xxxxx'} do
+      #     title "Pageviews and Visits"
+      #     columns [:pageviews, :visits]
+      #     no_labels false
+      #     label_column "recorded_at"
+      #     width "400"
+      #     height "350"
+      #     type "line"
+      #   end
+      # 
+      def chart(name, *chart_options, &block)
+        chart_options = chart_options.shift || {}
+        charts(Chart.configure(name, chart_options, &block))
+      end
+
+      # Method for instanciating a report instance on a set of given records.
+      #
+      # Example:
+      #
+      # OrdersReport.on(@records)
+      #
+      # Where @records is an array of
+      #
+      # * Objects that respond to methods for all columns defined on the report
+      # * Hashes that have keys corresponding to all columns defined on the report
+      #
+      # This will return an instance of the OrdersReport bound to @records
+      #
+      def on(records)
+        new(records, @options)
+      end
+
+      #--
+      # Methods for definining a sub report
+      #def link_column
+      #end
+      #def link_rows
+      #end
+
+    end
+
+    # Instantiate the report on a set of records.
+    #
+    # Example:
+    #
+    # OrdersReport.new(@records)
+    #
+    # options is a set of optional overrides for 
+    #
+    # * views - Used to override the class defined views.
+    # * template - Used to override the class defined template.
+    #
+    def initialize(records, *new_options)
+      new_options  = new_options.shift || {}
+      @records = records
+      @views = []
+      @views << new_options.delete(:views) if new_options[:views]
+      @views += self.class.views
+      @template = new_options.delete(:template) if new_options[:template]
+      @options = self.class.options.merge!(new_options)
+      @options.each_pair do |key,value|
+        if key == "chart"
+          # TODO: erh?
+          self.chart(value[:name],{},value)
+        else
+          instance_variable_set("@#{key}".to_sym, value)
+        end
+      end
+    end
+
+    # Convert an instance of a report bound to a records set to an html view
+    #
+    # Example
+    #
+    # OrdersReport.on(@records).to_html
+    #
+    # [options]
+    #   :engine - one of  :erb, :haml, :csv, :pdf
+    #
+    # Note: CSV & PDF forthcoming.
+    #
+    def to_html(*options)
+      view    = View.new(self)
+      # todo: this is not clean...
+      options = (options.shift || {}).merge!(@options || {})
+      # todo: if rails is loaded set the default engine: dynamicreports::report.default_engine
+      engine  = options.delete(:engine) || @@default_engine
+      view.__send__("#{engine}", options)
+    end
+
+    # Not Implemented Yet
+    def to_csv
+      # TODO: Write csv hook
+    end
+
+    # Not Implemented Yet
+    def to_pdf
+      # TODO: Write pdf hook
+    end
+
+  end
+
+end
+