tricle 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c0460bda7f826c939acd97c2e0334932b9f0ea64
-  data.tar.gz: 2d54ea7afaa2b7de1d75f281a4a875ebf3096501
+  metadata.gz: a0a773a86cbdcd4e1c093bd098e1a79d450e7e73
+  data.tar.gz: 47963dbca244c39651964fd6516c5847d1e79e57
 SHA512:
-  metadata.gz: 0578353886fe5153797d77ef3082e2e90a741812a0381fa1e14844d865a23ec967f3ccfc169032317cff2e8b9d073b86fdccf5950aefea051be67c6bb14b6e88
-  data.tar.gz: be52787ddabd878a279254dcee7e529b7f300cdcac285cbfb89a652ee85d87f21bcd0dfee2e6760cf454ebcefa1f8cfe1a7d2a5d04d830872a7e7a38663c0e7e
+  metadata.gz: 5948b2159e96493cb19eeb3f0de03be23f941749a8ceb13ccb9c84169ce999de99ae5fe06a53db30ac3205cf1a090e6db1b5992a743bafd05c75046de8ef97ba
+  data.tar.gz: 544c67eb18aa0beaad093f4f04dab5ee7a42f2bbef03824e8d8fec9090ec796c4579e1bb8f041d0283fd8264d73486e0c9693518f9c9848cb89d72574ebef85e

data/README.md

@@ -1,6 +1,6 @@
 # Tricle [![Build Status](https://travis-ci.org/afeld/tricle.png?branch=master)](https://travis-ci.org/afeld/tricle) [![Code Climate](https://codeclimate.com/github/afeld/tricle.png)](https://codeclimate.com/github/afeld/tricle)
 
-Automated metrics reporting via email.  It's datastore-agnostic, so you can query SQL, MongoDB, external APIs, etc. to generate the stats you need.  See [here](https://github.com/afeld/tricle-afeld) for an example implementation ([live demo](http://tricle.afeld.me/weekly_metrics)).
+Automated metrics reporting via email.  It's datastore-agnostic, so you can query SQL, MongoDB, external APIs, etc. to generate the stats you need.  See [here](https://github.com/afeld/tricle-afeld) for an example implementation ([live demo](http://tricle.afeld.me/weekly_metrics)). Uses [sparkle](https://github.com/afeld/sparkle) for generating sparklines.
 
 ![screenshot](screenshot.png)
 
@@ -77,38 +77,41 @@ class MyMetric < Tricle::Metric
 end
 ```
 
-ActiveRecord example:
+If you would like finer-grain optimization, the methods included from the [`Aggregation`](lib/tricle/arregation.rb) mixin can be overridden.
+
+### ActiveRecord Metrics
+
+You can inherit from [`Tricle::ActiveRecordMetric`](lib/tricle/active_record_metric.rb) for even easier setup. By default, Tricle looks for records with a `created_at` timestamp between the `start_at` and `end_at` times.
 
 ```ruby
 # app/metrics/new_users.rb
-class NewUsers < Tricle::Metric
-
-  def size_for_range(start_at, end_at)
-    self.items_for_range(start_at, end_at).count
-  end
+class NewUsers < Tricle::ActiveRecordMetric
 
-  def total
-    self.users.count
+  # Apply any default scopes you need
+  def items
+    User.where(deleted_at: nil)
   end
 
-  def items_for_range(start_at, end_at)
-    self.users.where('created_at >= ? AND created_at < ?', start_at, end_at)
-  end
+end
+```
 
+You can also override the `time_column` method to split the time intervals based on that value. For example, to see records that have been updated:
 
-  private
+```ruby
+# app/metrics/new_users.rb
+class NewUsers < Tricle::ActiveRecordMetric
 
-  # You can add whatever helper methods in that class that you need.
-  def users
-    # non-deleted Users
+  def items
     User.where(deleted_at: nil)
   end
 
+  def column
+    'updated_at'
+  end
+
 end
 ```
 
-If you would like finer-grain optimization, the methods included from the [`Aggregation`](lib/tricle/arregation.rb) mixin can be overridden.
-
 #### "Lower is better" metrics
 
 By default, Tricle highlights numbers that increased in green, and those that decreased in red. If you have a metric where a *lower* number is considered better, you'll want to override the `#better` method so Tricle highlights your cells properly:
