dossier 2.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 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.markdown

@@ -0,0 +1,181 @@
+# Dossier
+
+Dossier is a Rails engine that turns SQL into reports. Reports can be easily rendered in various formats, like HTML, CSV, and JSON. The SQL can be written by hand or generated by another tool, like ActiveRecord.
+
+## Setup
+
+Install the Dossier gem and create `config/dossier.yml`. This has the same format as Rails' `database.yml`, and can actually just be a symlink: `ln -s config/{database,dossier}.yml`.
+
+## Routing
+
+Dossier will add a route to your app so that `reports/fancy_ketchup` will instantiate and run a `FancyKetchupReport`. It will respond with whatever format was requested; for example `reports/fancy_ketchup.csv` will render the results as CSV.
+
+## Basic Reports
+
+In your app, create report classes under `app/reports`, with `Report` as the end of the class name. Define a `sql` method that returns the sql string to be sent to the database.
+
+For example:
+
+```ruby
+# app/reports/fancy_ketchup_report.rb
+class FancyKetchupReport < Dossier::Report
+  def sql 
+    'SELECT * FROM ketchups WHERE fancy = true'
+  end
+
+  # Or, if you're using ActiveRecord and hate writing SQL:
+  def sql 
+    Ketchup.where(fancy: true).to_sql
+  end
+
+end
+```
+
+If you need dynamic values that may be influenced by the user, [do not interpolate them directly](http://xkcd.com/327/). Dossier provides a safer way to add them: any symbols in the query will be replaced by calling methods of the same name in the report. Return values other than numerics will be coerced to strings and **escaped by the database**.
+  
+```ruby
+# app/reports/fancy_ketchup_report.rb
+class FancyKetchupReport < Dossier::Report
+  def sql
+    'SELECT * FROM ketchups WHERE brand = :brand'
+  end
+
+  def brand
+    'Acme'
+  end
+end
+```
+
+## Column Formatting
+
+You can format any values in your results by defining a `format_` method for that column on your report class. For instance, to reverse the names of your employees:
+
+```ruby
+class EmployeeReport < Dossier::Report
+  # ...
+  def format_name(value)
+    value.reverse
+  end
+end
+```
+
+Dossier also provides a `formatter` with access to all the standard Rails formatters. So to format all values in the `payment` column as currency, you could do:
+
+```ruby
+class MoneyLaunderingReport < Dossier::Report
+  #...
+  def format_payment(value)
+    formatter.number_to_currency
+  end
+end
+```
+
+In addition, the formatter provides Rails' URL helpers for use in your reports. For example, in a report of your least profitable accounts, you might want to add a link to change the salesperson assigned to that account.
+
+```ruby
+formatter.url_helpers.edit_accounts_path(3)
+```
+
+The built-in `ReportsController` uses this formatting when rendering the HTML and JSON representations, but not when rendering the CSV.
+
+## Report Options and Footers
+
+You may want to specify parameters for a report: which columns to show, a range of dates, etc. Dossier supports this via URL parameters, which will be passed into your report's `initialize` method and made available via the `options` reader.
+
+You can pass these options by hardcoding them into a link, or you can allow users to customize a report with a form. For example:
+
+```ruby
+# app/views/dossier/reports/employee.html.haml
+
+= form_for report, as: :options, url: url_for, html: {method: :get} do |f|
+
+  = f.label "Salary greater than:"
+  = f.text_field :salary_greater_than
+  = f.label "In Division:"
+  = f.select_tag :in_division, divisions_collection
+  = f.button "Submit"
+
+= render template: 'dossier/dossier/reports/show', locals: {report: report}
+```
+
+It's up to you to use these options in generating your SQL query. 
+
+However, Dossier does support one URL parameter natively: if you supply a `footer` parameter with an integer value, the last N rows will be accesible via `report.results.footers` instead of `report.results.body`. The built-in `show` view renders those rows inside an HTML footer. This is an easy way to display a totals row or something similar.
+
+## Additional View Customization
+
+To further customize your results view, provide your own `app/views/dossier/reports/show`.
+
+## Callbacks
+
+To produce report results, Dossier builds your query and executes it in separate steps. It uses [ActiveSupport::Callbacks](http://api.rubyonrails.org/classes/ActiveSupport/Callbacks.html) to define callbacks for `build_query` and `execute`. Therefore, you may provide callbacks similar to these:
+
+```ruby
+set_callback :build_query, :before, :run_my_stored_procedure
+set_callback :execute,     :after do
+  mangle_results
+end
+```
+
+## Using Reports Outside of Dossier::ReportsController
+
+### With Other Controllers
+
+You can use Dossier reports in your own controllers and views. For example, if you wanted to render two reports on a page with other information, you might do this in a controller:
+
+```ruby
+class ProjectsController < ApplicationController
+
+  def show
+    @project                = Project.find(params[:id])
+    @project_status_report  = ProjectStatusReport.new(project: @project)
+    @project_revenue_report = ProjectRevenueReport.new(project: @project, grouped: 'monthly')
+  end
+end
+```
+
+```haml
+.span6
+  = render template: 'dossier/reports/show', locals: {report: @project_status_report.run}
+.span6
+  = render template: 'dossier/reports/show', locals: {report: @project_revenue_report.run}
+```
+
+### Dossier for APIs
+
+```ruby
+class API::ProjectsController < Api::ApplicationController
+
+  def snapshot
+    render json: ProjectStatusReport.new(project: @project).results.hashes
+  end
+end
+```
+
+## Advanced Usage
+
+To see a report with all the bells and whistles, check out `spec/support/reports/employee_report.rb`.
+
+## Running the Tests
+
+Note: when you run the tests, Dossier will **make and/or truncate** some tables in the `dossier_test` database.
+
+- Run `bundle`
+- `cp spec/dummy/config/database.yml{.example,}` and edit it so that it can connect to the test database.
+- `rspec spec`
+
+## TODO
+
+### Features
+
+- Support more databases
+
+### Moar Dokumentationz pleaze
+
+- Document using hooks and what methods are available in them
+- callbacks
+  - stored procedures
+  - reformat results
+- linking to reports
+  - linking to formats
+- Extending the formatter

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Dossier'
+  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
+

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

@@ -0,0 +1,15 @@
+// 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
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/app/assets/stylesheets/dossier/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/dossier/application_controller.rb

@@ -0,0 +1,4 @@
+module Dossier
+  class ApplicationController < ::ApplicationController
+  end
+end

data/app/controllers/dossier/reports_controller.rb

@@ -0,0 +1,34 @@
+module Dossier
+  class ReportsController < ApplicationController
+    def show
+      report = report_class.new(params[:options] || {})
+      report.run
+
+      respond_to do |format|
+        format.html do
+          begin
+            render template: "dossier/reports/#{report.view}", locals: {report: report}
+          rescue ActionView::MissingTemplate => e
+            render template: 'dossier/reports/show', locals: {report: report}
+          end
+        end
+
+        format.json do
+          render :json => report.results.hashes
+        end
+
+        format.csv do
+          headers["Content-Disposition"] = %[attachment;filename=#{params[:report]}-report_#{Time.now.strftime('%m-%d-%Y-%H%M%S')}.csv]
+          self.response_body = StreamCSV.new(report.raw_results.arrays)
+        end
+      end
+    end
+
+    private
+
+    def report_class
+      "#{params[:report].classify}Report".constantize
+    end
+
+  end
+end

data/app/helpers/dossier/application_helper.rb

@@ -0,0 +1,4 @@
+module Dossier
+  module ApplicationHelper
+  end
+end

data/app/views/dossier/reports/show.html.haml

@@ -0,0 +1,21 @@
+%h1= report.class.name.titleize
+
+%table
+  %thead
+    %tr
+      - report.results.headers.each do |header|
+        %th= Dossier::Formatter.titleize(header)
+  %tbody
+    - report.results.body.each do |row|
+      %tr
+        - row.each do |value|
+          %td= value
+
+  - if report.results.footers.any?
+    %tfoot
+      - report.results.footers.each do |row|
+        %tr
+          - row.each do |value|
+            %th= value
+
+= link_to 'Download CSV', dossier_report_path(:format => 'csv', :options => params[:options]), :class => 'download-csv'

data/config/routes.rb

@@ -0,0 +1,5 @@
+Rails.application.routes.draw do
+
+  match "reports/:report", :to => 'dossier/reports#show', :as => :dossier_report
+
+end

data/lib/dossier.rb

@@ -0,0 +1,31 @@
+require "dossier/engine"
+require "dossier/version"
+
+module Dossier
+
+  def self.configuration
+    @configuration || configure
+  end
+
+  def self.configure
+    @configuration = Configuration.new
+    yield(@configuration) if block_given?
+    @configuration
+  end
+
+  def self.client
+    configuration.client
+  end
+
+  class ExecuteError < StandardError; end
+end
+
+require "dossier/adapter/active_record"
+require "dossier/adapter/active_record/result"
+require "dossier/client"
+require "dossier/configuration"
+require "dossier/formatter"
+require "dossier/query"
+require "dossier/report"
+require "dossier/result"
+require "dossier/stream_csv"

data/lib/dossier/adapter/active_record.rb

@@ -0,0 +1,40 @@
+module Dossier
+  module Adapter
+    class ActiveRecord
+
+      attr_accessor :options, :connection
+
+      def initialize(options = {})
+        self.options    = options
+        self.connection = options.delete(:connection) || active_record_connection
+      end
+
+      def escape(value)
+        connection.quote(value)
+      end
+
+      def execute(query, report_name = nil)
+        Result.new(connection.exec_query(*[query, report_name].compact))
+      rescue => e
+        raise Dossier::ExecuteError.new "#{e.message}\n\n#{query}"
+      end
+
+      private
+
+      def active_record_connection
+        @abstract_class = Class.new(::ActiveRecord::Base) do
+          self.abstract_class = true
+          
+          # Needs a unique name for ActiveRecord's connection pool
+          def self.name
+            "Dossier::Adapter::ActiveRecord::Connection_#{object_id}"
+          end
+        end
+        @abstract_class.establish_connection(options)
+        @abstract_class.connection
+      end
+
+    end
+
+  end
+end

data/lib/dossier/adapter/active_record/result.rb

@@ -0,0 +1,24 @@
+module Dossier
+  module Adapter
+    class ActiveRecord
+      class Result
+
+        attr_accessor :result
+
+        def initialize(activerecord_result)
+          self.result = activerecord_result
+        end
+
+        def headers
+          result.columns
+        end
+
+        def rows
+          result.rows
+        end
+
+      end
+    end
+
+  end
+end

data/lib/dossier/client.rb

@@ -0,0 +1,52 @@
+module Dossier
+  class Client
+
+    attr_accessor :adapter, :options
+
+    delegate :escape, :execute, to: :adapter
+
+    def initialize(options)
+      self.options = options.symbolize_keys
+      self.adapter = dossier_adapter.new(self.options.except(:dossier_adapter))
+    end
+
+    def dossier_adapter
+      adapter_name = options.fetch(:dossier_adapter) { determine_adapter_name }
+      "Dossier::Adapter::#{adapter_name.classify}".constantize
+    end
+
+    private
+
+    def determine_adapter_name
+      if options.has_key?(:connection)
+        namespace_for(options[:connection].class)
+      else
+        guess_adapter_name
+      end
+    end
+
+    def namespace_for(klass)
+      klass.name.split('::').first.underscore
+    end
+
+    def guess_adapter_name
+      return namespace_for(loaded_orms.first) if loaded_orms.length == 1
+
+      message = <<-Must_be_one_of_them_newfangled_ones.strip_heredoc
+        You didn't specify a dossier_adapter. If you had exactly one
+        ORM loaded that Dossier knew about, it would try to choose an
+        appropriate adapter, but you have #{loaded_orms.length}.
+        Must_be_one_of_them_newfangled_ones
+      message << "Specifically, Dossier found #{loaded_orms.join(', ')}" if loaded_orms.any?
+      raise IndeterminableAdapter.new(message)
+    end
+
+    def loaded_orms
+      [].tap do |loaded_orms|
+        loaded_orms << ActiveRecord::Base if defined?(ActiveRecord)
+      end
+    end
+
+    class IndeterminableAdapter < StandardError; end
+  end
+end