reportable 1.0.0

data/lib/saulabs/reportable/report_cache.rb

@@ -0,0 +1,163 @@
+module Saulabs
+
+  module Reportable
+
+    # The +ReportCache+ class is a regular +ActiveRecord+ model and represents cached results for single {Saulabs::Reportable::ReportingPeriod}s.
+    # +ReportCache+ instances are identified by the combination of +model_name+, +report_name+, +grouping+, +aggregation+ and +reporting_period+.
+    #
+    class ReportCache < ActiveRecord::Base
+
+      set_table_name :reportable_cache
+
+      self.skip_time_zone_conversion_for_attributes = [:reporting_period]
+
+      # Clears the cache for the specified +klass+ and +report+
+      #
+      # @param [Class] klass
+      #   the model the report to clear the cache for works on
+      # @param [Symbol] report
+      #   the name of the report to clear the cache for
+      #
+      # @example Clearing the cache for a report
+      #
+      #   class User < ActiveRecord::Base
+      #     reportable :registrations
+      #   end
+      #
+      #   Saulabs::Reportable::ReportCache.clear_for(User, :registrations)
+      #
+      def self.clear_for(klass, report)
+        self.delete_all(:conditions => {
+          :model_name  => klass.name,
+          :report_name => report.to_s
+        })
+      end
+
+      # Processes the report using the respective cache.
+      #
+      # @param [Saulabe::Reportable::Report] report
+      #   the report to process
+      # @param [Hash] options
+      #   options for the report
+      #
+      # @option options [Symbol] :grouping (:day)
+      #   the period records are grouped in (+:hour+, +:day+, +:week+, +:month+); <b>Beware that <tt>reportable</tt> treats weeks as starting on monday!</b>
+      # @option options [Fixnum] :limit (100)
+      #   the number of reporting periods to get (see +:grouping+)
+      # @option options [Hash] :conditions ({})
+      #   conditions like in +ActiveRecord::Base#find+; only records that match these conditions are reported;
+      # @option options [Boolean] :live_data (false)
+      #   specifies whether data for the current reporting period is to be read; <b>if +:live_data+ is +true+, you will experience a performance hit since the request cannot be satisfied from the cache alone</b>
+      # @option options [DateTime, Boolean] :end_date (false)
+      #   when specified, the report will only include data for the +:limit+ reporting periods until this date.
+      #
+      # @return [Array<Array<DateTime, Float>>]
+      #   the result of the report as pairs of {DateTime}s and {Float}s
+      #
+      def self.process(report, options, &block)
+        raise ArgumentError.new('A block must be given') unless block_given?
+        self.transaction do
+          cached_data = read_cached_data(report, options)
+          new_data = read_new_data(cached_data, options, &block)
+          prepare_result(new_data, cached_data, report, options)
+        end
+      end
+
+      private
+
+        def self.prepare_result(new_data, cached_data, report, options)
+          new_data = new_data.map { |data| [ReportingPeriod.from_db_string(options[:grouping], data[0]), data[1]] }
+          cached_data.map! { |cached| [ReportingPeriod.new(options[:grouping], cached.reporting_period), cached.value] }
+          current_reporting_period = ReportingPeriod.new(options[:grouping])
+          reporting_period = get_first_reporting_period(options)
+          result = []
+          while reporting_period < (options[:end_date] ? ReportingPeriod.new(options[:grouping], options[:end_date]).next : current_reporting_period)
+            if cached = cached_data.find { |cached| reporting_period == cached[0] }
+              result << [cached[0].date_time, cached[1]]
+            else
+              new_cached = build_cached_data(report, options[:grouping], options[:conditions], reporting_period, find_value(new_data, reporting_period))
+              new_cached.save!
+              result << [reporting_period.date_time, new_cached.value]
+            end
+            reporting_period = reporting_period.next
+          end
+          if options[:live_data]
+            result << [current_reporting_period.date_time, find_value(new_data, current_reporting_period)]
+          end
+          result
+        end
+
+        def self.find_value(data, reporting_period)
+          data = data.detect { |d| d[0] == reporting_period }
+          data ? data[1] : 0.0
+        end
+
+        def self.build_cached_data(report, grouping, condition, reporting_period, value)
+          self.new(
+            :model_name       => report.klass.to_s,
+            :report_name      => report.name.to_s,
+            :grouping         => grouping.identifier.to_s,
+            :aggregation      => report.aggregation.to_s,
+            :condition        => condition.to_s,
+            :reporting_period => reporting_period.date_time,
+            :value            => value
+          )
+        end
+
+        def self.read_cached_data(report, options)
+          conditions = [
+            'model_name = ? AND report_name = ? AND grouping = ? AND aggregation = ? AND `condition` = ?',
+            report.klass.to_s,
+            report.name.to_s,
+            options[:grouping].identifier.to_s,
+            report.aggregation.to_s,
+            options[:conditions].to_s
+          ]
+          first_reporting_period = get_first_reporting_period(options)
+          last_reporting_period = get_last_reporting_period(options)
+          if last_reporting_period
+            conditions.first << ' AND reporting_period BETWEEN ? AND ?'
+            conditions << first_reporting_period.date_time
+            conditions << last_reporting_period.date_time
+          else
+            conditions.first << ' AND reporting_period >= ?'
+            conditions << first_reporting_period.date_time
+          end
+          self.all(
+            :conditions => conditions,
+            :limit      => options[:limit],
+            :order      => 'reporting_period ASC'
+          )
+        end
+
+        def self.read_new_data(cached_data, options, &block)
+          if !options[:live_data] && cached_data.length == options[:limit]
+            []
+          else
+            first_reporting_period_to_read = if cached_data.length < options[:limit]
+              get_first_reporting_period(options)
+            else
+              ReportingPeriod.new(options[:grouping], cached_data.last.reporting_period).next
+            end
+            last_reporting_period_to_read = options[:end_date] ? ReportingPeriod.new(options[:grouping], options[:end_date]).last_date_time : nil
+            yield(first_reporting_period_to_read.date_time, last_reporting_period_to_read)
+          end
+        end
+
+        def self.get_first_reporting_period(options)
+          if options[:end_date]
+            ReportingPeriod.first(options[:grouping], options[:limit] - 1, options[:end_date])
+          else
+            ReportingPeriod.first(options[:grouping], options[:limit])
+          end
+        end
+
+        def self.get_last_reporting_period(options)
+          return ReportingPeriod.new(options[:grouping], options[:end_date]) if options[:end_date]
+        end
+
+    end
+
+  end
+
+end

