compendium 1.1.3.4 → 1.2.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZTRmMzFjMzFhMTA3YjVjNDMwYjM0NzQwYjFhMWMxMDNlZjdlZGQ0ZQ==
-  data.tar.gz: !binary |-
-    MWEzM2NiMjk2ZjhiNGE5YmIwNjkzNjY0MTRkMDI1YWU3OGE1NWE3Ng==
+SHA1:
+  metadata.gz: a4bf2931ee1fe86a8844273e9219577c865fa9e7
+  data.tar.gz: 5f75cd47f1a38914d32850ce28b37341a536c36e
 SHA512:
-  metadata.gz: !binary |-
-    MWRlMjMxNTlkNDg4ZTUxMmRhZjBhZjJlZjVmNDJlZTRkMmVkY2Y1Nzg3YzM0
-    YzI2YTY0NGYzODdmOGFkNmI1NTBmMDVmNzBjZTI3ODBiMDdlMzJiZDk3OWZk
-    NDhjMjk2NDlmZTdkOTJkMTc3NWJjZGE1ZTcxZGQ0N2RkODNiODE=
-  data.tar.gz: !binary |-
-    ZGMzNzk4NGVhMDU0NjU1MDVjNGYyYzM2ZjIyMWZjOTc5MzgwMDEyNWEzYzcz
-    NTgwZGQ2OTA0YTMwNDZhYTAyYWNlMWQ1MGYzZDM0ZWQ3YTRmODE0MzAzMDUy
-    MzNlYjQ0NDNiZGJlMDViOTQ0NDRmNDcwMDc5MTJiNWMzYTk0NzY=
+  metadata.gz: '09afd485514be265abc5af4600fad2ef3054650160ea351658ea27aa325e3b90e9b81b88d138394568bb5abf652d79cb90e40907662f739503d3a4cf4a31be7a'
+  data.tar.gz: 8eb6644a34e973139131469c3c069fbd518f62ed7bd3ba0afebebeb8ea27a09f1d6f8a9da433ec62987d7c814ddb08d588b433ef888adfad98e5b3e2b86c1d8d

data/.travis.yml

@@ -0,0 +1,12 @@
+sudo: false
+language: ruby
+cache:
+  - bundler
+rvm:
+  - 1.9.3
+  - 2.0
+  - 2.1.9
+  - 2.2.6
+  - 2.3.3
+  - 2.4.0
+before_install: gem install bundler -v 1.13.7

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Change Log
 
+## 1.2.0
+* Added the ability to render a query to CSV, and a controller action for downloading the CSV
+* Added `exports` report setting
+* Added `skip_totals_for` option to table settings to define columns to skip in the totals row
+* Added `i18n_scope` option to table settings
+* Added `Settings::Query#update` to update query settings with a block
+* Allow table settings to be specified on the report object
+* Add settings to `render_table` to specify the CSS classes to use for each element.
+* Allow queries to be ordered and reversed via query options (:order and :reverse)
+* Add default orders for count and sum queries
+* Fix redefining a query so that it actually overrides the previous query instead of creating a new one with the same name
+
+## 1.1.3
+* Add `SumQuery` query type
+* Fix option tooltip covering input elements in IE [rvracaric]
+* Allow custom param validations to be specified
+* Fix filters being overridden by subclassed queries
+
 ## 1.1.2
 * Allow direct access to a chart object without having to render it (useful if the provider allows chart settings to be updated after initialization)
 * Delegate missing methods from ChartProvider classes to the chart

data/Gemfile

@@ -2,3 +2,7 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in compendium.gemspec
 gemspec
+
+if RUBY_VERSION >= '2.4'
+  gem 'json', github: 'flori/json', branch: 'v1.8'
+end

data/README.md