@@ -229,6 +232,16 @@ bundle exec rake tricle:preview
 open http://localhost:8080
 ```
 
+### Global Configuration
+
+To set global configuration options, in an initializer:
+
+```ruby
+Tricle.configure do |c|
+  c.sparklines = false # default: true
+end
+```
+
 ## Deploying
 
 To send all Tricle emails, run

data/lib/tricle.rb

@@ -1,4 +1,5 @@
 # only the files needed publicly
 require_relative 'tricle/version'
+require_relative 'tricle/configuration'
 require_relative 'tricle/metric'
 require_relative 'tricle/mailer'

data/lib/tricle/active_record_metric.rb

@@ -0,0 +1,29 @@
+require_relative 'metric'
+
+module Tricle
+  class ActiveRecordMetric < Metric
+    def items
+      options[:items] || raise(Tricle::AbstractMethodError.new)
+    end
+
+    def time_column
+      options[:time_column] || 'created_at'
+    end
+
+    def unit
+      options[:unit] || 'record'
+    end
+
+    def size_for_range(start_at, end_at)
+      items.where("#{time_column}" => start_at..end_at).count
+    end
+
+    def items_for_range(start_at, end_at)
+      items.where("#{time_column}" => start_at..end_at)
+    end
+
+    def total
+      items.count
+    end
+  end
+end

data/lib/tricle/configuration.rb

@@ -0,0 +1,17 @@
+module Tricle
+  class Configuration
+    attr_accessor :sparklines
+
+    def initialize
+      @sparklines = true
+    end
+  end
+
+  def self.configure
+    yield self.configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+end

data/lib/tricle/email_helper.rb

@@ -3,6 +3,8 @@ require 'active_support/core_ext/numeric/time'
 
 module Tricle
   module EmailHelper
+    include ActiveSupport::Inflector
+
     def weeks_ago(n)
       Date.today.beginning_of_week.ago(n.weeks)
     end
@@ -11,8 +13,9 @@ module Tricle
       date.strftime('%-m/%-d/%y')
     end
 
-    def format_number(number)
-      number_with_delimiter((number.abs >= 100 ? number.round : sig_figs(number)))
+    def format_number(number, unit = nil)
+      number_with_delimiter(if number.abs >= 100 then number.round else sig_figs(number) end) +
+      (if unit then ' ' + unit.pluralize(number.abs) else '' end)
     end
 
     def number_with_delimiter(number)
@@ -50,10 +53,10 @@ module Tricle
       end
     end
 
-    def percent_change_cell(new_val, old_val, better)
+    def percent_change_cell(new_val, old_val, better, unit)
       cls = self.percent_change_class(new_val, old_val, better)
       pct_str = percent_change(new_val, old_val)
-      old_val_str = format_number(old_val)
+      old_val_str = format_number(old_val, unit)
       %[<td class="#{cls}"><div>#{pct_str}</div><div>#{old_val_str}</div></td>].html_safe
     end
 

data/lib/tricle/metric.rb

@@ -14,6 +14,18 @@ module Tricle
       @options = opts
     end
 
+    def sparkline?
+      if options.key?(:sparkline)
+        options[:sparkline]
+      else
+        Tricle.configuration.sparklines
+      end
+    end
+
+    def unit
+      options[:unit]
+    end
+
     def better
       options[:better] || :higher
     end

data/lib/tricle/templates/email.html.erb

@@ -30,20 +30,22 @@
           <% section.metrics.each do |metric| %>
             <tr>
               <th class="metric-title" rowspan="2"><%= metric.title %></th>
-              <%= percent_change_cell(metric.last_week, metric.week_average_this_quarter, metric.better) %>
-              <%= percent_change_cell(metric.last_week, metric.weeks_ago(2), metric.better) %>
+              <%= percent_change_cell(metric.last_week, metric.week_average_this_quarter, metric.better, metric.unit) %>
+              <%= percent_change_cell(metric.last_week, metric.weeks_ago(2), metric.better, metric.unit) %>
               <td>
-                <div><%= format_number(metric.last_week) %></div>
+                <div><%= format_number(metric.last_week, metric.unit) %></div>
                 <% if metric.total? %>
                   <div><%= format_number(metric.total) %> (total)</div>
                 <% end %>
               </td>
             </tr>
-            <tr>
-              <td colspan="3">
-                <%= sparkline(metric) %>
-              </td>
-            </tr>
+            <% if metric.sparkline? %>
+              <tr>
+                <td colspan="3">
+                  <%= sparkline(metric) %>
+                </td>
+              </tr>
+            <% end %>
             <tr class="separator"></tr>
           <% end %>
         <% end %>

data/lib/tricle/version.rb

@@ -1,3 +1,3 @@
 module Tricle
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 end

data/script/release

@@ -0,0 +1,38 @@
+#!/bin/sh
+# Tag and push a release.
+
+set -e
+
+# Make sure we're in the project root.
+
+cd $(dirname "$0")/..
+
+# Build a new gem archive.
+
+rm -rf tricle-*.gem
+gem build -q tricle.gemspec
+
+# Make sure we're on the master branch.
+
+(git branch | grep -q '* master') || {
+  echo "Only release from the master branch."
+  exit 1
+}
+
+# Figure out what version we're releasing.
+
+tag=v`ls tricle-*.gem | sed 's/^tricle-\(.*\)\.gem$/\1/'`
+
+# Make sure we haven't released this version before.
+
+git fetch -t origin
+
+(git tag -l | grep -q "$tag") && {
+  echo "Whoops, there's already a '${tag}' tag."
+  exit 1
+}
+
+# Tag it and bag it.
+
+gem push tricle-*.gem && git tag "$tag" &&
+  git push origin master && git push origin "$tag"

data/spec/app/test_active_record_metric.rb

@@ -0,0 +1,12 @@
+require_relative '../../lib/tricle/active_record_metric'
+
+class TestActiveRecordMetric < Tricle::ActiveRecordMetric
+  def initialize(opts = {})
+    @klass = opts.delete(:klass)
+    super(opts)
+  end
+
+  def items
+    @klass.where(foo: 'bar')
+  end
+end

data/spec/spec_helper.rb

@@ -15,6 +15,8 @@ require_relative 'config/timecop'
 # TODO find a less heavy-handed way of handling this
 reset_time
 
+require 'tricle'
+
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 RSpec.configure do |config|
   config.run_all_when_everything_filtered = true

data/spec/unit/email_helper_spec.rb

@@ -67,6 +67,13 @@ describe Tricle::EmailHelper do
       expect(helper.format_number(0.00123456789)).to eq('0.00123')
       expect(helper.format_number(-0.00123456789)).to eq('-0.00123')
     end
+
+    it "can include units" do
+      expect(helper.format_number(0.00123456789, 'juice')).to eq('0.00123 juices')
+      expect(helper.format_number(1.0, 'juice')).to eq('1.0 juice')
+      expect(helper.format_number(-1, 'juice')).to eq('-1.0 juice')
+      expect(helper.format_number(-1, 'juice')).to eq('-1.0 juice')
+    end
   end
 
   describe "#percent_change" do
@@ -99,16 +106,16 @@ describe Tricle::EmailHelper do
 
   describe '#percent_change_cell' do
     it "should be positive with positive change and better = :higher" do
-      expect(helper.percent_change_cell(4, 2, :higher)).to match('good')
+      expect(helper.percent_change_cell(4, 2, :higher, nil)).to match('good')
     end
 
     it "should be negative with positive change and better = :lower" do
-      expect(helper.percent_change_cell(4, 2, :lower)).to match('bad')
+      expect(helper.percent_change_cell(4, 2, :lower, nil)).to match('bad')
     end
 
     it "should not be positive or negative with positive change and better = :none" do
-      expect(helper.percent_change_cell(4, 2, :none)).to_not match('good')
-      expect(helper.percent_change_cell(4, 2, :none)).to_not match('bad')
+      expect(helper.percent_change_cell(4, 2, :none, nil)).to_not match('good')
+      expect(helper.percent_change_cell(4, 2, :none, nil)).to_not match('bad')
     end
   end
 

data/spec/unit/mailer_spec.rb

@@ -39,6 +39,10 @@ describe Tricle::Mailer do
       source = message.text_part.body.to_s
       expect(source).to include('github.com/artsy/tricle')
     end
+
+    it "includes sparklines by default" do
+      expect(markup).to include('sparklines.herokuapp.com')
+    end
   end
 
   it "should exclude the total if not defined" do

data/spec/unit/metric_spec.rb

@@ -15,4 +15,21 @@ describe Tricle::Metric do
       expect(metric.size_for_range(Time.now.yesterday, Time.now)).to eq(3)
     end
   end
+
+  describe '#sparkline?' do
+    it 'defaults to Tricle.configuration' do
+      expect(Tricle).to receive_message_chain(:configuration, :sparklines).
+        and_return(false)
+
+      expect(metric.sparkline?).to eq false
+    end
+
+    context 'with options override' do
+      let(:sparkline_metric) { Tricle::Metric.new(sparkline: true) }
+
+      it 'ignores Tricle.configuration' do
+        expect(sparkline_metric.sparkline?).to eq true
+      end
+    end
+  end
 end

data/spec/unit/test_active_record_metric_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+require_relative '../app/test_active_record_metric'
+
+describe TestActiveRecordMetric do
+  let(:klass) { class_double('User') }
+  let(:metric) { TestActiveRecordMetric.new(klass: klass) }
+  let!(:start_time) { Time.now }
+  let!(:end_time) { start_time - 1.day }
+
+  describe '#total' do
+    it 'executes a #count query' do
+      expect(klass).to receive_message_chain(:where, :count).and_return(1)
+      expect(metric.total).to eq 1
+    end
+  end
+
+  describe '#size_for_range' do
+    it 'executes a #count query with the correct filters' do
+      # These stubs are ugly, but we want to test the arguments received
+      # to the method called in the middle of the message chain...
+      expect(klass).to receive(:where).and_return(klass)
+      expect(klass).to receive(:where).
+                        with('created_at' => start_time..end_time).
+                        and_return(klass)
+      expect(klass).to receive(:count).and_return(1)
+      expect(metric.size_for_range(start_time, end_time)).to eq 1
+    end
+  end
+
+  describe '#items_for_range' do
+    it 'executes a query with the correct filters' do
+      expect(klass).to receive(:where).and_return(klass)
+      expect(klass).to receive(:where).
+                        with('created_at' => start_time..end_time).
+                        and_return(['foobar'])
+      expect(metric.items_for_range(start_time, end_time)).to eq ['foobar']
+    end
+  end
+
+  describe 'overriding the time_column' do
+    before do
+      allow(metric).to receive(:time_column).and_return('updated_at')
+    end
+
+    it 'executes a query with the correct filters' do
+      expect(klass).to receive(:where).and_return(klass)
+      expect(klass).to receive(:where).
+                        with('updated_at' => start_time..end_time).
+                        and_return(['fuzz'])
+      expect(metric.items_for_range(start_time, end_time)).to eq ['fuzz']
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tricle
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Aidan Feldman
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-09 00:00:00.000000000 Z
+date: 2014-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionmailer
@@ -115,7 +115,9 @@ files:
 - gemfiles/rails_4.gemfile
 - lib/tricle.rb
 - lib/tricle/abstract_method_error.rb
+- lib/tricle/active_record_metric.rb
 - lib/tricle/aggregation.rb
+- lib/tricle/configuration.rb
 - lib/tricle/email_helper.rb
 - lib/tricle/mail_preview.rb
 - lib/tricle/mailer.rb
@@ -132,10 +134,12 @@ files:
 - lib/tricle/time.rb
 - lib/tricle/version.rb
 - screenshot.png
+- script/release
 - spec/app/group_test_mailer.rb
 - spec/app/list_test_mailer.rb
 - spec/app/list_test_mailer_with_options.rb
 - spec/app/no_total_test_mailer.rb
+- spec/app/test_active_record_metric.rb
 - spec/app/test_mailer.rb
 - spec/app/test_metric.rb
 - spec/app/test_metric_with_long_name.rb
@@ -154,6 +158,7 @@ files:
 - spec/unit/mailer_spec.rb
 - spec/unit/metric_spec.rb
 - spec/unit/range_data_spec.rb
+- spec/unit/test_active_record_metric_spec.rb
 - spec/unit/test_metric_spec.rb
 - tricle.gemspec
 homepage: https://github.com/artsy/tricle
@@ -176,7 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.1
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: A datastore-agnostic mailer where you can define custom metrics, where you
@@ -187,6 +192,7 @@ test_files:
 - spec/app/list_test_mailer.rb
 - spec/app/list_test_mailer_with_options.rb
 - spec/app/no_total_test_mailer.rb
+- spec/app/test_active_record_metric.rb
 - spec/app/test_mailer.rb
 - spec/app/test_metric.rb
 - spec/app/test_metric_with_long_name.rb
@@ -205,4 +211,6 @@ test_files:
 - spec/unit/mailer_spec.rb
 - spec/unit/metric_spec.rb
 - spec/unit/range_data_spec.rb
+- spec/unit/test_active_record_metric_spec.rb
 - spec/unit/test_metric_spec.rb
+has_rdoc: