compendium 1.0.7 → 1.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    Y2ZlZDg2ZDkxZjRlNjc5Yzk0OTZlYWUyYTJkNDZmMTBkNTlmNDczMA==
+    YzRhZmU5NjE5ZTIzMGZmM2JmMzhlNDRhNjY3NTQ2ZjRjYzI0ZDkxNg==
   data.tar.gz: !binary |-
-    OWE2NmE5MGZlZjhmNzdlOTljZWQyYmQ4NDU2NzhlZmM5MzZhMjgxNg==
+    ODk2NGYxNjU1YzgzZTlkZmM5MmU1ZjljZjNlNjdkZGE1YTY0ZmY1Ng==
 SHA512:
   metadata.gz: !binary |-
-    ZjNkMDgzYWI0OGNkZTY4NGJmMDQxMzRjMzcyODEyOWE2MGFhZDlmOWIzMzZl
-    ZTQ3OGViNWQ3MGY3ZTlkOGFkMzZhNmVjNmM3NmFiMjYwMzc2MmE0YTQ2ZjBm
-    YzY0ODFkNzlhMzBhZTEzNDkzNTQ3OTVlZmMwZDJiOWE3NWFiYWU=
+    OThmYTFhNmQ2MWY0NTdmYmQxYzg2OTkzYzViNThmMTNjNzhhNDgzMjU4NmQ2
+    NjYyMThlMzQyMDY4NzU1YWY0MTdiNGIyYWFjNzdlMzgzMGMyZjY0MTk0MjU2
+    MzEyYTVjMGE1ZTQ2NTczN2YyOWM5ZTg1YTk1Mzg3ZjYxOTNjOGI=
   data.tar.gz: !binary |-
-    ZDk4ODU0OTJmMTU4ODA2ODViZjhlNDVjZTI2YTdlMjA4ZDY2ZGFhZWI1OWQy
-    ZjM4MjAxNTI2NzRkYTYxNTlhNDAxNzkxYzMwNjdhNDA4MGI3N2NhZWRlOTFm
-    Yjc1OWQzMzVjNWZhN2QwNGQ3YTZkMTgyZTI0NjRkMmMzNjcyNjI=
+    Y2M1NzdhOGQzMWVhZjNmNGVlZTVlY2JiOWQzZTFlZTkzZGY4ZjE5YjdiMWVi
+    ZGU2MzY3ZTU4ZTFiNzU4MDQxNTA5ZjBlZTlmY2YyNGIyM2ZlZWQ3MzNhYzMz
+    ZjExMWFhOWZhZTIwOGQwZjJlOGQ2ZGE1OTFhYjAxOTA2MzEwMGE=

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Change Log
+
+## 1.1.0 (unreleased)
+* Added query filters (allow a result set to be filtered to remove/translate/etc. data)
+* Extract chart providers into their own gems
+* Allow queries to be rendered as charts without having been run yet (to set up for a future AJAX load)
+* Added `Report#url` and `Query#url` methods to get the JSON URL
+
+## 1.0.7
+* Added the ability to render a report or a specific query of a report as JSON
+
+## 1.0.6
+* Added a built-in renderer for metrics
+
+## 1.0.5
+* Fixed the `:only` and `:except` options to `Report#run`
+* Give `ThroughQuery` access to params if the definition block has an arity of 2
+* Fixed mutating results in a `ThroughQuery` block affecting the parent query

data/README.md

@@ -24,6 +24,16 @@ class MyReport < Compendium::Report
     Items.where(delivered: true, purchased_at: (params[:starting_on]..params[:ending_on]))
   end
 
+  # Define a filter to modify the results from specified query (in this case :deliveries)
+  # For example, this can be useful to translate columns prior to rendering, as it will apply
+  # for all render types (table, chart, JSON)
+  # Note: A filter can be applied to multiple queries at once
+  filter :deliveries do |results, params|
+    results.each do |row|
+      row['price'] = sprintf('$%.2f', row['price'])
+    end
+  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)

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

@@ -3,17 +3,25 @@ require 'active_support/core_ext/array/extract_options'
 
 module Compendium::Presenters
   class Chart < Query
