snogmetrics 0.1.1 → 0.1.2

data/.gitignore

@@ -15,10 +15,10 @@ tmtags
 
 ## PROJECT::GENERAL
 /coverage
-/rdoc
-/yardoc
+/doc
 /coverage
 /pkg
 /.bundle
+/.yardoc
 
 ## PROJECT::SPECIFIC

data/CHANGELOG.mdown

@@ -0,0 +1,13 @@
+# SNOGmetrics changelog
+
+## 0.1.2
+
+API documentation and a way to override the logic that determines when the stub API is used instead of the real KISSmetrics API.
+
+## 0.1.1
+
+Refactored and removed 40% of the code.
+
+## 0.1.0
+
+First release.

data/Gemfile

@@ -4,6 +4,7 @@ group :development do
   gem 'rake'
   gem 'jeweler'
   gem 'yard'
+  gem 'BlueCloth'
   gem 'rails', '>= 2.3.5'
 end
 

data/Rakefile

@@ -38,7 +38,7 @@ begin
   require 'yard'
   YARD::Rake::YardocTask.new
 rescue LoadError
-  task :yardoc do
+  task :yard do
     abort 'YARD is not available. In order to run yardoc, you must: sudo gem install yard'
   end
 end

data/lib/snogmetrics.rb

@@ -1,8 +1,26 @@
+# If SNOGmetrics is used as a Rails plugin, this module is automatically mixed 
+# into ActionController::Base, so that it's #km method is available in 
+# controllers and in views.
+#
+# If not used as a Rails plugin, make sure that the context where Snogmetrics
+# is mixed in defines #session (which should return hash).
+#
+# You should override #kissmetrics_api_key in an initializer to set the
+# KISSmetrics API key.
+#
+# You can also override #use_fake_kissmetrics_api? to provide your own logic for
+# when the real KISSmetrics API and when the fake should be used. The fake API
+# simply outputs all events to the console (if the console is defined). The
+# the default implementation outputs the real API only when 
+# `Rails.env.production?` is true.
 module Snogmetrics
-  VERSION = '0.1.1'
-  
+  VERSION = '0.1.2'
+
+  # Returns an instance of KissmetricsApi, which is an interface to the
+  # KISSmetrics API. It has the methods #record and #identify, which work just
+  # like the corresponding methods in the JavaScript API.
   def km
-    @km_api ||= KissmetricsApi.new(kissmetrics_api_key, session)
+    @km_api ||= KissmetricsApi.new(kissmetrics_api_key, session, use_fake_kissmetrics_api?)
   end
 
   # Override this method to set the KISSmetrics API key
@@ -10,14 +28,30 @@ module Snogmetrics
     ''
   end
   
+  # Override this method to customize when the real API and when the stub API
+  # will be outputted.
+  def use_fake_kissmetrics_api?
+    if defined? Rails
+      ! Rails.env.production?
+    else
+      false
+    end
+  end
+  
 private
 
   class KissmetricsApi
-    def initialize(api_key, session)
+    # Do not instantiate KissmetricsApi yourself, instead mix in Snogmetrics
+    # and use it's #km method to get an instance of KissmetricsApi.
+    def initialize(api_key, session, fake_it)
       @session = session
       @api_key = api_key
+      @fake_it = fake_it
     end
     
+    # The equivalent of the `KM.record` method of the JavaScript API. You can
+    # pass either an event name, an event name and a hash of properties, or only
+    # a hash of properties.
     def record(*args)
       raise 'Not enough arguments' if args.size == 0
       raise 'Too many arguments' if args.size > 2
@@ -25,6 +59,7 @@ private
       queue << ['record', *args]
     end
     
+    # The equivalent of the `KM.identify` method of the JavaScript API.
     def identify(identity)
       unless @session[:km_identity] == identity
         queue.delete_if { |e| e.first == 'identify' }
@@ -33,6 +68,23 @@ private
       end
     end
     
+    # Equivalent to `js(:reset => true)`, i.e. returns the JavaScript code
+    # needed to load the KISSmetrics API and send the current state, and reset
+    # the state afterwards.
+    def js!
+      js(:reset => true)
+    end
+    
+    # In most situations you want the #js! method instead of this one.
+    #
+    # Returns the JavaScript needed to send the current state to KISSmetrics.
+    # This includes the a JavaScript tag that loads the API code (or a fake API
+    # that sends events to the console if the `fake_it` parameter to #initialize
+    # is true), as well as statements that push the current state onto the 
+    # `_kmq` array.
+    #
+    # You can pass the option `:reset` to reset the state, this makes sure that
+    # subsequent calls to #js will not send events that have already been sent.
     def js(options={})
       options = {:reset => false}.merge(options)
       