data/lib/saulabs/reportable/reporting_period.rb

@@ -0,0 +1,181 @@
+module Saulabs
+
+  module Reportable
+
+    # A reporting period is a specific hour or a specific day etc. depending on the used {Saulabs::Reportable::Grouping}.
+    #
+    class ReportingPeriod
+
+      # The actual +DateTime the reporting period represents
+      #
+      attr_reader :date_time
+
+      # The {Saulabs::Reportable::Grouping} of the reporting period
+      #
+      attr_reader :grouping
+
+      # Initializes a new reporting period.
+      #
+      # @param [Saulabs::Reportable::Grouping] grouping
+      #   the grouping the generate the reporting period for
+      # @param [DateTime] date_time
+      #   the +DateTime+ to generate the reporting period for
+      #
+      def initialize(grouping, date_time = nil)
+        @grouping  = grouping
+        @date_time = parse_date_time(date_time || DateTime.now)
+      end
+
+      # Gets a reporting period relative to the current one.
+      #
+      # @param [Fixnum] offset
+      #   the offset to get the reporting period for
+      #
+      # @return [Saulabs::Reportable::ReportingPeriod]
+      #   the reporting period relative by offset to the current one
+      #
+      # @example Getting the reporting period one week later
+      #
+      #   reporting_period = Saulabs::Reportable::ReportingPeriod.new(:week, DateTime.now)
+      #   next_week = reporting_period.offset(1)
+      #
+      def offset(offset)
+        self.class.new(@grouping, @date_time + offset.send(@grouping.identifier))
+      end
+
+      # Gets the first reporting period for a grouping and a limit (optionally relative to and end date).
+      #
+      # @param [Saulabs::ReportingPeriod::Grouping] grouping
+      #   the grouping to get the first reporting period for
+      # @param [Fixnum] limit
+      #   the limit to get the first reporting period for
+      # @param [DateTime] end_date
+      #   the end date to get the first reporting period for (the first reporting period is then +end_date+ - +limit+ * +grouping+)
+      #
+      # @return [Saulabs::Reportable::ReportingPeriod]
+      #   the first reporting period for the grouping, limit and optionally end date
+      #
+      def self.first(grouping, limit, end_date = nil)
+        self.new(grouping, end_date).offset(-limit)
+      end
+
+      # Gets a reporting period from a DB date string.
+      #
+      # @param [Saulabs::Reportable::Grouping] grouping
+      #   the grouping to get the reporting period for
+      # @param [String] db_string
+      #   the DB string to parse and get the reporting period for
+      #
+      # @return [Saulabs::Reportable::ReportingPeriod]
+      #   the reporting period for the {Saulabs::Reportable::Grouping} as parsed from the db string
+      #
+      def self.from_db_string(grouping, db_string)
+        parts = grouping.date_parts_from_db_string(db_string)
+        result = case grouping.identifier
+          when :hour
+            self.new(grouping, DateTime.new(parts[0], parts[1], parts[2], parts[3], 0, 0))
+          when :day
+            self.new(grouping, Date.new(parts[0], parts[1], parts[2]))
+          when :week
+            self.new(grouping, Date.commercial(parts[0], parts[1], 1))
+          when :month
+            self.new(grouping, Date.new(parts[0], parts[1], 1))
+        end
+        result
+      end
+
+      # Gets the next reporting period.
+      #
+      # @return [Saulabs::Reportable::ReportingPeriod]
+      #   the reporting period after the current one
+      #
+      def next
+        self.offset(1)
+      end
+
+      # Gets the previous reporting period.
+      #
+      # @return [Saulabs::Reportable::ReportingPeriod]
+      #   the reporting period before the current one
+      #
+      def previous
+        self.offset(-1)
+      end
+
+      # Gets whether the reporting period +other+ is equal to the current one.
+      #
+      # @param [Saulabs::Reportable::ReportingPeriod] other
+      #   the reporting period to check for whether it is equal to the current one
+      #
+      # @return [Boolean]
+      #   true if +other+ is equal to the current reporting period, false otherwise
+      #
+      def ==(other)
+        if other.is_a?(Saulabs::Reportable::ReportingPeriod)
+          @date_time.to_s == other.date_time.to_s && @grouping.identifier.to_s == other.grouping.identifier.to_s
+        elsif other.is_a?(Time) || other.is_a?(DateTime)
+          @date_time == parse_date_time(other)
+        else
+          raise ArgumentError.new("Can only compare instances of #{self.class.name}")
+        end
+      end
+
+      # Gets whether the reporting period +other+ is smaller to the current one.
+      #
+      # @param [Saulabs::Reportable::ReportingPeriod] other
+      #   the reporting period to check for whether it is smaller to the current one
+      #
+      # @return [Boolean]
+      #   true if +other+ is smaller to the current reporting period, false otherwise
+      #
+      def <(other)
+        if other.is_a?(Saulabs::Reportable::ReportingPeriod)
+          return @date_time < other.date_time
+        elsif other.is_a?(Time) || other.is_a?(DateTime)
+          @date_time < parse_date_time(other)
+        else
+          raise ArgumentError.new("Can only compare instances of #{self.class.name}")
+        end
+      end
+
+      # Gets the latest point in time that is included the reporting period. The latest point in time included in a reporting period
+      # for grouping hour would be that hour and 59 minutes and 59 seconds.
+      #
+      # @return [DateTime]
+      #   the latest point in time that is included in the reporting period
+      #
+      def last_date_time
+        case @grouping.identifier
+          when :hour
+            DateTime.new(@date_time.year, @date_time.month, @date_time.day, @date_time.hour, 59, 59)
+          when :day
+            DateTime.new(@date_time.year, @date_time.month, @date_time.day, 23, 59, 59)
+          when :week
+            date_time = (@date_time - @date_time.wday.days) + 7.days
+            Date.new(date_time.year, date_time.month, date_time.day)
+          when :month
+            Date.new(@date_time.year, @date_time.month, (Date.new(@date_time.year, 12, 31) << (12 - @date_time.month)).day)
+        end
+      end
+
+      private
+
+        def parse_date_time(date_time)
+          case @grouping.identifier
+            when :hour
+              DateTime.new(date_time.year, date_time.month, date_time.day, date_time.hour)
+            when :day
+              date_time.to_date
+            when :week
+              date_time = (date_time - date_time.wday.days) + 1.day
+              Date.new(date_time.year, date_time.month, date_time.day)
+            when :month
+              Date.new(date_time.year, date_time.month, 1)
+          end
+        end
+
+    end
+
+  end
+
+end

