<commit_before>= ReportsAsSparkline

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

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

The CI server is at http://ci.saulabs.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:

* <tt>:date_column</tt> - The name of the date column over that the records are aggregated (defaults to <tt>created_at</tt>)
* <tt>:value_column</tt> - The name of the column that holds the values to sum up when using aggregation <tt>:sum</tt>
* <tt>:aggregation</tt> - The aggregation to use (one of <tt>:count</tt>, <tt>:sum</tt>, <tt>:minimum</tt>, <tt>:maximum</tt> or <tt>:average</tt>); when using anything other than <tt>:count</tt>, <tt>:value_column</tt> must also be specified (<b>If you really want to e.g. sum up the values in the <tt>id</tt> column, you have to explicitely say so.</b>); (defaults to <tt>:count</tt>)
* <tt>:grouping</tt> - The period records are grouped on (<tt>:hour</tt>, <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt>); <b>Beware that <tt>reports_as_sparkline</tt> treats weeks as starting on monday!</b>
* <tt>:limit</tt> - The number of reporting periods to get (see <tt>:grouping</tt>), (defaults to 100)
* <tt>:conditions</tt> - Conditions like in <tt>ActiveRecord::Base#find</tt>; only records that match the conditions are reported
* <tt>:live_data</tt> - Specifies whether data for the current reporting period is to be read; <b>if <tt>:live_data</tt> is <tt>true</tt>, you will experience a performance hit since the request cannot be satisfied from the cache only (defaults to <tt>false</tt>)</b>
* <tt>:end_date</tt> - When specified, the report will only include data for the <tt>:limit</tt> reporting periods until this date.

<b>Example:</b>

  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+:

* <tt>:grouping</tt> - The period records are grouped on (<tt>:hour</tt>, <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt>); <b>Beware that <tt>reports_as_sparkline</tt> treats weeks as starting on monday!</b>
* <tt>:limit</tt> - The number of reporting periods to get (see <tt>:grouping</tt>), (defaults to 100)
* <tt>:conditions</tt> - Conditions like in <tt>ActiveRecord::Base#find</tt>; only records that match the conditions are reported
* <tt>:live_data</tt> - Specifies whether data for the current reporting period is to be read; <b>if <tt>:live_data</tt> is <tt>true</tt>, you will experience a performance hit since the request cannot be satisfied from the cache only (defaults to <tt>false</tt>)</b>
* <tt>:end_date</tt> - When specified, the report will only include data for the <tt>:limit</tt> reporting periods until this date.

<b>Example:</b>

  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 <tt>Saulabs::ReportsAsSparkline::ReportCache</tt> class.
<b>Beware that when you modify data in the cache, report results may be incorrect or execurting reports may even fail completely!</b> To clear the cache for a specific report, use the <tt>Saulabs::ReportsAsSparkline::ReportCache.clear_for</tt>
method.

<b>Example</b>

For a report defined as

  class User < ActiveRecord::Base
    reports_as_sparkline :registrations
  end

you can clear the cache with

  Saulabs::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:

* <tt>width</tt> - The width of the generated image
* <tt>height</tt> - The height of the generated image
* <tt>line_color</tt> - The line color of the sparkline (hex code)
* <tt>fill_color</tt> - The color to fill the area below the sparkline with (hex code)
* <tt>labels</tt> - The axes to render lables for (Array of <tt>:x</tt>, <tt>:y+</tt>, <tt>:r</tt>, <tt>:t</tt>; this is x axis, y axis, right, top)

== Installation

Installation requires 3 simple steps:

<b>get the plugin</b>

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

<b>generate migration</b>

  ./script/generate reports_as_sparkline_migration add_reports_as_sparkline_tables

<b>migrate</b>

  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 Saulabs::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.

<b>Example</b>

  <%- 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 http://github.com/marcoow/reports_as_sparkline/issues.

== Contributors

* myronmarston (http://github.com/myronmarston)
* jan (http://github.com/jan)
* eric (http://github.com/eric)

== Author

© 2008-2010 <NAME> (http://saulabs.com), <NAME>, released under the MIT license<commit_msg>change README to make clear this is not a fork of ReportsAsSparkline<commit_after>= Reportable

Former ReportsAsSparkline; expect new features, cleaner code etc. in the next weeks
{'fraction_non_alphanumeric': 0.12445351209559895, 'fraction_numerical': 0.0030603322646458758, 'mean_word_length': 5.030755711775044, 'pattern_counts': {'":': 0, '<': 152, '<?xml version=': 0, '>': 159, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1615789', 'n_tokens_mistral': 2221, 'n_tokens_neox': 2109, 'n_words': 774}