Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
rails plugin for easy generation of sparklines based on your models
branch: master

This branch is 12 commits ahead, 27 commits behind marcoow:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
doc
generators/reports_as_sparkline_migration
lib/simplabs
spec
.gitignore
HISTORY.rdoc
MIT-LICENSE
README.rdoc
Rakefile
init.rb
install.rb
uninstall.rb

README.rdoc

ReportsAsSparkline

ReportsAsSparkline enables you to generate sparkline reports 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 over that the records are aggregated (defaults to created_at)

  • :value_column - The name of the column that holds the values to sum up when using 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. sum up the values in the id column, you have to explicitely say so.); (defaults to :count)

  • :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 reporting periods to get (see :grouping), (defaults to 100)

  • :conditions - Conditions like in ActiveRecord::Base#find; only records that match the conditions are reported; Beware that when conditions are specified, caching is disabled!

  • :live_data - Specifies whether data for the current reporting period is to be 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)

  • :end_date - When specified, the report will only include data for the :limit reporting periods until this date.

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); Beware that reports_as_sparkline treats weeks as starting on monday!

  • :limit - The number of reporting periods to get (see :grouping), (defaults to 100)

  • :conditions - Conditions like in ActiveRecord::Base#find; only records that match the conditions are reported; Beware that when conditions are specified, caching is disabled!

  • :live_data - Specifies whether data for the current reporting period is to be 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)

  • :end_date - When specified, the report will only include data for the :limit reporting periods until this date.

Example:

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

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)

  • labels - 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/marcoow/reports_as_sparkline.git

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

git clone git://github.com/marcoow/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 achieve best performance, you should add indices to your tables on the date columns that are used for grouping the records (see Simplabs::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

  • Limit number of data points to maximum that the google chart api allows

  • Make graph styling configurable

If you want to suggest any new features or report bugs, do so at github.com/marcoow/reports_as_sparkline/issues.

Contributors

Author

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

Something went wrong with that request. Please try again.