-    attr_reader :data, :container, :chart_provider
+    attr_reader :data, :params, :container, :chart_provider
+    attr_accessor :options
 
     def initialize(template, object, *args, &setup)
-      options = args.extract_options!
-      type, container = args
-
       super(template, object)
 
-      @data = options[:index] ? results.records[options[:index]] : results
-      @data = @data.records if @data.is_a?(Compendium::ResultSet)
-      @data = @data[0...-1] if query.options[:totals]
+      self.options = args.extract_options!
+      type, container = args
+
+      if remote?
+        # If the query hasn't run yet, render a chart that loads its data remotely (ie. through AJAX)
+        # ie. if rendering a query from a report class directly
+        @data = query.url
+        @params = collect_params
+      else
+        @data = options[:index] ? results.records[options[:index]] : results
+        @data = @data.records if @data.is_a?(Compendium::ResultSet)
+        @data = @data[0...-1] if query.options[:totals]
+      end
 
       @container = container || query.name
 
@@ -32,7 +40,34 @@ module Compendium::Presenters
     end
 
     def initialize_chart_provider(type, &setup)
-      @chart_provider = provider.new(type, @data, &setup)
+      @chart_provider = provider.new(type, @data, @params, &setup)
+    end
+
+    def collect_params
+      params = {}
+      params[:report] = options[:params] if options[:params]
+
+      if remote? and 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)
+      end
+
+      params
+    end
+
+    # You can force the chart to render remote data, even if the query has already run by passing the remote: true option
+    def remote?
+      !query.ran? || options.fetch(:remote, false)
+    end
+
+    def protected_against_csrf?
+      !@template.controller.forgery_protection_strategy.nil?
+    end
+
+    def form_authenticity_param
+      return {} unless protected_against_csrf?
+      { @template.controller.request_forgery_protection_token => @template.controller.send(:form_authenticity_token) }
     end
   end
 end

data/lib/compendium/abstract_chart_provider.rb

@@ -3,10 +3,17 @@ require 'active_support/core_ext/string/inflections'
 module Compendium
   # Abstract wrapper for rendering charts
   # To add a new chart provider, #initialize and #render must be implemented
+  # Custom providers should also override Compendium::AbstractChartProvider.find_chart_provider (but fallback to super)
+
   class AbstractChartProvider
     attr_reader :chart
 
-    def initialize(type, data, &setup_proc)
+    # @param type [Symbol] The type of chart you want to render (:pie, :line, etc).
+    #   Accepted types might vary by provider.
+    # @param data_or_url [Enumerable or String] The data or URL to the data you wish to render.
+    #   Providers may not support loading data remotely.
+    # @param params [Hash] If data_or_url is a URL, the params to use for the AJAX request
+    def initialize(type, data_or_url, params = {}, &setup_proc)
       raise NotImplementedError
     end
 
@@ -14,17 +21,9 @@ module Compendium
       raise NotImplementedError
     end
 
-    # As more chart providers are added, this method will have to be extended to find them
+    # Chart providers need to override this method to add a hook for themselves
     def self.find_chart_provider
-      if defined?(AmCharts)
-        :AmCharts
-      else
-        self.name.demodulize.to_sym
-      end
+      nil
     end
   end
-
-  module ChartProvider
-    autoload :AmCharts, 'compendium/chart_provider/amcharts'
-  end
 end

data/lib/compendium/dsl.rb

@@ -49,6 +49,13 @@ module Compendium
       end
     end
 
+    def filter(*query_names, &block)
+      query_names.each do |query_name|
+        raise ArgumentError, "query #{query_name} is not defined" unless queries.key?(query_name)
+        queries[query_name].add_filter(block)
+      end
+    end
+
     # Each Report will have its own descendant of Params in order to safely add validations
     def params_class
       @params_class ||= Class.new(Params)
@@ -95,6 +102,7 @@ module Compendium
       end
 
       query = query_type.new(*params)
+      query.report = self
 
       metrics[name] = opts[:metric] if opts.key?(:metric)
       queries << query

