Home

ReportsAsSparkline

ReportsAsSparkline enables you to generate reports and sparklines from your model’s data with very little effort.

Usage

If you hace a User model with created_at and activated_at columns, you can just add reports_as_sparkline
to it with the following options:

• :date_column – The name of the date column on that the records are aggregated
• :value_column – The name of the column that holds the value to sum for aggregation :sum
• :aggregation – The aggregation to use (either :count or :sum); when using :sum, :value_column must also be specified
• :grouping – The period records are grouped on (:hour, :day, :week, :month) Beware that reports_as_sparkline treats weeks as starting on monday!
• :limit – The number of periods to get (see :grouping)
• :conditions – Conditions like in ActiveRecord::Base#find; only records that match there conditions are reported on
• :cumulate – Sets whether to cumulate the numbers (instead of [1, 2, 3] returns [1, 3, 6])
• :live_data – Specified whether data for the current reporting period is read; if :live_data is true, you will experience a performance hit since the request cannot be satisfied from the cache only (defaults to false)

Example

  class User < ActiveRecord::Base
    reports_as_sparkline :registrations
    reports_as_sparkline :activations,  :date_column => :activated_at
    reports_as_sparkline :total_users,  :cumulate    => true
  end

This will add the following class methods to your User model:

  User.registrations_report
  User.activations_report
  User.total_users_report

When invoking the report, you can override some of the options you specified for reports_as_sparkline:

• :grouping – The period records are grouped on (:hour, :day, :week, :month)
• :limit – The number of periods to get (see :grouping)
• :conditions – Conditions like in ActiveRecord::Base#find; only records that match there conditions are reported on
• :live_data – Specified whether data for the current reporting period is read; if :live_data is true, you will experience a performance hit since the request cannot be satisfied from the cache only (defaults to false)

Example

  User.registrations_report(:conditions => ['last_name LIKE 'A%'])
  User.activations_report(:grouping => :week, :limit => 5)

Beware that when specifying conditions on invocation of the report, the cache will not be used!

You can than render sparklines for these reports with sparkline_tag in your view:

  <%= sparkline_tag(User.registrations_report) %>

The sparkline_tag helper takes the following parameters:

• :width – The width of the generated image
• :height – The height of the generated image
• :line_color – The line color of the sparkline (hex code)
• :fill_color – The color to fill the area below the sparkline with (hex code)
• :labes – The axes to render lables for (Array of :x, :y, :r, :t; this is x axis, y axis, right, top)

Installation

Installation requires 3 simple steps:

get the plugin

From your RAILS_ROOT in Rails >= 2.1, do

  ./script/plugin install git://github.com/mk/reports_as_sparkline.git

If you are on Rails < 2.1, do this from your RAILS_ROOT

  git clone git://github.com/mk/reports_as_sparkline.git vendor/plugins/reports_as_sparkline

generate migration

  ./script/generate reports_as_sparkline_migration add_reports_as_sparkline_tables

migrate

  rake db:migrate

Performance

To get the best possible performance, you should add indices to your tables on the date columns that are
used for grouping the records (see Kvlr::ReportsAsSparkline::ClassMethods.reports_as_sparkline):

  add_index :[table], :[date_column]

If you are on PostgreSQL, you should add functional indices:

  add_index :[table], :[date_column], :functional => "date_trunc('hour', [date_column])"
  add_index :[table], :[date_column], :functional => "date_trunc('day',  [date_column])"
  add_index :[table], :[date_column], :functional => "date_trunc('week', [date_column])"
  add_index :[table], :[date_column], :functional => "date_trunc('year', [date_column])"

TODOs/ future plans

• support for Oracle and DB2 (and others?) missing
• Implement data ranges in arguments
• Limit number of data points to maximum that the google chart api allows
• Make graph styling configurable

If you want ot suggest any new features or report bugs, do so at http://simplabs.lighthouseapp.com/projects/21060-reportsassparkline/overview.

© 2008-2009 Martin Kavalar, Marco Otte-Witte (http://simplabs.com/#projects), released under the MIT license