Compendium
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 is present, option notes will be rendered in a tooltip rather than as straight text.
- 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:
gem 'compendium'
And then execute:
$ bundle
Or install it yourself as:
$ gem install compendium
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Acknowledgments
- Special thanks to TalentNest, who sponsored this gem's development.