data/lib/compendium/query.rb

@@ -7,7 +7,7 @@ require_relative '../../config/initializers/ruby/hash'
 
 module Compendium
   class Query
-    attr_reader :name, :results, :metrics
+    attr_reader :name, :results, :metrics, :filters
     attr_accessor :options, :proc, :report
 
     def initialize(*args)
@@ -17,6 +17,7 @@ module Compendium
 
       @name, @options, @proc = args
       @metrics = ::Collection[Metric]
+      @filters = ::Collection[Proc]
     end
 
     def initialize_clone(*)
@@ -25,22 +26,40 @@ module Compendium
     end
 
     def run(params, context = self)
-      collect_results(context, params)
-      collect_metrics(context)
+      if report.is_a?(Class)
+        # If running a query directly from a class rather than an instance, the class's query should
+        # not be affected/modified, so run the query without a reference back to the report.
+        # Otherwise, if the class is subsequently instantiated, the instance will already have results.
+        dup.tap{ |q| q.report = nil }.run(params, context)
+      else
+        collect_results(context, params)
+        collect_metrics(context)
 
-      @results
+        @results
+      end
+    end
+
+    # Get a URL for this query (format: :json set by default)
+    def url(params = {})
+      report.url(params.merge(query: self.name))
     end
 
     def add_metric(name, proc, options = {})
       Compendium::Metric.new(name, self.name, proc, options).tap { |m| @metrics << m }
     end
 
+    def add_filter(filter)
+      @filters << filter
+    end
+
     def render_table(template, *options, &block)
       Compendium::Presenters::Table.new(template, self, *options, &block).render unless empty?
     end
 
     def render_chart(template, *options, &block)
-      Compendium::Presenters::Chart.new(template, self, *options, &block).render unless empty?
+      # A query can be rendered regardless of if it has data or not
+      # Rendering a chart with no result set builds a chart scaffold which can be updated through AJAX
+      Compendium::Presenters::Chart.new(template, self, *options, &block).render
     end
 
     def ran?
@@ -55,15 +74,16 @@ module Compendium
 
     # A query is empty if it has no results
     def empty?
-      results.empty?
+      results.blank?
     end
 
   private
 
     def collect_results(context, *params)
       command = context.instance_exec(*params, &proc) if proc
-      command = fetch_results(command)
-      @results = ResultSet.new(command) if command
+      results = fetch_results(command)
+      results = filter_results(results, *params) if filters.any?
+      @results = ResultSet.new(results) if results
     end
 
     def collect_metrics(context)
@@ -74,6 +94,20 @@ module Compendium
       (options.fetch(:collect, nil) == :active_record) ? command : execute_command(command)
     end
 
+    def filter_results(results, params)
+      return unless results
+
+      filters.each do |f|
+        if f.arity == 2
+          results = f.call(results, params)
+        else
+          results = f.call(results)
+        end
+      end
+
+      results
+    end
+
     def execute_command(command)
       return [] if command.nil?
       command = command.to_sql if command.respond_to?(:to_sql)

data/lib/compendium/report.rb

@@ -11,6 +11,7 @@ module Compendium
     extend Compendium::DSL
 
     delegate :valid?, :errors, to: :params
+    delegate :name, :url, to: :class
 
     class << self
       def inherited(report)
@@ -27,6 +28,15 @@ module Compendium
         }
       end
 
+      def name
+        super.underscore.gsub(/_report$/,'').to_sym
+      end
+
+      # Get a URL for this report (format: :json set by default)
+      def url(params = {})
+        path_helper(params)
+      end
+
       # Define predicate methods for getting the report type
       # ie. r.spending? checks that r == SpendingReport
       def method_missing(name, *args, &block)
@@ -45,6 +55,16 @@ module Compendium
         return true if name.to_s.end_with?('?') and Compendium.reports.include?(report_class)
         super
       end
+
+    private
+
+      def path_helper(params)
+        unless Rails.application.routes.url_helpers.method_defined? :compendium_reports_run_path
+          raise ActionController::RoutingError, "compendium_reports_run_path must be defined"
+        end
+
+        Rails.application.routes.url_helpers.compendium_reports_run_path(self.name, params.reverse_merge(format: :json))
+      end
     end
 
     def initialize(params = {})

