report_cat 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bb5df8435727e3a79d5e7fb487a3cb59dc51ee05
+  data.tar.gz: 17cbef82f87e179e82f53d7518a8452eab81879d
+SHA512:
+  metadata.gz: 832119ce0f907982113db1b246dc796ad1ad0b7efbbcdfd0b94a8ab106e135508f34e8381c66534550927ccab13298ba5e53ef92d224c7dd46538fff80f9ed50
+  data.tar.gz: 10ef1443c4601eaa121cf6af0e5dd8348ed72f26eeeb43c4553eb262929a0a83f693827b280ce2e33aa904787576820a33b51d0ec339660f10a2ce76471b53ff

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,147 @@
+[![Build Status](https://travis-ci.org/schrodingersbox/report_cat.svg?branch=master)](https://travis-ci.org/schrodingersbox/report_cat)
+[![Coverage Status](https://coveralls.io/repos/schrodingersbox/report_cat/badge.png?branch=master)](https://coveralls.io/r/schrodingersbox/report_cat?branch=master)
+[![Code Climate](https://codeclimate.com/github/schrodingersbox/report_cat.png)](https://codeclimate.com/github/schrodingersbox/report_cat)
+[![Dependency Status](https://gemnasium.com/schrodingersbox/report_cat.png)](https://gemnasium.com/schrodingersbox/report_cat)
+[![Gem Version](https://badge.fury.io/rb/report_cat.png)](http://badge.fury.io/rb/report_cat)
+
+# schrodingersbox/report_cat README
+
+A Rails engine to generate simple web-based reports with charts along with Rspec matchers for testing them.
+
+It currently supports:
+
+ * Simple reports
+ * Date range reports
+ * Date range cohort reports
+
+It provides the following matchers:
+
+ * have_chart
+ * have_column
+ * have_param
+
+ Report subclasses will automatically appear under the ReportCat index controller,
+ allowing you to add a new report with custom form, columns and charts by just adding a single ReportCat::Report subclass.
+
+## Getting Started
+
+1. Add this to your `Gemfile` and `bundle install`
+
+		gem 'report_cat', :git => 'https://github.com/schrodingersbox/report_cat.git'
+
+2. Add this to your `config/routes.rb`
+
+		mount ReportCat::Engine => '/report_cat'
+
+3. Install and run migrations
+
+        rake report_cat:install:migrations
+        rake db:migrate
+
+4. Restart your Rails server
+
+5.  Visit http://yourapp/report_cat in a browser
+
+## Background
+
+ _TODO: UML goes here_
+
+### Report Types
+
+
+
+### Building a report
+
+
+
+### Adding Params
+
+add_param( name, type, value = nil, options = {} )
+
+types = :check_box, :date, :select, :text_field
+options = :hidden, :values
+
+### Adding Columns
+
+add_column( name, type, options = {} )
+
+types = :date, :float, :integer, :moving_average, :ratio, :report, :string
+options = :hidden, :sql
+
+### Adding Charts
+
+add_chart( name, type, label, values, options = {} )
+
+types = :area, :bar, :column, :line, :pie
+
+## How To
+
+### Add New Reports
+
+You can place new reports anywhere you like, but `app/reports` is the recommended location.
+
+1.  Add the following to `config/application.rb`
+
+    	Dir[Rails.root + 'app/reports/**/*.rb'].each { |path| require path }
+
+2.  Create a subclass of `ReportCat::Core::Report`, `ReportCat::Report::DateRangeReport` or `ReportCat::Report::CohortReport`
+
+    class MyReport << ReportCat::Report::DateRangeReport
+
+        def initialize
+            super( :name => :my_report, :from => :users, :order_by => 'users.id asc' )
+            add_column( :total, :integer, :sql => 'count( users.id )' )
+            add_chart( :chart, :line, :start_date, :total )
+        end
+    end
+
+3.  Or build one on the fly
+
+    report = ReportCat::Core::DateRangeReport.new( :name => :my_report, :from => :users, :order_by => 'users.id asc' )
+    report.add_column( :total, :integer, :sql => 'count( users.id )' )
+    report.add_chart( :chart, :line, :start_date, :total )
+    report.generate
+    report.rows.each { |row| puts "Total = #{row[0]} }
+
+
+### Reload Reports In Development Mode
+
+Add the following to ApplicationController:
+
+      before_filter :require_reports if Rails.env.development?
+
+      def require_reports
+        silence_warnings do
+          Dir[Rails.root + 'app/reports/**/*.rb'].each { |path| require_dependency path }
+        end
+      end
+
+NOTE: This is a rank hack and causes some weird behavior if you change a report's base class or override methods
+without restarting the server.  Please let me know if you find a better way to dynamically force reload in development.
+
+## Reference
+
+ * [Getting Started with Engines](http://edgeguides.rubyonrails.org/engines.html)
+ * [Testing Rails Engines With Rspec](http://whilefalse.net/2012/01/25/testing-rails-engines-rspec/)
+ * [How do I write a Rails 3.1 engine controller test in rspec?](http://stackoverflow.com/questions/5200654/how-do-i-write-a-rails-3-1-engine-controller-test-in-rspec)
+ * [Best practice for specifying dependencies that cannot be put in gemspec?](https://groups.google.com/forum/?fromgroups=#!topic/ruby-bundler/U7FMRAl3nJE)
+ * [Clarifying the Roles of the .gemspec and Gemfile](http://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/)
+ * [The Semi-Isolated Rails Engine](http://bibwild.wordpress.com/2012/05/10/the-semi-isolated-rails-engine/)
+ * [Shoulda](https://github.com/thoughtbot/shoulda-matchers)
+
+# TODO
+
+ * Ability to register "anonymous" reports of generic Report classes with factory
+
+ * Fix pending spec due to Travis problem
+
+ * Add a AnnotatedReport class - base report left joined to an "annotation" report
+
+ * Replace Google Charts with D3
+ * Improve Column modelling WRT calculated ratios and moving averages
+
+ * Document
+   * How To
+   * Background
+     * UML
+

data/Rakefile

@@ -0,0 +1,24 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ReportCat'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+load 'tasks/spec_cat.rake'

data/app/assets/javascripts/report_cat/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/app/assets/stylesheets/report_cat/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/app/controllers/report_cat/reports_controller.rb

@@ -0,0 +1,43 @@
+module ReportCat
+  class ReportsController < ApplicationController
+
+    layout :set_layout
+
+    before_filter :_authenticate!
+    before_filter :_authorize!
+    before_filter :set_reports
+
+    def index
+    end
+
+    def show
+      @report = @reports[ params[ :id ] ]
+      @report.back = params[ :back ]
+      @report.generate( params )
+
+      respond_to do |format|
+        format.html
+        format.csv { render :text => @report.to_csv, :content_type => 'text/csv' }
+      end
+    end
+
+  protected
+
+    def set_reports
+      @reports = ReportCat.reports
+    end
+
+    def set_layout
+      return ReportCat.config.layout
+    end
+
+    def _authenticate!
+      instance_eval( &ReportCat.config.authenticate_with )
+    end
+
+    def _authorize!
+      instance_eval( &ReportCat.config.authorize_with )
+    end
+
+  end
+end

data/app/helpers/report_cat/reports_helper.rb

@@ -0,0 +1,132 @@
+module ReportCat
+  module ReportsHelper
+
+    def report_back( report )
+      if report.back
+        report_link( report.back )
+      else
+        link_to report_title, root_path
+      end
+    end
+
+    def report_chart_name( report, chart )
+      t( chart.name.to_sym, :scope => [ :report_cat, :charts ] )
+    end
+
+
+    def report_chart_partial
+      render :partial => 'report_cat/reports/google_charts'
+    end
+
+    def report_charts( report )
+      output = ''
+
+      report.charts.each do |chart|
+        output += content_tag( :div, '', :class => :chart,
+                           :name => report_chart_name( report, chart ),
+                           :chart => chart.type,
+                           :columns => chart.columns( report ),
+                           :data => chart.data( report ),
+                           :options => chart.options.to_json )
+      end
+
+      output
+    end
+
+    def report_count( report )
+      t( :count, :scope => :report_cat, :count => report.rows.count )
+    end
+
+    def report_csv_link( report )
+      link_to t( :export_as_csv, :scope => :report_cat ), :params => params.merge( :format => :csv )
+    end
+
+    def report_description( report )
+      t( :description, :scope => [ :report_cat, :instances, report.name.to_sym ] )
+    end
+
+    def report_form( report )
+      form_tag report_path( report.name ), :method => :get do
+        @report.params.each do |param|
+          concat report_form_param( param )
+        end
+        concat submit_tag( t( :report, :scope => :report_cat ) )
+      end
+    end
+
+    def report_form_param( param )
+      name =  t( param.name, :scope => [ :report_cat, :params ] )
+      if param.options[ :hidden ]
+        return report_param( param )
+      else
+        return content_tag( :div, label_tag( name ) + report_param( param ) )
+      end
+    end
+
+    def report_link( attributes )
+      attributes = attributes.dup
+      attributes[ :id ] = name = attributes.delete( :name )
+      name = t( :name, :scope => [ :report_cat, :instances, name ] )
+      path = defined?( report_cat ) ? report_cat.report_path( attributes ) : report_path( attributes )
+      link_to name, path
+    end
+
+    def report_list( reports )
+      content_tag( :ul ) do
+        reports.values.sort { |a,b| a.name <=> b.name }.each do |report|
+          unless ReportCat.config.excludes.include?( report.name.to_sym )
+            attributes = { :id => report.name }
+            path = defined?( report_cat ) ? report_cat.report_path( attributes ) : report_path( attributes )
+            link = link_to( report_name( report ), path)
+            concat content_tag( :li, link + ' - ' + report_description( report ) )
+          end
+        end
+      end
+    end
+
+    def report_name( report )
+      t( :name, :scope => [ :report_cat, :instances, report.name.to_sym ] )
+    end
+
+    def report_param( param )
+      return hidden_field_tag( param.name, param.value ) if param.options[ :hidden ]
+
+      case param.type
+        when :check_box  then return check_box_tag( param.name, '1', param.value )
+        when :date       then return select_date( param.value, :prefix => param.name )
+        when :select     then return select_tag( param.name, options_for_select( param.options[ :values ], param.value ) )
+        when :text_field then return text_field_tag( param.name, param.value )
+        else
+          raise "Unknown param: #{param.type}"
+      end
+    end
+
+    def report_table( report )
+      content_tag( :table, :border => 1 ) do
+        output = content_tag( :tr ) do
+          report.columns.each do |column|
+            concat content_tag( :th, column.name.to_s ) unless column.options[ :hidden ]
+          end
+        end
+
+        report.rows.each do |row|
+          output += content_tag( :tr ) do
+            row.each_index do |index|
+              column = report.columns[ index ]
+              data = row[ index ]
+              data = report_link( data ) if ( column.type == :report )
+              concat content_tag( :td, data ) unless column.options[ :hidden ]
+            end
+          end
+        end
+
+        output
+      end
+    end
+
+    def report_title
+      t :reports, :scope => :report_cat
+    end
+
+  end
+end

data/app/models/report_cat/date_range.rb

@@ -0,0 +1,94 @@
+module ReportCat
+  class DateRange < ActiveRecord::Base
+
+    def self.range( period, start_date, stop_date )
+      sql = [
+          sql_intersect( start_date, stop_date ),
+          sql_period( period )
+      ].join( ' and ' )
+
+      DateRange.where( sql ).order( "#{table_name}.start_date asc" )
+    end
+
+    #############################################################################
+    # ::generate
+
+    def self.generate( period, start_date, stop_date )
+      date_ranges = {}
+      range( period, start_date, stop_date ).each { |d| date_ranges[ d.start_date ] = true }
+
+      iterate( period, start_date, stop_date ) do |start_date, stop_date|
+        unless date_ranges[ start_date ]
+          DateRange.create( :period => period, :start_date => start_date, :stop_date => stop_date )
+        end
+      end
+    end
+
+    #############################################################################
+    # ::iterate
+
+    def self.iterate( period, start_date, stop_date )
+      start_date = Date.parse( start_date ) if start_date.is_a?( String )
+      stop_date = Date.parse( stop_date ) if stop_date.is_a?( String )
+
+      while( start_date <= stop_date )
+        case period
+          when :daily
+            next_date = start_date
+          when :weekly
+            start_date = start_date.beginning_of_week
+            next_date  = start_date.end_of_week
+          when :monthly
+            start_date = start_date.beginning_of_month
+            next_date  = start_date.end_of_month
+          when :quarterly
+            start_date = start_date.beginning_of_quarter
+            next_date  = start_date.end_of_quarter
+          when :yearly
+            start_date = start_date.beginning_of_year
+            next_date  = start_date.end_of_year
+          else
+            raise "Unknown date range: #{period}"
+        end
+
+        yield start_date, next_date
+
+        start_date = next_date + 1
+      end
+    end
+
+    #############################################################################
+    # ::join_*
+
+    def self.join_to( table, column )
+      "join #{table} on date( #{table}.#{column} ) between #{table_name}.start_date and #{table_name}.stop_date"
+    end
+
+    def self.join_before( table, column )
+      "join #{table} on date( #{table}.#{column} ) <= #{table_name}.stop_date"
+    end
+
+    def self.join_after( table, column )
+      "join #{table} on date( #{table}.#{column} ) > #{table_name}.stop_date"
+    end
+
+    #############################################################################
+    # ::sql_*
+
+    def self.sql_intersect( start_date, stop_date )
+      sql =<<-EOSQL
+        (
+          #{table_name}.start_date between '#{start_date}' and '#{stop_date}'
+          or
+          '#{start_date}' between #{table_name}.start_date and #{table_name}.stop_date
+        )
+      EOSQL
+    end
+
+    def self.sql_period( period )
+      "#{table_name}.period = '#{period}'"
+    end
+
+  end
+end
+

data/app/views/report_cat/reports/_google_charts.html.erb

@@ -0,0 +1,61 @@
+<%= javascript_include_tag 'https://www.google.com/jsapi' %>
+<%= javascript_include_tag 'https://ajax.googleapis.com/ajax/libs/jquery/1.4.3/jquery.min.js' %>
+
+<script type="text/javascript">
+  google.load('visualization', '1', {'packages':['corechart']});
+  google.setOnLoadCallback(drawCharts);
+
+  function makeDataTable( element ) {
+    var columns = eval( element.getAttribute( 'columns' ) );
+    var data = eval( element.getAttribute( 'data' ) );
+    var dataTable = new google.visualization.DataTable();
+
+    for( i = 0; i < columns.length; i++ ) {
+      dataTable.addColumn( columns[ i ][ 0 ], columns[ i ][ 1 ] );
+    }
+
+    dataTable.addRows( data  );
+
+    return dataTable;
+  }
+
+  function makeChart( index, element ) {
+    var dataTable =  makeDataTable( element );
+    var customOptions = eval( element.getAttribute( 'options' ) );
+    var defaultOptions = { is3D: true, title: element.getAttribute( 'name' ) };
+    var chart = undefined;
+
+    switch( element.getAttribute( 'chart' ) ) {
+      case 'area':
+        chart = new google.visualization.AreaChart( element );
+        break;
+
+      case 'bar':
+        chart = new google.visualization.BarChart( element );
+        break;
+
+      case 'column':
+        chart = new google.visualization.ColumnChart( element );
+        break;
+
+      case 'line':
+        chart = new google.visualization.LineChart( element );
+        break;
+
+      case 'pie':
+        chart = new google.visualization.PieChart( element );
+        break;
+    }
+
+    if ( chart != undefined ) {
+      jQuery.extend( true, defaultOptions, customOptions );
+      chart.draw( dataTable, defaultOptions );
+    }
+  }
+
+  function drawCharts() {
+    $('[chart]').each( makeChart );
+   }
+
+
+</script>

data/app/views/report_cat/reports/index.html.erb

@@ -0,0 +1,2 @@
+<h1><%= report_title %></h1>
+<%= report_list( @reports ) %>

data/app/views/report_cat/reports/show.html.erb

@@ -0,0 +1,15 @@
+<p><%= report_back( @report ) %></p>
+
+<h1><%= report_name( @report ) %></h1>
+<%= report_description( @report ) %>
+
+<p><%= report_form( @report ) %></p>
+
+<p><%= raw report_charts( @report ) %></p>
+<p><%= report_chart_partial %></p>
+
+<p><%= report_count( @report ) %></p>
+<p><%= report_table( @report ) %></p>
+<p><%= report_csv_link( @report ) %></p>
+
+

data/config/locales/en.yml

@@ -0,0 +1,26 @@
+en:
+  report_cat:
+    back: Back
+    count: "%{count} rows"
+    export_as_csv: Export as CSV
+    report: Report
+    reports: Reports
+    charts:
+      cohort_line: Cohort Line Chart
+    instances:
+      cohort_report:
+        name: Cohort Report
+        description: Generic cohort reporting
+      date_range_report:
+        name: Date Range Report
+        description: Generic daily, weekly, monthly, quarterly, yearly reports
+    params:
+      activated: Activated
+      date: Date
+      group: Group
+      group_by: Group By
+      is_cohort: Is Cohort
+      mode: Mode
+      period: Period
+      start_date: Start Date
+      stop_date: Stop Date

data/config/routes.rb

@@ -0,0 +1,7 @@
+ReportCat::Engine.routes.draw do
+
+  root :to => 'reports#index'
+
+  resources :reports, :only => [ :index, :show ]
+
+end

data/db/migrate/20130918075200_create_date_ranges.rb

@@ -0,0 +1,13 @@
+class CreateDateRanges < ActiveRecord::Migration
+  def change
+    create_table :report_cat_date_ranges do |t|
+      t.date :start_date
+      t.date :stop_date
+      t.string :period
+
+      t.index [ :period, :start_date ], :unique => true
+      t.index [ :period, :stop_date ], :unique => true
+      t.index [ :period, :start_date, :stop_date ], :unique => true, :name => 'index_report_cat_date_ranges_on_period_and_dates'
+    end
+  end
+end

data/lib/report_cat/config.rb

@@ -0,0 +1,30 @@
+require 'singleton'
+
+module ReportCat
+
+  class Config
+    include Singleton
+
+    NIL_PROC = proc {}
+
+    attr_accessor :authenticate, :authorize
+    attr_accessor :layout
+    attr_accessor :excludes
+
+    def initialize
+      @excludes = []
+    end
+
+    def authenticate_with(&blk)
+      @authenticate = blk if blk
+      @authenticate || NIL_PROC
+    end
+
+    def authorize_with(&block)
+      @authorize = block if block
+      @authorize || NIL_PROC
+    end
+
+  end
+
+end