compendium 0.0.1 → 1.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MDMzZWY3N2Y4MWU5MGUxODg2YzFjZWY2ZDgzNzE0ZTU0MmNkN2IyYw==
+  data.tar.gz: !binary |-
+    ZDBjNTEwN2NjNGNlZWIxMzhiMWQ5MGRmMzg0NmY4NGQyNTlhYTAwNA==
+SHA512:
+  metadata.gz: !binary |-
+    MDQ1M2YwZDVjMWEyN2M2NjM4ZDYxOGY4ZTEwOTQ0M2Y0MWIzM2UxNDM2MGVm
+    YzIwMDFkYzM1ZjliNDUxMjBjNzQxNDkyMTIzYzlhNWQyNjViYTMwYmRhYmUy
+    ODBiODRhZjRkOGQ0MWVjNDdiNjE4MmE3MjM2OGNkNDZlZTE0NDk=
+  data.tar.gz: !binary |-
+    NjIzZGIwNWY1NTU3MzViOTU5Njc3MzFiNTdiYzdhZWViYjIwOGVlYzZmMDhm
+    NWI5NzkwNDJjYTUzYjIwNDg4ZjZkZDJhYzE5MDE0ZGQyM2U0Y2JlMGIzNThk
+    ODY0NDFkY2NhMDg1MWZkYmU3MjlmNjdhMzIxZWUzYWFjNjIyMzU=

data/README.md

@@ -2,6 +2,72 @@
 
 Ruby on Rails framework for making reporting easy.
 