@@ -52,10 +104,6 @@ private
         JAVASCRIPT
       end
     end
-    
-    def js!
-      js(:reset => true)
-    end
   
   private
   
@@ -64,9 +112,7 @@ private
     end
     
     def api_js
-      if Rails.env.production?
-        %((function(){function _kms(u,d){if(navigator.appName.indexOf("Microsoft")==0 && d)document.write("<scr"+"ipt defer='defer' async='true' src='"+u+"'></scr"+"ipt>");else{var s=document.createElement('script');s.type='text/javascript';s.async=true;s.src=u;(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(s);}}_kms('https://i.kissmetrics.com/i.js');_kms('http'+('https:'==document.location.protocol ? 's://s3.amazonaws.com/' : '://')+'scripts.kissmetrics.com/#{@api_key}.1.js',1);})();)
-      else
+      if @fake_it
         <<-JS
         var KM = {
           record: function() {
@@ -91,6 +137,8 @@ private
           })(_kmq);
         }
         JS
+      else
+        %((function(){function _kms(u,d){if(navigator.appName.indexOf("Microsoft")==0 && d)document.write("<scr"+"ipt defer='defer' async='true' src='"+u+"'></scr"+"ipt>");else{var s=document.createElement('script');s.type='text/javascript';s.async=true;s.src=u;(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(s);}}_kms('https://i.kissmetrics.com/i.js');_kms('http'+('https:'==document.location.protocol ? 's://s3.amazonaws.com/' : '://')+'scripts.kissmetrics.com/#{@api_key}.1.js',1);})();)
       end
     end
   end

data/snogmetrics.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{snogmetrics}
-  s.version = "0.1.1"
+  s.version = "0.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Theo"]
-  s.date = %q{2010-03-31}
+  s.date = %q{2010-04-02}
   s.description = %q{SNOGmetrics gives you the best of both worlds: access to KISSmetrics' JavaScript API through Ruby}
   s.email = %q{theo@iconara.net}
   s.extra_rdoc_files = [
@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
   s.files = [
     ".document",
      ".gitignore",
+     "CHANGELOG.mdown",
      "Gemfile",
      "LICENSE",
      "README.mdown",

data/spec/snogmetrics_spec.rb

@@ -50,9 +50,11 @@ describe Snogmetrics do
       @context.km.record('An important event', :p => 3)
       @context.km.record('An important event', :p => 4)
       js = @context.km.js
-      js.should include('_kmq.push(["record","An important event",{"p":3}]);')
-      js.should include('_kmq.push(["record","An important event",{"p":4}]);')
-      js.index('_kmq.push(["record","An important event",{"p":3}]);').should < js.index('_kmq.push(["record","An important event",{"p":4}]);')
+      first = '_kmq.push(["record","An important event",{"p":3}]);'
+      second = '_kmq.push(["record","An important event",{"p":4}]);'
+      js.should include(first)
+      js.should include(second)
+      js.index(first).should < js.index(second)
     end
   end
   
@@ -82,9 +84,19 @@ describe Snogmetrics do
         Rails.stub!(:env).and_return(mock('env', :production? => true))
       end
       
-      it 'outputs a JavaScript tag that loads the KISSmetrics API' do
+      it 'outputs a JavaScript tag that loads the KISSmetrics API for the provided API key' do
+        @context.stub!(:kissmetrics_api_key).and_return('cab1ebeef')
         @context.km.identify('Phil')
-        @context.km.js.should include('scripts.kissmetrics.com/abc123.1.js')
+        @context.km.js.should include('scripts.kissmetrics.com/cab1ebeef.1.js')
+      end
+    end
+    
+    context 'overriding #use_fake_kissmetrics_api?' do
+      it 'will do your bidding, and not be influenced by Rails.env' do
+        Rails.stub!(:env).and_return(mock('env', :production? => true))
+        @context.stub!(:use_fake_kissmetrics_api?).and_return(true)
+        @context.km.identify('Joyce')
+        @context.km.js.should_not include('scripts.kissmetrics.com')
       end
     end
     
@@ -97,7 +109,7 @@ describe Snogmetrics do
       @context.km.record('1')
       @context.km.record('2')
       @context.km.record('3')
-      @context.km.js.scan(/_kmq.push\(\["record","\d"\]\)/).size.should == 3
+      @context.km.js.scan(/_kmq.push\(\["record","\d"\]\)/).should have(3).items
     end
     
     it 'resets the session when passed :reset => true' do

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Theo
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-31 00:00:00 +02:00
+date: 2010-04-02 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -30,6 +30,7 @@ extra_rdoc_files:
 files: 
 - .document
 - .gitignore
+- CHANGELOG.mdown
 - Gemfile
 - LICENSE
 - README.mdown