ReportsAsSparkline enables you to generate reports and sparklines from your model’s data with very little effort.
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 (one of :count, :sum, :minimum, :maximum or :average); when using anything other than :count, :value_column must also be specified (If you really want to e.g. sumon the ‘id’ column, you have to explicitely say so.)
-
: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 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
To achieve best 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])"
-
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 simplabs.lighthouseapp.com/projects/21060-reportsassparkline/overview.
© 2008-2009 Martin Kavalar, Marco Otte-Witte (simplabs.com/#projects), released under the MIT license