data/lib/saulabs/reportable/sparkline_tag_helper.rb

@@ -0,0 +1,62 @@
+module Saulabs
+
+  module Reportable
+
+    module SparklineTagHelper
+
+      # Renders a sparkline with the given data.
+      #
+      # @param [Array<Array<DateTime, Float>>] data
+      #   an array of report data as returned by {Saulabs::Reportable::Report#run}
+      # @param [Hash] options
+      #   options for the sparkline
+      #
+      # @option options [Fixnum] :width (300)
+      #   the width of the generated image
+      # @option options [Fixnum] :height (34)
+      #   the height of the generated image
+      # @option options [String] :line_color ('0077cc')
+      #   the line color of the generated image
+      # @option options [String] :fill_color ('e6f2fa')
+      #   the fill color of the generated image
+      # @option options [Array<Symbol>] :labels ([])
+      #   the axes to render lables for (Array of +:x+, +:y+, +:r+, +:t+; this is x axis, y axis, right, top)
+      # @option options [String] :alt ('')
+      #   the alt attribute for the generated image
+      # @option options [String] :title ('')
+      #   the title attribute for the generated image
+      #
+      # @return [String]
+      #   an image tag showing a sparkline for the passed +data+
+      #
+      # @example Rendering a sparkline tag for report data
+      #
+      #   <%= sparkline_tag(User.registrations_report, :width => 200, :height => 100, :color => '000') %>
+      #
+      def sparkline_tag(data, options = {})
+        options.reverse_merge!({ :width => 300, :height => 34, :line_color => '0077cc', :fill_color => 'e6f2fa', :labels => [], :alt => '', :title => '' })
+        data = data.collect { |d| d[1] }
+        labels = ''
+        unless options[:labels].empty?
+          chxr = {}
+          options[:labels].each_with_index do |l, i|
+            chxr[l] = "#{i}," + ([:x, :t].include?(l) ? "0,#{data.length}" : "#{[data.min, 0].min},#{data.max}")
+          end
+          labels = "&chxt=#{options[:labels].map(&:to_s).join(',')}&chxr=#{options[:labels].collect{|l| chxr[l]}.join('|')}"
+        end
+        title = ''
+        unless options[:title].empty?
+          title = "&chtt=#{options[:title]}"
+        end
+        image_tag(
+          "http://chart.apis.google.com/chart?cht=ls&chs=#{options[:width]}x#{options[:height]}&chd=t:#{data.join(',')}&chco=#{options[:line_color]}&chm=B,#{options[:fill_color]},0,0,0&chls=1,0,0&chds=#{data.min},#{data.max}#{labels}#{title}",
+          :alt   => options[:alt],
+          :title => options[:title]
+        )
+      end
+
+    end
+
+  end
+
+end

