Skip to content
This repository

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

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 doc
Octocat-spinner-32 generators
Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .gitignore
Octocat-spinner-32 HISTORY.rdoc
Octocat-spinner-32 MIT-LICENSE
Octocat-spinner-32 README.rdoc
Octocat-spinner-32 Rakefile
Octocat-spinner-32 init.rb
Octocat-spinner-32 install.rb
Octocat-spinner-32 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.