README.rdoc

ReportsAsSparkline¶ ↑

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

See the API docs at docs.github.com/marcoow/reports_as_sparkline.

The CI server is at ci.simplabs.com/reportsassparkline.

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)

The Report cache¶ ↑

Unless you specify parameters that make it impossible to cache report results, all results will be cached. You can access the cache via the Simplabs::ReportsAsSparkline::ReportCache class. Beware that when you modify data in the cache, report results may be incorrect or execurting reports may even fail completely! To clear the cache for a specific report, use the Simplabs::ReportsAsSparkline::ReportCache.clear_for method.

Example

For a report defined as

class User < ActiveRecord::Base
  reports_as_sparkline :registrations
end

you can clear the cache with

Simplabs::ReportsAsSparkline::ReportCache.clear_for(User, :registrations)

In your views¶ ↑

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])"

You might also want to use fragment caching in your views since processing the data read from the db (either from the model’s table or from the cache) aso takes some time.

Example

<%- cache do -%>
  <%= sparkline_tag(User.registrations_report) %>
<%- end -%>

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¶ ↑

• myronmarston (github.com/myronmarston)

Author¶ ↑

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