data/lib/compendium/version.rb

@@ -1,3 +1,3 @@
 module Compendium
-  VERSION = "1.0.7"
+  VERSION = "1.1.0"
 end

data/spec/dsl_spec.rb

@@ -60,8 +60,8 @@ describe Compendium::DSL do
       r.test.report.should == r
     end
 
-    it "should not relate a query to the report class" do
-      subject.test.report.should be_nil
+    it "should relate a query to the report class" do
+      subject.test.report.should == subject
     end
 
     context "when given a through option" do
@@ -159,6 +159,35 @@ describe Compendium::DSL do
     end
   end
 
+  describe "#filter" do
+    let(:filter_proc) { ->{ :filter } }
+
+    it "should add a filter to the given query" do
+      subject.query :test
+      subject.filter :test, &filter_proc
+      subject.queries[:test].filters.should include filter_proc
+    end
+
+    it "should raise an error if there is no query of the given name" do
+      expect { subject.filter :test, &filter_proc }.to raise_error(ArgumentError, "query test is not defined")
+    end
+
+    it "should allow multiple filters to be defined for the same query" do
+      subject.query :test
+      subject.filter :test, &filter_proc
+      subject.filter :test, &->{ :another_filter }
+      subject.queries[:test].filters.count.should == 2
+    end
+
+    it "should allow a filter to be applied to multiple queries at once" do
+      subject.query :query1
+      subject.query :query2
+      subject.filter :query1, :query2, &filter_proc
+      subject.queries[:query1].filters.should include filter_proc
+      subject.queries[:query2].filters.should include filter_proc
+    end
+  end
+
   it "should allow previously defined queries to be redefined by name" do
     subject.query :test_query
     subject.test_query foo: :bar

data/spec/presenters/chart_spec.rb

@@ -2,16 +2,16 @@ require 'spec_helper'
 require 'compendium/presenters/chart'
 
 describe Compendium::Presenters::Chart do
+  let(:template) { double('Template', forgery_protection_strategy: nil, request_forgery_protection_token: :authenticity_token, form_authenticity_token: "ABCDEFGHIJ").as_null_object }
+  let(:query) { double('Query', name: 'test_query', results: results, ran?: true, options: {}).as_null_object }
+  let(:results) { Compendium::ResultSet.new([]) }
+
   before do
     described_class.any_instance.stub(:provider) { double('ChartProvider') }
     described_class.any_instance.stub(:initialize_chart_provider)
   end
 
   describe '#initialize' do
-    let(:template) { double('Template') }
-    let(:query) { double('Query', name: 'test_query', results: results, options: {}) }
-    let(:results) { Compendium::ResultSet.new([]) }
-
     context 'when all params are given' do
       subject{ described_class.new(template, query, :pie, :container) }
 
@@ -33,5 +33,39 @@ describe Compendium::Presenters::Chart do
       its(:data) { should == results.records[:one] }
       its(:container) { should == 'test_query' }
     end
+
+    context "when the query has not been run" do
+      before { query.stub(ran?: false, url: '/path/to/query.json') }
+
+      subject{ described_class.new(template, query, :pie, params: { foo: 'bar' }) }
+
+      its(:data) { should == '/path/to/query.json' }
+      its(:params) { should == { report: { foo: 'bar' } } }
+
+      context "when CSRF protection is enabled" do
+        before { template.stub(forgery_protection_strategy: double('CSRF')) }
+
+        its(:params) { should include authenticity_token: "ABCDEFGHIJ" }
+      end
+
+      context "when CSRF protection is disabled" do
+        its(:params) { should_not include authenticity_token: "ABCDEFGHIJ" }
+      end
+    end
+  end
+
+  describe '#remote?' do
+    it 'should be true if options[:remote] is set to true' do
+      described_class.new(template, query, :pie, remote: true).should be_remote
+    end
+
+    it 'should be true if the query has not been run yet' do
+      query.stub(run?: false)
+      described_class.new(template, query, :pie).should_be_remote
+    end
+
+    it 'should be false otherwise' do
+      described_class.new(template, query, :pie).should_not be_remote
+    end
   end
 end