data/rails/init.rb

@@ -0,0 +1,9 @@
+require 'saulabs/reportable'
+
+ActiveRecord::Base.class_eval do
+  include Saulabs::Reportable
+end
+
+ActionView::Base.class_eval do
+  include Saulabs::Reportable::SparklineTagHelper
+end

data/spec/boot.rb

@@ -0,0 +1,25 @@
+plugin_root = File.join(File.dirname(__FILE__), '..')
+
+gem 'rails'
+require 'active_record'
+require 'active_support'
+require 'action_controller'
+require 'action_view'
+
+$:.unshift "#{plugin_root}/lib"
+
+RAILS_ROOT = File.expand_path(File.dirname(__FILE__) + '/../')
+Rails::Initializer.run(:set_load_path)
+Rails::Initializer.run(:set_autoload_paths)
+Rails::Initializer.run(:initialize_time_zone) do |config|
+  config.time_zone = 'Pacific Time (US & Canada)'
+end
+
+require File.join(File.dirname(__FILE__), '..', 'rails', 'init.rb')
+
+FileUtils.mkdir_p File.join(File.dirname(__FILE__), 'log')
+ActiveRecord::Base.logger = Logger.new(File.join(File.dirname(__FILE__), 'log', 'spec.log'))
+
+databases = YAML::load(IO.read(File.join(File.dirname(__FILE__), 'db', 'database.yml')))
+ActiveRecord::Base.establish_connection(databases['sqlite3'])
+load(File.join(File.dirname(__FILE__), 'db', 'schema.rb'))