@@ -1,4 +1,4 @@
-# Compendium [![Gem Version](https://badge.fury.io/rb/compendium.svg)](http://badge.fury.io/rb/compendium)
+# Compendium [![Gem Version](https://badge.fury.io/rb/compendium.svg)](http://badge.fury.io/rb/compendium) [![Build Status](https://travis-ci.org/dvandersluis/compendium.svg?branch=master)](https://travis-ci.org/dvandersluis/compendium)
 
 Ruby on Rails framework for making reporting easy.
 
@@ -63,6 +63,89 @@ Compendium also comes with a variety of different presenters, for rendering the
 (`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).
 
+### Report Options
+Report options are defined by the keyword `option` in your report class. Options must have a name and a type (scalar, boolean, date, dropdown or radio). Additionally, an option can have a default value (given by a proc passed in with the `default:` key), and validations (via the `validates:` key).
+
+In order to specify parameters for the options, pass a hash to `MyReport.new`. Parameters are available via `params`:
+
+```ruby
+r = MyReport.new(starting_on: Date.today - 3.months, ending_on: Date.today)
+r.params
+
+# {
+#   "starting_on"=>Sun, 30 Aug 2015,
+#   "ending_on"=>Mon, 30 Nov 2015,
+# }
+```
+
+#### Validation
+
+If validation is set up on any options, calling `valid?` on the report will validate any given parameters against the validations set up, and will populate an errors object. All validations provided by `ActiveModel::Validations` are available.
+
+```ruby
+class MyReport < Compendium::Report
+  options :starting_on, :date, validates: { presence: true }
+end
+
+r = MyReport.new
+r.valid?
+# => false
+
+r.errors
+# => #<ActiveModel::Errors:0x007fe8359cc6b8
+#  @base={"starting_on"=>nil},
+#  @messages={:starting_on=>["This field is required."]}>
+```
+
+### Query types
+
+Compendium provides a few types of queries in order to make report writing more streamlined.
+
+#### Through Queries
+
+A **through query** lets you use the results of a previous query (or multiple queries) as the basis of your query. This lets you build on another query or combine multiple query's results into a single query. It it specified by passing the `through:` key to `query`, with a query name or array or query names (as symbols).
+
+```ruby
+query :dog_sales { |params| Order.where(pet_type: 'dog', created_at: params[:starting_on]..params[:ending_on]) }
+query :cat_sales { |params| Order.where(pet_type: 'cat', created_at: params[:starting_on]..params[:ending_on]) }
+query :bird_sales { |params| Order.where(pet_type: 'bird', created_at: params[:starting_on]..params[:ending_on]) }
+
+query :total_sales, through: [:dog_sales, :cat_sales, :bird_sales] do |results, params|
+  # results is a hash with keys :dog_sales, :cat_sales, :bird_sales
+end
+```
+
+#### Count Queries
+
+A **count query** simplifies creating a query where you want a count (especially per group of something). A count query is specified by adding `count: true` to the `query` call.
+
+```ruby
+query :sales_per_day, count: true do
+  Order.group("DATE(created_at)")
+end
+
+# results will look something like
+# { 2015-10-01 => 4, 2015-10-02 => 20, ... }
+```
+
+#### Sum Queries
+
+Like a count query, a **sum query** is useful for performing an aggregate function on a grouped query, in this case summing the results. A sum query is specified by adding <code>sum: <i>:column_name</i></code> to the `query` call.
+
+```ruby
+query :commission_per_salesperson, sum: 'commission' do
+  # assume commission is a numeric column
+  Order.group(:employee_id)
+end
+
+# results will be something like
+# { 1 => 840.34, 2 => 1065.02, ... }
+```
+
+#### Collection Queries
+
+Sometimes you'll want to run a collection over a collection of data; for this, you can use a **collection query**. A collection query will perform the same query for each element of a hash or array, or for each result of a query. A collection is specified via `collection: [...]`, `collection: { ... }` or `collection: query` (note not a symbol but an actual query object).
+
 ### Tying into your Rails application
 
 Compendium has a `Rails::Engine`, which adds a default controller and some views. If desired, the controller can be
@@ -78,14 +161,37 @@ within your `config/routes.rb` file
 mount_compendium at: '/report', controller: 'reports' # controller defaults to compendium/reports
 ```
 
-### Rendering report results as JSON
+### Rendering report results in other formats
+
+#### JSON
 
 While the default action when running a report is to render a view with the results, Compendium reports can be rendered
 as JSON. If using the default routes provided by `mount_compendium` (assuming compendium was mounted at `/report`),
-`POST`ing to <code>report/<i>report_name</i>.json</code> will return the report results as JSON. You can also collect
-the results of a single query (instead of the entire report) by `POST`ing to
+`GET`ing or `POST`ing to <code>report/<i>report_name</i>.json</code> will return the report results as JSON. You can also collect
+the results of a single query (instead of the entire report) by `GET`ing or `POST`ing to
 <code>report/<i>report_name</i>/<i>query_name</i>.json</code>.
 
+#### CSV
+
+A report can be exported as CSV. In order to enable CSV exports, a query needs to be defined as the exporter
+for the report. Note that only one query can be exported, because otherwise there's no way to ensure that the
+headings are consistent.
+
+```ruby
+class MyReport < Compendium::Report
+  exports :csv, :deliveries # Defines `deliveries` to be the query that is exported to CSV
+end
+```
+
+Note that if your report class subclasses another, and you want to disable a previously defined exporter, you can with `exports :csv, false`.
+
+When a report has a CSV exporter defined, an `Export CSV` button will appear on the default setup page. You can also directly export
+using the path `/report/:report_name/export.csv` (using `GET` or `POST`).
+
+Customization of the query can be done by setting table options for the query. See the [Rendering a table](#rendering-a-table) section below for more details.
+
+## Displaying Report Results
+
 ### Chart Providers
 
 As of 1.1.0, chart providers have been extracted out of the main repository and are available as their own gems. If you want to render queries as a chart, a chart provider gem is needed.
@@ -100,6 +206,81 @@ end
 
 The following providers are available (If you would like to contribute a chart provider, please let me know and I'll add it to the list):
 * [compendium-amcharts](https://github.com/dvandersluis/compendium-amcharts) - makes use of [AmCharts.rb](https://github.com/dvandersluis/amcharts.rb)
+* [compendium-highcharts](https://github.com/cimtico/compendium-highcharts) - makes use of [lazy_high_charts](https://github.com/michelson/lazy_high_charts) [thanks to [cimtico](https://github.com/cimtico)]
+
+### Rendering a table
+
+> *Note: When table settings are defined for a query, they are applied both to rendering HTML tables, as well as CSV file exports.
+See [Rendering report results in other formats](#rendering-report-results-in-other-formats) above for more details.* 
+
+In addition to charts, you can output a query as a table. When a query is rendered as a table, each row is output with columns in the
+query order (so you may want to use an explicit `select` in your query to order the columns as required). If the query is set up with
+`totals: true`, a totals row will be added to the bottom of the table.
+
+In order to customize the table, you can add a `table` declaration to your report. Each query can have different table settings.
+
+```ruby
+class MyReport < Compendium::Report
+  table :deliveries do
+    # The i18n scope to use for any translations can be specified:
+    i18n_scope 'reports.my_report'
+    
+    # Column headings by default are the column name passed through I18n,
+    # but can be overridden:
+  
+    # ... with a block...
+    override_heading do |heading|
+      # ...
+    end
+  
+    # ... or one at a time...
+    override_heading :col, 'My Column'
+  
+    # Records where a cell is 0 or nil can have the value overridden to something else:
+    display_zero_as 'N/A'
+    display_nil_as 'NULL'
+  
+    # You can specify how to format numbers:
+    number_format "%0.1f"
+  
+    # You can also specify formatting on a per-column basis:
+    format(:col) do |value|
+      "#{(value / 50) * 100}%"
+    end
+  end
+end
+```
+
+A query is rendered from a view, and is passed in the view context as the first parameter. Optionally, a block can be passed to
+override previously defined settings:
+
+```ruby
+my_query.render_table(self) do
+  display_zero_as 'nil' # Override the previous version just for this render
+end
+```
+
+#### CSS Classes
+
+By default, Compendium uses the following four CSS classes when rendering a table:
+
+| Element               | Element Type | Class Name |
+|-----------------------|--------------|------------|
+| Table                 | `table`      | `results`  |
+| Table header          | `tr`         | `headings` |
+| Table data            | `tr`         | `data`     |
+| Table footer (totals) | `tr`         | `totals`   |
+
+Each class can be overridden when setting up the table:
+
+```ruby
+my_query.render_table(self) do |t|
+  t.table_class   'my_table_class'
+  t.header_class  'my_header_class'
+  t.row_class     'my_row_class'
+  t.totals_class  'my_totals_class'
+end
+```
 
 ### Interaction with other gems
 * If [accessible_tooltip](https://github.com/dvandersluis/accessible_tooltip) is present, option notes will be rendered

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

@@ -2,7 +2,6 @@
 {
   @mixin label-font
   {
-    font-family: "Arial";
     font-size: 14px;
     font-weight: bold;
     color: #575757;
@@ -44,8 +43,8 @@
     }
   }
 
-  & + &, & + input[type=submit]
+  & + &
   {
     margin-top: 15px;
   }
-}
+}

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

@@ -48,7 +48,7 @@ module Compendium::Presenters
       params = {}
       params[:report] = options[:params] if options[:params]
 
-      if remote? and protected_against_csrf?
+      if remote? && protected_against_csrf?
         # If we're loading remotely, and CSRF protection is enabled,
         # automatically include the CSRF token in AJAX params
         params.merge!(form_authenticity_param)

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

@@ -0,0 +1,32 @@
+require 'csv'
+
+module Compendium::Presenters
+  class CSV < Table
+    def initialize(object, &block)
+      super(nil, object, &block)
+    end
+
+    def render
+      ::CSV.generate do |csv|
+        csv << headings.map{ |_, val| formatted_heading(val) }
+
+        records.each do |row|
+          csv << row.map{ |key, val| formatted_value(key, val) }
+        end
+
+        if has_totals_row?
+          totals[totals.keys.first] = translate(:total)
+          csv << totals.map do |key, val|
+            formatted_value(key, val) unless settings.skipped_total_cols.include?(key.to_sym)
+          end
+        end
+      end
+    end
+
+  private
+
+    def settings_class
+      Compendium::Presenters::Settings::Table
+    end
+  end
+end

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

@@ -1,4 +1,6 @@
 require 'compendium/presenters/base'
+require 'compendium/presenters/settings/query'
+require 'compendium/presenters/settings/table'
 
 module Compendium::Presenters
   class Query < Base
@@ -19,7 +21,7 @@ module Compendium::Presenters
     end
 
     def settings_class
-      Settings.const_get(self.class.name.demodulize) rescue Settings::Query
+      Settings.const_get(self.class.name.demodulize, false) rescue Settings::Query
     end
   end
-end
+end

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

@@ -1,9 +1,17 @@
 module Compendium::Presenters::Settings
   class Query
+    attr_reader :query
+
     delegate :[], :fetch, to: :@settings
+    delegate :report, to: :query, allow_nil: true
 
-    def initialize
+    def initialize(query = nil)
       @settings = {}.with_indifferent_access
+      @query = query
+    end
+
+    def update(&block)
+      instance_exec(self, &block)
     end
 
     def method_missing(name, *args, &block)
@@ -19,4 +27,4 @@ module Compendium::Presenters::Settings
       end
     end
   end
-end
+end

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

@@ -1,16 +1,32 @@
+require 'compendium/presenters/settings/query'
+
 module Compendium::Presenters::Settings
   class Table < Query
     attr_reader :headings
 
-    def initialize(headings)
-      super()
+    def initialize(*)
+      super
+
+      @headings = {}
+
+      # Set default values for settings
+      number_format       '%0.2f'
+      table_class         'results'
+      header_class        'headings'
+      row_class           'data'
+      totals_class        'totals'
+      skipped_total_cols  []
+    end
+
+    def set_headings(headings)
+      headings.map!(&:to_sym)
       @headings = Hash[headings.zip(headings)].with_indifferent_access
     end
 
     def override_heading(*args, &block)
       if block_given?
         @headings.each do |key, val|
-          res = yield val
+          res = yield val.to_s
           @headings[key] = res if res
         end
       else
@@ -27,5 +43,9 @@ module Compendium::Presenters::Settings
     def formatters
       (@settings[:formatters] || {})
     end
+
+    def skip_total_for(*cols)
+      @settings[:skipped_total_cols].concat(cols.map(&:to_sym))
+    end
   end
-end
+end

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

@@ -1,27 +1,33 @@
 module Compendium::Presenters
   class Table < Query
-    attr_reader :records, :totals
+    attr_reader :records, :totals, :settings
 
     def initialize(*)
       super
 
       @records = results.records
-      @totals = @records.pop if has_totals_row?
 
-      @settings = settings_class.new(results.keys)
+      @settings = settings_class.new(query)
+      @settings.set_headings(results.keys)
+      @settings.update(&query.table_settings) if query.table_settings
       yield @settings if block_given?
+
+      if has_totals_row?
+        @totals = @records.pop
+        totals[totals.keys.first] = translate(:total)
+      end
     end
 
     def render
-      content_tag(:table, class: 'results') do
+      content_tag(:table, class: @settings.table_class) do
         table = ActiveSupport::SafeBuffer.new
-        table << content_tag(:thead, build_heading_row)
+        table << content_tag(:thead, build_row(headings, settings.header_class, :th, &heading_proc))
         table << content_tag(:tbody) do
           tbody = ActiveSupport::SafeBuffer.new
-          records.each { |row| tbody << build_data_row(row) }
+          records.each { |row| tbody << build_row(row, settings.row_class, &data_proc) }
           tbody
         end
-        table << content_tag(:tfoot, build_totals_row) if has_totals_row?
+        table << content_tag(:tfoot, build_row(totals, @settings.totals_class, :th, &totals_proc)) if has_totals_row?
         table
       end
     end
@@ -36,21 +42,20 @@ module Compendium::Presenters
       query.options.fetch(:totals, false)
     end
 
-    def build_data_row(row)
-      build_row(row, 'data') { |key, val| formatted_value(key, val) }
+    def data_proc
+      proc { |key, val| formatted_value(key, val) }
     end
 
-    def build_heading_row
-      build_row(headings, 'headings', :th) { |key, val| t(val) }
+    def heading_proc
+      proc { |_, val| formatted_heading(val) }
     end
 
-    def build_totals_row
-      totals[totals.keys.first] = t(:total)
-      build_row(totals, 'totals', :th) { |key, val| formatted_value(key, val) }
+    def totals_proc
+      proc { |key, val| formatted_value(key, val) unless settings.skipped_total_cols.include?(key.to_sym) }
     end
 
     def build_row(row, row_class, cell_type = :td)
-      content_tag('tr', class: row_class) do
+      content_tag(:tr, class: row_class) do
         out = ActiveSupport::SafeBuffer.new
 
         row.each.with_index do |(key, val), i|
@@ -62,20 +67,30 @@ module Compendium::Presenters
       end
     end
 
+    def formatted_heading(v)
+      v.is_a?(Symbol) ? translate(v) : v
+    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?
+          if v.zero? && @settings.display_zero_as?
             @settings.display_zero_as
           else
-            sprintf(@settings.number_format || '%0.2f', v)
+            sprintf(@settings.number_format, v)
           end
         elsif v.nil?
           @settings.display_nil_as
         end
       end || v
     end
+
+    def translate(v, opts = {})
+      opts.reverse_merge!(scope: settings.i18n_scope) if settings.i18n_scope?
+      opts[:default] = -> * { I18n.t(v, scope: 'compendium') }
+      I18n.t(v, opts)
+    end
   end
-end
+end