data/spec/query_spec.rb

@@ -49,6 +49,43 @@ describe Compendium::Query do
       query = described_class.new(:blank, {}, nil)
       query.run(nil).should be_empty
     end
+
+    it "should filter the result set if a filter is provided" do
+      query.add_filter(-> data { data.reject(&:odd?) })
+      query.run(nil).should == [2]
+    end
+
+    it "should run multiple filters if given" do
+      query.add_filter(-> data { data.reject(&:odd?) })
+      query.add_filter(-> data { data.reject(&:even?) })
+      query.run(nil).should == []
+    end
+
+    context "when the query belongs to a report class" do
+      let(:report) do
+        Class.new(Compendium::Report) do
+          query(:test) { [1, 2, 3] }
+        end
+      end
+
+      subject { report.queries[:test] }
+
+      before { described_class.any_instance.stub(:fetch_results) { |c| c } }
+
+      it "should return its results" do
+        subject.run(nil).should == [1, 2, 3]
+      end
+
+      it "should not affect the report" do
+        subject.run(nil)
+        report.queries[:test].results.should be_nil
+      end
+
+      it "should not affect future instances of the report" do
+        subject.run(nil)
+        report.new.queries[:test].results.should be_nil
+      end
+    end
   end
 
   describe "#nil?" do
@@ -65,9 +102,10 @@ describe Compendium::Query do
     let(:template) { double("Template") }
     subject { described_class.new(:test, {}, -> * {}) }
 
-    it "should return nil if the query has no results" do
+    it "should initialize a new Chart presenter if the query has no results" do
       subject.stub(empty?: true)
-      subject.render_chart(template).should be_nil
+      Compendium::Presenters::Chart.should_receive(:new).with(template, subject).and_return(double("Presenter").as_null_object)
+      subject.render_chart(template)
     end
 
     it "should initialize a new Chart presenter if the query has results" do
@@ -92,4 +130,15 @@ describe Compendium::Query do
       subject.render_table(template)
     end
   end
+
+  describe "#url" do
+    let(:report) { double("Report") }
+    subject { described_class.new(:test, {}, ->{}) }
+    before { subject.report = report }
+
+    it "should build a URL using its report's URL" do
+      report.should_receive(:url).with(query: :test)
+      subject.url
+    end
+  end
 end

data/spec/report_spec.rb

@@ -28,6 +28,11 @@ describe Compendium::Report do
     its(:metrics) { should_not equal report2.metrics }
   end
 
+  describe ".name" do
+    subject { TestReport = Class.new(described_class) }
+    its(:name) { should == :test }
+  end
+
   describe "#run" do
     context do
       let(:report_class) do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: compendium
 version: !ruby/object:Gem::Version
-  version: 1.0.7
+  version: 1.1.0
 platform: ruby
 authors:
 - Daniel Vandersluis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-03 00:00:00.000000000 Z
+date: 2014-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   type: :runtime
@@ -102,6 +102,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -129,7 +130,6 @@ files:
 - config/locales/en.yml
 - lib/compendium.rb
 - lib/compendium/abstract_chart_provider.rb
-- lib/compendium/chart_provider/amcharts.rb
 - lib/compendium/collection_query.rb
 - lib/compendium/context_wrapper.rb
 - lib/compendium/dsl.rb

data/lib/compendium/chart_provider/amcharts.rb

@@ -1,20 +0,0 @@
-module Compendium
-  module ChartProvider
-    # Uses the amcharts.rb gem to provide charting
-    class AmCharts < Compendium::AbstractChartProvider
-      def initialize(type, data, &setup_proc)
-        @chart = chart_class(type).new(data, &setup_proc)
-      end
-
-      def render(template, container)
-        template.amchart(chart, container)
-      end
-
-    private
-
-      def chart_class(type)
-        ::AmCharts::Chart.const_get(type.to_s.titlecase)
-      end
-    end
-  end
-end