+## Usage
+
+Compendium is a reporting framework for Rails which makes it easy to create and render reports (with charts and tables).
+
+A Compendium report is a subclass of `Compendium::Report`. Reports can be defined using the simple DSL:
+
+    class MyReport < Compendium::Report
+      # Options define which parameters your report will accept when being set up.
+      # An option is defined with a name, a type, and some settings (ie. default value, choices for radio buttons and
+      # dropdowns, etc.)
+      option :starting_on, :date, default: -> { Date.today - 1.month }
+      option :ending_on, :date, default: -> { Date.today }
+      option :currency, :radio, choices: [:USD, :CAD, :GBP]
+
+      # By default, queries are converted to SQL and executed instead of returning AR models
+      # The query definition block gets the report's current parameters
+      # totals: true means that the last row returned should be interpretted as a row of totals
+      query :deliveries, totals: true do |params|
+        Items.where(delivered: true, purchased_at: (params[:starting_on]..params[:ending_on]))
+      end
+
+      # Define a query which collects data by using AR directly
+      query :on_hand_inventory, collect: :active_record do |params|
+        Items.where(in_stock: true)
+      end
+
+      # Define a query that works on another query's result set
+      # Note: chart and data are aliases for query
+      chart :deliveries_over_time, through: :deliveries do |results|
+        results.group_by(&:purchased_at)
+      end
+
+      # Queries can also be used to drive metrics
+      metric :shipping_time, -> results { results.last['shipping_time'] }, through: :deliveries
+    end
+
+Reports can then also be simply instantiated (which is done automatically if using the supplied
+`Compendium::ReportsController`):
+
+    report = MyReport.new(starting_on: '2013-06-01')
+    report.run(self) # The parameter is the context to run the report in; usually this should be
+                     # a controller context so that methods like current_user can be used
+
+Compendium also comes with a variety of different presenters, for rendering the setup page, and displaying charts
+(`report.render_chart`), tables (`report.render_table`) and metrics for your report. Charting is delegated through a
+`ChartProvider` to a charting gem (amcharts.rb is currently supported).
+
+### Tying into your Rails application
+
+Compendium has a `Rails::Engine`, which adds a default controller and some views. If desired, the controller can be
+subclassed so that filters and the like can be added. The controller (which extends `ApplicationController`
+automatically) has two actions: `setup` (collect options for the report) and `run` (execute and render the report),
+with accompanying views. The `setup` view can be included inside your own view using the `render_report_setup`
+method (*NOTE:* you have to pass `local_assigns` into it if you want locals to be passed along).
+
+Routes are not automatically added to your application. In order to do so, you can use the `mount_compendium` helper
+within your `config/routes.rb` file
+
+    mount_compendium at: '/report', controller: 'reports' # controller defaults to compendium/reports
+
+### Interaction with other gems
+* If [accessible_tooltip](https://github.com/dvandersluis/accessible_tooltip) is present, option notes will be rendered
+in a tooltip rather than as straight text.
+* [AmCharts.rb](https://github.com/dvandersluis/amcharts.rb) is currently the only chart provider (please create a pull
+request if you'd like to create another one...)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -16,10 +82,6 @@ Or install it yourself as:
 
     $ gem install compendium
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Contributing
 
 1. Fork it
@@ -27,3 +89,7 @@ TODO: Write usage instructions here
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+## Acknowledgments
+
+* Special thanks to [TalentNest](http://github.com/talentnest), who sponsored this gem's development.

data/Rakefile

@@ -1 +1,5 @@
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/app/assets/stylesheets/compendium/_metrics.css.scss

@@ -0,0 +1,92 @@
+@import "compass/css3/border-radius";
+
+div.metrics
+{
+  div.metric
+  {
+    float: left;
+    margin: 10px;
+    padding: 5px;
+    border: 2px solid #575757;
+    width: 150px;
+    height: 150px;
+    font-size: 12px;
+    text-align: center;
+    color: #575757;
+    @include border-radius(10px);
+
+    .metric-label
+    {
+      height: 30%;
+      font-size: 150%;
+      padding-top: 10px;
+      padding-bottom: 5px;
+      font-weight: bold;
+    }
+
+    .metric-data
+    {
+      height: 50%;
+      position: relative;
+      font-size: 600%;
+      font-weight: bold;
+      color: black;
+
+      .metric-data-inner
+      {
+        display: inline;
+        position: relative;
+        line-height: 0;
+        top: 50%;
+        margin: auto;
+        padding: 0;
+      }
+    }
+
+    .metric-label-small
+    {
+      height: 20%;
+      font_size: 90%;
+    }
+
+    &.small
+    {
+      width: 115px;
+      height: 115px;
+      font-size: 10px;
+
+      .metric-label
+      {
+        padding-top: 0px;
+      }
+
+      .metric-label-small
+      {
+        font-size: 100%;
+      }
+    }
+
+    &.big
+    {
+      border-width: 3px;
+      width: 280px;
+      height: 280px;
+      font-size: 22px;
+
+      .metric-label
+      {
+        padding-top: 25px;
+      }
+
+      .metric-label-small
+      {
+        margin-top: -25px;
+      }
+
+      .metric-data
+      {
+        top: -10px;
+      }
+    }
+  }
+}

data/app/assets/stylesheets/compendium/options.css.scss

@@ -0,0 +1,41 @@
+.option
+{
+  .option-label
+  {
+    margin: 0px 0px 0px 0px;
+    font-family: "Arial";
+    font-size: 14px;
+    font-weight: bold;
+    color: #575757;
+  }
+
+  .option-note
+  {
+    font-style: italic;
+    color: #575757;
+  }
+
+  .option-element-group
+  {
+    margin-top: 3px;
+  }
+
+  .option-radio
+  {
+    input[type=radio]
+    {
+      margin: 2px 6px 2px 0;
+
+      & + label
+      {
+        position: relative;
+        top: 1px;
+      }
+    }
+  }
+
+  & + &, & + input[type=submit]
+  {
+    margin-top: 15px;
+  }
+}

data/app/assets/stylesheets/compendium/report.css.scss

@@ -0,0 +1,22 @@
+.report
+{
+  @import 'metrics';
+
+  .title
+  {
+    font-size: 200%;
+    font-weight: bold;
+  }
+
+  .subtitle
+  {
+    font-size: 150%;
+    font-weight: bold;
+  }
+
+  .setting, .option
+  {
+    font-weight: bold;
+    color: #575757;
+  }
+}

data/app/classes/compendium/presenters/base.rb

@@ -0,0 +1,30 @@
+module Compendium::Presenters
+  class Base
+    def initialize(template, object)
+      @object = object
+      @template = template
+    end
+
+    def to_s
+      "#<#{self.class.name}:0x00#{'%x' % (object_id << 1)}>"
+    end
+
+  private
+
+    def self.presents(name)
+      define_method(name) do
+        @object
+      end
+    end
+
+    def method_missing(*args, &block)
+      return @template.send(*args, &block) if @template.respond_to?(args.first)
+      super
+    end
+
+    def respond_to_missing?(*args)
+      return true if @template.respond_to?(*args)
+      super
+    end
+  end
+end

data/app/classes/compendium/presenters/chart.rb

@@ -0,0 +1,31 @@
+module Compendium::Presenters
+  class Chart < Query
+    attr_reader :data, :chart_provider
+
+    def initialize(template, object, type, container = nil, &setup)
+      super(template, object)
+
+      @data = results.records
+      @data = @data[0...-1] if query.options[:totals]
+
+      @container = container || query.name
+
+      initialize_chart_provider(type, &setup)
+    end
+
+    def render
+      chart_provider.render(@template, @container)
+    end
+
+  private
+
+    def provider
+      provider = Compendium.config.chart_provider
+      provider.is_a?(Class) ? provider : Compendium::ChartProvider.const_get(provider)
+    end
+
+    def initialize_chart_provider(type, &setup)
+      @chart_provider = provider.new(type, @data, &setup)
+    end
+  end
+end

data/app/classes/compendium/presenters/metric.rb

@@ -0,0 +1,19 @@
+module Compendium::Presenters
+  class Metric < Base
+    presents :metric
+
+    delegate :name, :query, :ran?, to: :metric
+
+    def label
+      t("#{query}.#{name}")
+    end
+
+    def result(number_format = '%0.1f', display_nil_as = :na)
+      if metric.result
+        sprintf(number_format, metric.result)
+      else
+        t(display_nil_as)
+      end
+    end
+  end
+end

data/app/classes/compendium/presenters/option.rb

@@ -0,0 +1,97 @@
+module Compendium::Presenters
+  class Option < Base
+    MISSING_CHOICES_ERROR = "choices must be specified"
+
+    presents :option
+
+    def name
+      t(option.name)
+    end
+
+    def label(form)
+      label = case option.type.to_sym
+        when :boolean, :radio
+          name
+
+        else
+          form.label option.name, name
+      end
+
+      out = ActiveSupport::SafeBuffer.new
+      out << content_tag(:span, label, class: 'option-label')
+
+      if option.note?
+        note = t(option.note == true ? :"#{option.name}_note" : option.note)
+
+        if defined?(AccessibleTooltip)
+          return accessible_tooltip(:help, label: out, title: t("#{option.name}_note_title", default: '')) { note }
+        else
+          out << content_tag(:div, note, class: 'option-note')
+        end
+      end
+
+      out
+    end
+
+    def note
+      if option.note?
+        key = option.note === true ? :"#{option.name}_note" : option.note
+        content_tag(:div, t(key), class: 'option-note')
+      end
+    end
+
+    def input(ctx, form)
+      out = ActiveSupport::SafeBuffer.new
+
+      case option.type.to_sym
+        when :date
+          out << date_field(form)
+
+        when :dropdown
+          raise ArgumentError, MISSING_CHOICES_ERROR unless option.choices?
+
+          options = option.choices
+          options = ctx.instance_exec(&options) if options.respond_to?(:call)
+          out << dropdown(form, options)
+
+        when :boolean, :radio
+          choices = if option.radio?
+            raise ArgumentError, MISSING_CHOICES_ERROR unless option.choices?
+            option.choices
+          else
+            %w(true false)
+          end
+
+          choices.each.with_index { |choice, index| out << radio_button(form, choice, index) }
+      end
+
+      out
+    end
+
+  private
+
+    def date_field(form, include_time = false)
+      content_tag('div', class: 'option-date') do
+        if defined?(CalendarDateSelect)
+          form.calendar_date_select option.name, time: include_time, popup: 'force'
+        else
+          form.text_field option.name
+        end
+      end
+    end
+
+    def dropdown(form, choices = {})
+      content_tag('div', class: 'option-dropdown') do
+        form.select option.name, choices
+      end
+    end
+
+    def radio_button(form, label, value)
+      content_tag('div', class: 'option-radio') do
+        div_content = ActiveSupport::SafeBuffer.new
+        div_content << form.radio_button(option.name, value)
+        div_content << form.label(option.name, t(label), value: value)
+      end
+    end
+  end
+end

data/app/classes/compendium/presenters/query.rb

@@ -0,0 +1,23 @@
+module Compendium::Presenters
+  class Query < Base
+    presents :query
+
+    def initialize(template, object)
+      super(template, object)
+    end
+
+    def render
+      raise NotImplementedError
+    end
+
+  private
+
+    def results
+      query.results
+    end
+
+    def settings_class
+      Settings.const_get(self.class.name.demodulize) rescue Settings::Query
+    end
+  end
+end

data/app/classes/compendium/presenters/settings/query.rb

@@ -0,0 +1,22 @@
+module Compendium::Presenters::Settings
+  class Query
+    delegate :[], :fetch, to: :@settings
+
+    def initialize
+      @settings = {}.with_indifferent_access
+    end
+
+    def method_missing(name, *args, &block)
+      if block_given?
+        @settings[name] = block.call(*args)
+      elsif !args.empty?
+        @settings[name] = args.length == 1 ? args.first : args
+      elsif name.to_s.end_with?('?')
+        prefix = name.to_s.gsub(/\?\z/, '')
+        @settings.key?(prefix)
+      else
+        @settings[name]
+      end
+    end
+  end
+end

data/app/classes/compendium/presenters/settings/table.rb

@@ -0,0 +1,23 @@
+module Compendium::Presenters::Settings
+  class Table < Query
+    attr_reader :headings
+
+    def initialize(headings)
+      super()
+      @headings = Hash[headings.zip(headings)].with_indifferent_access
+    end
+
+    def override_heading(col, label)
+      @headings[col] = label
+    end
+
+    def format(column, &block)
+      @settings[:formatters] ||= {}
+      @settings[:formatters][column] = block
+    end
+
+    def formatters
+      (@settings[:formatters] || {})
+    end
+  end
+end

data/app/classes/compendium/presenters/table.rb

@@ -0,0 +1,81 @@
+module Compendium::Presenters
+  class Table < Query
+    attr_reader :records, :totals
+
+    def initialize(*)
+      super
+
+      @records = results.records
+      @totals = @records.pop if has_totals_row?
+
+      @settings = settings_class.new(results.keys)
+      yield @settings if block_given?
+    end
+
+    def render
+      content_tag(:table, class: 'results') do
+        table = ActiveSupport::SafeBuffer.new
+        table << content_tag(:thead, build_heading_row)
+        table << content_tag(:tbody) do
+          tbody = ActiveSupport::SafeBuffer.new
+          records.each { |row| tbody << build_data_row(row) }
+          tbody
+        end
+        table << content_tag(:tfoot, build_totals_row) if has_totals_row?
+        table
+      end
+    end
+
+  private
+
+    def headings
+      @settings.headings
+    end
+
+    def has_totals_row?
+      query.options.fetch(:totals, false)
+    end
+
+    def build_data_row(row)
+      build_row(row, 'data') { |key, val| formatted_value(key, val) }
+    end
+
+    def build_heading_row
+      build_row(headings, 'headings', :th) { |key, val| t(val) }
+    end
+
+    def build_totals_row
+      totals[totals.keys.first] = t(:total)
+      build_row(totals, 'totals', :th) { |key, val| formatted_value(key, val) }
+    end
+
+    def build_row(row, row_class, cell_type = :td)
+      content_tag('tr', class: row_class) do
+        out = ActiveSupport::SafeBuffer.new
+
+        row.each.with_index do |(key, val), i|
+          val = yield key, val, i if block_given?
+          out << content_tag(cell_type, val)
+        end
+
+        out
+      end
+    end
+
+    def formatted_value(k, v)
+      if @settings.formatters[k]
+        @settings.formatters[k].call(v)
+      else
+        if v.numeric?
+          if v.zero? and @settings.display_zero_as?
+            @settings.display_zero_as
+          else
+            sprintf(@settings.number_format || '%0.2f', v)
+          end
+        elsif v.nil?
+          @settings.display_nil_as
+        end
+      end || v
+    end
+  end
+end

data/app/controllers/compendium/reports_controller.rb

@@ -0,0 +1,52 @@
+module Compendium
+  class ReportsController < ::ApplicationController
+    helper Compendium::ReportsHelper
+
+    before_filter :find_report
+    before_filter :run_report, only: :run
+
+    def setup
+      render locals: { report: setup_report, prefix: @prefix }
+    end
+
+    def run
+      template = template_exists?(@prefix, get_template_prefixes) ? @prefix : 'run'
+      render action: template, locals: { report: @report }
+    end
+
+    private
+
+    def find_report
+      @prefix = params[:report_name]
+      @report_name = "#{@prefix}_report"
+
+      begin
+        require(@report_name) unless Rails.env.development? or Module.const_defined?(@report_name.classify)
+        @report_class = @report_name.camelize.constantize
+      rescue LoadError
+        flash[:error] = t(:invalid_report)
+        redirect_to action: :index
+      end
+    end
+
+    def setup_report
+      @report_class.new(params[:report] || {})
+    end
+
+    def run_report
+      @report = @report_class.new(params[:report]).run(self)
+    end
+
+    def get_template_prefixes
+      paths = []
+      klass = self.class
+
+      begin
+        paths << klass.name.underscore.gsub(/_controller$/, '')
+        klass = klass.superclass
+      end while(klass != ActionController::Base)
+
+      paths
+    end
+  end
+end

data/app/helpers/compendium/reports_helper.rb

@@ -0,0 +1,21 @@
+module Compendium
+  module ReportsHelper
+    def expose(*args)
+      klass = args.pop if args.last.is_a?(Class)
+      klass ||= "Compendium::Presenters::#{args.first.class}".constantize
+      presenter = klass.new(self, *(args.empty? ? [nil] : args))
+      yield presenter if block_given?
+      presenter
+    end
+
+    def render_report_setup(assigns)
+      render file: "#{Compendium::Engine.root}/app/views/compendium/reports/setup", locals: assigns
+    end
+
+    def render_if_exists(options = {})
+      if lookup_context.template_exists?(options[:partial] || options[:template], options[:path], options.key?(:partial))
+        render options
+      end
+    end
+  end
+end

data/app/views/compendium/reports/run.haml

@@ -0,0 +1 @@
+= t(:results, report_name: @prefix)

data/app/views/compendium/reports/setup.haml

@@ -0,0 +1,14 @@
+- content_for :stylesheets do
+  = stylesheet_link_tag 'compendium/options'
+
+= render_if_exists partial: 'report_header', path: 'compendium/reports'
+
+.options
+  = form_for report, as: :report, url: compendium_reports_run_path do |f|
+    - report.options.values.each do |option|
+      - expose option, Compendium::Presenters::Option do |opt|
+        .option
+          = opt.label(f)
+          .option-element-group= opt.input(self, f)
+
+    = f.submit t(:generate_report, scope: 'compendium.reports')