data/spec/classes/cumulated_report_spec.rb

@@ -0,0 +1,169 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper')
+
+describe Saulabs::Reportable::CumulatedReport do
+
+  before do
+    @report = Saulabs::Reportable::CumulatedReport.new(User, :cumulated_registrations)
+  end
+
+  describe '#run' do
+
+    it 'should cumulate the data' do
+      @report.should_receive(:cumulate).once
+
+      @report.run
+    end
+
+    it 'should return an array of the same length as the specified limit when :live_data is false' do
+      @report = Saulabs::Reportable::CumulatedReport.new(User, :cumulated_registrations, :limit => 10, :live_data => false)
+
+      @report.run.length.should == 10
+    end
+
+    it 'should return an array of the same length as the specified limit + 1 when :live_data is true' do
+      @report = Saulabs::Reportable::CumulatedReport.new(User, :cumulated_registrations, :limit => 10, :live_data => true)
+
+      @report.run.length.should == 11
+    end
+    
+    for grouping in [:hour, :day, :week, :month] do
+
+      describe "for grouping #{grouping.to_s}" do
+
+        [true, false].each do |live_data|
+
+          describe "with :live_data = #{live_data}" do
+
+            before(:all) do
+              User.delete_all
+              User.create!(:login => 'test 1', :created_at => Time.now,                    :profile_visits => 2)
+              User.create!(:login => 'test 2', :created_at => Time.now - 1.send(grouping), :profile_visits => 1)
+              User.create!(:login => 'test 3', :created_at => Time.now - 3.send(grouping), :profile_visits => 2)
+              User.create!(:login => 'test 4', :created_at => Time.now - 3.send(grouping), :profile_visits => 3)
+            end
+
+            describe 'the returned result' do
+
+              before do
+                @grouping = Saulabs::Reportable::Grouping.new(grouping)
+                @report = Saulabs::Reportable::CumulatedReport.new(User, :cumulated_registrations,
+                  :grouping  => grouping,
+                  :limit     => 10,
+                  :live_data => live_data
+                )
+                @result = @report.run
+              end
+
+              it "should be an array starting reporting period (Time.now - limit.#{grouping.to_s})" do
+                @result.first[0].should == Saulabs::Reportable::ReportingPeriod.new(@grouping, Time.now - 10.send(grouping)).date_time
+              end
+
+              if live_data
+                it "should be data ending with the current reporting period" do
+                  @result.last[0].should == Saulabs::Reportable::ReportingPeriod.new(@grouping).date_time
+                end
+              else
+                it "should be data ending with the reporting period before the current" do
+                  @result.last[0].should == Saulabs::Reportable::ReportingPeriod.new(@grouping).previous.date_time
+                end
+              end
+
+            end
+
+            it 'should return correct data for aggregation :count' do
+              @report = Saulabs::Reportable::CumulatedReport.new(User, :registrations,
+                :aggregation => :count,
+                :grouping    => grouping,
+                :limit       => 10,
+                :live_data   => live_data
+              )
+              result = @report.run
+
+              result[10][1].should == 4.0 if live_data
+              result[9][1].should  == 3.0
+              result[8][1].should  == 2.0
+              result[7][1].should  == 2.0
+              result[6][1].should  == 0.0
+            end
+
+            it 'should return correct data for aggregation :sum' do
+              @report = Saulabs::Reportable::CumulatedReport.new(User, :registrations,
+                :aggregation  => :sum,
+                :grouping     => grouping,
+                :value_column => :profile_visits,
+                :limit        => 10,
+                :live_data    => live_data
+              )
+              result = @report.run()
+
+              result[10][1].should == 8.0 if live_data
+              result[9][1].should  == 6.0
+              result[8][1].should  == 5.0
+              result[7][1].should  == 5.0
+              result[6][1].should  == 0.0
+            end
+
+            it 'should return correct data for aggregation :count when custom conditions are specified' do
+              @report = Saulabs::Reportable::CumulatedReport.new(User, :registrations,
+                :aggregation => :count,
+                :grouping    => grouping,
+                :limit       => 10,
+                :live_data   => live_data
+              )
+              result = @report.run(:conditions => ['login IN (?)', ['test 1', 'test 2', 'test 4']])
+
+              result[10][1].should == 3.0 if live_data
+              result[9][1].should  == 2.0
+              result[8][1].should  == 1.0
+              result[7][1].should  == 1.0
+              result[6][1].should  == 0.0
+            end
+
+            it 'should return correct data for aggregation :sum when custom conditions are specified' do
+              @report = Saulabs::Reportable::CumulatedReport.new(User, :registrations,
+                :aggregation  => :sum,
+                :grouping     => grouping,
+                :value_column => :profile_visits,
+                :limit        => 10,
+                :live_data    => live_data
+              )
+              result = @report.run(:conditions => ['login IN (?)', ['test 1', 'test 2', 'test 4']])
+
+              result[10][1].should == 6.0 if live_data
+              result[9][1].should  == 4.0
+              result[8][1].should  == 3.0
+              result[7][1].should  == 3.0
+              result[6][1].should  == 0.0
+            end
+
+          end
+
+          after(:all) do
+            User.destroy_all
+          end
+
+        end
+
+      end
+
+    end
+
+    after(:each) do
+      Saulabs::Reportable::ReportCache.destroy_all
+    end
+
+  end
+
+  describe '#cumulate' do
+
+    it 'should correctly cumulate the given data' do
+      first = (Time.now - 1.week).to_s
+      second = Time.now.to_s
+      data = [[first, 1], [second, 2]]
+
+      @report.send(:cumulate, data, @report.send(:options_for_run, {})).should == [[first, 1.0], [second, 3.0]]
+    end
+
+  end
+
+end