Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Ruby-based report generation/presentation Rails engine.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
app
config
lib
script
spec
.gitignore
.rspec
Gemfile
Gemfile.lock
MIT-LICENSE
README.markdown
Rakefile
dossier.gemspec

README.markdown

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.

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.

Basic Usage

Reports

In your app, create report classes under app/reports, 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:

# 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

Any symbols in the query will be replaced by calling methods of the same name in the report.

# app/reports/fancy_ketchup_report.rb
class FancyKetchupReport < Dossier::Report
  def sql
    'SELECT * FROM ketchups WHERE brand = :brand'
  end

  def brand
    'Acme'
  end
end

To see a report with all the bells and whistles, check out spec/support/reports/employee_report.rb.

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.

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:

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:

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.

formatter.url_helpers.edit_accounts_path(3)

Running the Tests

  • Run bundle
  • cp spec/dummy/config/database.yml{.example,} and edit it so that it can connect to the test database.
  • cd spec/dummy; rake db:create db:schema:load; cd -;
  • rspec spec

TODO - Moar Dokumentationz pleaze

  • Document using hooks and what methods are available in them
  • params => options
  • using models with reports
  • generating sql with scopes
    • with AREL
  • callbacks
    • stored procedures
    • reformat results
  • custom views
    • custom options
    • form_for @report
  • Bound parameters vs interpolation
  • linking to reports
    • linking to formats
  • using reports outside of Dossier::ReportsController
    • APIs
    • Exports
  • Extending the formatter
Something went wrong with that request. Please try again.