vanity 1.2.0 → 1.3.0

data/lib/vanity/frameworks/rails.rb

@@ -0,0 +1,222 @@
+module Vanity
+  module Rails #:nodoc:
+    # The use_vanity method will setup the controller to allow testing and
+    # tracking of the current user.
+    module UseVanity
+      # Defines the vanity_identity method and the set_identity_context filter.
+      #
+      # Call with the name of a method that returns an object whose identity
+      # will be used as the Vanity identity.  Confusing?  Let's try by example:
+      # 
+      #   class ApplicationController < ActionController::Base
+      #     use_vanity :current_user
+      #
+      #     def current_user
+      #       User.find(session[:user_id])
+      #     end
+      #   end
+      # 
+      # If that method (current_user in this example) returns nil, Vanity will
+      # set the identity for you (using a cookie to remember it across
+      # requests).  It also uses this mechanism if you don't provide an
+      # identity object, by calling use_vanity with no arguments.
+      #
+      # Of course you can also use a block:
+      #   class ProjectController < ApplicationController
+      #     use_vanity { |controller| controller.params[:project_id] }
+      #   end
+      def use_vanity(symbol = nil, &block)
+        if block
+          define_method(:vanity_identity) { block.call(self) }
+        else
+          define_method :vanity_identity do
+            return @vanity_identity if @vanity_identity
+            if symbol && object = send(symbol)
+              @vanity_identity = object.id
+            elsif response # everyday use
+              @vanity_identity = cookies["vanity_id"] || ActiveSupport::SecureRandom.hex(16)
+              cookies["vanity_id"] = { :value=>@vanity_identity, :expires=>1.month.from_now }
+              @vanity_identity
+            else # during functional testing
+              @vanity_identity = "test"
+            end
+          end
+        end
+        around_filter :vanity_context_filter
+        before_filter :vanity_reload_filter unless ::Rails.configuration.cache_classes
+        before_filter :vanity_query_parameter_filter
+      end
+      protected :use_vanity
+    end
+
+
+    # Vanity needs these filters.  They are includes in ActionController and
+    # automatically added when you use #use_vanity in your controller.
+    module Filters
+      # Around filter that sets Vanity.context to controller.
+      def vanity_context_filter
+        previous, Vanity.context = Vanity.context, self
+        yield
+      ensure
+        Vanity.context = previous
+      end
+
+      # This filter allows user to choose alternative in experiment using query
+      # parameter.
+      #
+      # Each alternative has a unique fingerprint (run vanity list command to
+      # see them all).  A request with the _vanity query parameter is
+      # intercepted, the alternative is chosen, and the user redirected to the
+      # same request URL sans _vanity parameter.  This only works for GET
+      # requests.
+      # 
+      # For example, if the user requests the page
+      # http://example.com/?_vanity=2907dac4de, the first alternative of the
+      # :null_abc experiment is chosen and the user redirected to
+      # http://example.com/.
+      def vanity_query_parameter_filter
+        if request.get? && params[:_vanity]
+          hashes = Array(params.delete(:_vanity))
+          Vanity.playground.experiments.each do |id, experiment|
+            if experiment.respond_to?(:alternatives)
+              experiment.alternatives.each do |alt|
+                if hash = hashes.delete(experiment.fingerprint(alt)) 
+                  experiment.chooses alt.value
+                  break
+                end
+              end
+            end
+            break if hashes.empty?
+          end
+          redirect_to url_for(params)
+        end
+      end
+
+      # Before filter to reload Vanity experiments/metrics.  Enabled when
+      # cache_classes is false (typically, testing environment).
+      def vanity_reload_filter
+        Vanity.playground.reload!
+      end
+
+      protected :vanity_context_filter, :vanity_query_parameter_filter, :vanity_reload_filter
+    end
+
+
+    # Introduces ab_test helper (controllers and views).  Similar to the generic
+    # ab_test method, with the ability to capture content (applicable to views,
+    # see examples).
+    module Helpers
+      # This method returns one of the alternative values in the named A/B test.
+      #
+      # @example A/B two alternatives for a page
+      #   def index
+      #     if ab_test(:new_page) # true/false test
+      #       render action: "new_page"
+      #     else
+      #       render action: "index"
+      #     end
+      #   end
+      # @example Similar, alternative value is page name
+      #   def index
+      #     render action: ab_test(:new_page)
+      #   end
+      # @example A/B test inside ERB template (condition) 
+      #   <%= if ab_test(:banner) %>100% less complexity!<% end %>
+      # @example A/B test inside ERB template (value) 
+      #   <%= ab_test(:greeting) %> <%= current_user.name %>
+      # @example A/B test inside ERB template (capture) 
+      #   <% ab_test :features do |count| %>
+      #     <%= count %> features to choose from!
+      #   <% end %>
+      def ab_test(name, &block)
+        value = Vanity.playground.experiment(name).choose
+        if block
+          content = capture(value, &block)
+          block_called_from_erb?(block) ? concat(content) : content
+        else
+          value
+        end
+      end
+    end
+
+
+    # Step 1: Add a new resource in config/routes.rb:
+    #   map.vanity "/vanity/:action/:id", :controller=>:vanity
+    #
+    # Step 2: Create a new experiments controller:
+    #   class VanityController < ApplicationController
+    #     include Vanity::Rails::Dashboard
+    #   end
+    #
+    # Step 3: Open your browser to http://localhost:3000/vanity
+    module Dashboard
+      def index
+        render :template=>Vanity.template("_report"), :content_type=>Mime::HTML, :layout=>true
+      end
+
+      def chooses
+        exp = Vanity.playground.experiment(params[:e])
+        exp.chooses(exp.alternatives[params[:a].to_i].value)
+        render :partial=>Vanity.template("experiment"), :locals=>{ :experiment=>exp }
+      end
+    end
+  end
+end
+
+
+# Enhance ActionController with use_vanity, filters and helper methods.
+if defined?(ActionController)
+  # Include in controller, add view helper methods.
+  ActionController::Base.class_eval do
+    extend Vanity::Rails::UseVanity
+    include Vanity::Rails::Filters
+    helper Vanity::Rails::Helpers
+  end
+
+  module ActionController
+    class TestCase
+      alias :setup_controller_request_and_response_without_vanity :setup_controller_request_and_response
+      # Sets Vanity.context to the current controller, so you can do things like:
+      #   experiment(:simple).chooses(:green)
+      def setup_controller_request_and_response
+        setup_controller_request_and_response_without_vanity 
+        Vanity.context = @controller
+      end
+    end
+  end
+end
+
+
+# Automatically configure Vanity.  Uses the 
+if defined?(Rails)
+  Rails.configuration.after_initialize do
+    # Use Rails logger by default.
+    Vanity.playground.logger ||= Rails.logger
+    Vanity.playground.load_path = Rails.root + Vanity.playground.load_path
+    config_file = Rails.root + "config/redis.yml"
+    if !Vanity.playground.connected? && config_file.exist?
+      config = YAML.load_file(config_file)[Rails.env.to_s]
+      Vanity.playground.redis = config if config
+    end
+
+    # Do this at the very end of initialization, allowing test environment to do
+    # Vanity.playground.mock! before any database access takes place.
+    Rails.configuration.after_initialize do
+      Vanity.playground.load!
+    end
+  end
+end
+
+
+# Reconnect whenever we fork under Passenger.
+if defined?(PhusionPassenger)
+  PhusionPassenger.on_event(:starting_worker_process) do |forked| 
+    if forked 
+      begin
+        Vanity.playground.reconnect!
+      rescue Exception=>ex
+        Rails.logger.error "Error reconnecting Redis: #{ex.to_s}" 
+      end
+    end 
+  end 
+end

data/lib/vanity/metric/active_record.rb

@@ -0,0 +1,77 @@
+module Vanity
+  class Metric
+
+    AGGREGATES = [:average, :minimum, :maximum, :sum]
+
+    # Use an ActiveRecord model to get metric data from database table.  Also
+    # forwards +after_create+ callbacks to hooks (updating experiments).
+    #
+    # Supported options:
+    # :conditions -- Only select records that match this condition
+    # :average -- Metric value is average of this column
+    # :minimum -- Metric value is minimum of this column
+    # :maximum -- Metric value is maximum of this column
+    # :sum -- Metric value is sum of this column
+    # :timestamp -- Use this column to filter/group records (defaults to
+    # +created_at+)
+    #
+    # @example Track sign ups using User model
+    #   metric "Signups" do
+    #     model Account
+    #   end
+    # @example Track satisfaction using Survey model
+    #   metric "Satisfaction" do
+    #     model Survey, :average=>:rating
+    #   end
+    # @example Track only high ratings
+    #   metric "High ratings" do
+    #     model Rating, :conditions=>["stars >= 4"]
+    #   end
+    # @example Track only high ratings (using scope)
+    #   metric "High ratings" do
+    #     model Rating.high
+    #   end
+    #
+    # @since 1.2.0
+    # @see Vanity::Metric::ActiveRecord
+    def model(class_or_scope, options = nil)
+      options = options || {}
+      conditions = options.delete(:conditions)
+      @ar_scoped = conditions ? class_or_scope.scoped(:conditions=>conditions) : class_or_scope
+      @ar_aggregate = AGGREGATES.find { |key| options.has_key?(key) }
+      @ar_column = options.delete(@ar_aggregate)
+      fail "Cannot use multiple aggregates in a single metric" if AGGREGATES.find { |key| options.has_key?(key) }
+      @ar_timestamp = options.delete(:timestamp) || :created_at
+      fail "Unrecognized options: #{options.keys * ", "}" unless options.empty?
+      @ar_scoped.after_create self
+      extend ActiveRecord
+    end
+
+    # Calling model method on a metric extends it with these modules, redefining
+    # the values and track! methods.
+    #
+    # @since 1.3.0
+    module ActiveRecord
+
+      # This values method queries the database.
+      def values(sdate, edate)
+        query = { :conditions=>{ @ar_timestamp=>(sdate.to_time...(edate + 1).to_time) },
+                  :group=>"date(#{@ar_scoped.connection.quote_column_name @ar_timestamp})" }
+        grouped = @ar_column ? @ar_scoped.calculate(@ar_aggregate, @ar_column, query) : @ar_scoped.count(query)
+        (sdate..edate).inject([]) { |ordered, date| ordered << (grouped[date.to_s] || 0) }
+      end
+
+      # This track! method stores nothing, but calls the hooks.
+      def track!(*args)
+        count = args.first || 1
+        call_hooks Time.now, count if count > 0
+      end
+
+      # AR model after_create callback notifies all the hooks.
+      def after_create(record)
+        count = @ar_column ? (record.send(@ar_column) || 0) : 1
+        call_hooks record.send(@ar_timestamp), count if count > 0 && @ar_scoped.exists?(record)
+      end
+    end
+  end
+end

data/lib/vanity/{metric.rb → metric/base.rb}

@@ -25,15 +25,14 @@ module Vanity
 
       # Defines a new metric, using the class Vanity::Metric.
       def metric(name, &block)
-        id = File.basename(caller.first.split(":").first, ".rb").downcase.gsub(/\W/, "_").to_sym
-        fail "Metric #{id} already defined in playground" if playground.metrics[id]
-        metric = Metric.new(playground, name.to_s, id)
+        fail "Metric #{@metric_id} already defined in playground" if playground.metrics[@metric_id]
+        metric = Metric.new(playground, name.to_s, @metric_id)
         metric.instance_eval &block
-        playground.metrics[id] = metric
+        playground.metrics[@metric_id] = metric
       end
 
-      def binding_with(playground)
-        @playground = playground
+      def new_binding(playground, id)
+        @playground, @metric_id = playground, id
         binding
       end
 
@@ -101,7 +100,7 @@ module Vanity
         context = Object.new
         context.instance_eval do
           extend Definition
-          metric = eval(source, context.binding_with(playground), file)
+          metric = eval(source, context.new_binding(playground, id), file)
           fail NameError.new("Expected #{file} to define metric #{id}", id) unless playground.metrics[id]
           metric
         end
@@ -197,70 +196,6 @@ module Vanity
     end
 
 
-    # -- ActiveRecord support --
-
-    AGGREGATES = [:average, :minimum, :maximum, :sum]
-
-    # Use an ActiveRecord model to get metric data from database table.  Also
-    # forwards @after_create@ callbacks to hooks (updating experiments).
-    #
-    # Supported options:
-    # :conditions -- Only select records that match this condition
-    # :average -- Metric value is average of this column
-    # :minimum -- Metric value is minimum of this column
-    # :maximum -- Metric value is maximum of this column
-    # :sum -- Metric value is sum of this column
-    # :timestamp -- Use this column to filter/group records (defaults to
-    # +created_at+)
-    #
-    # @example Track sign ups using User model
-    #   metric "Signups" do
-    #     model Account
-    #   end
-    # @example Track satisfaction using Survey model
-    #   metric "Satisfaction" do
-    #     model Survey, :average=>:rating
-    #   end
-    # @example Track only high ratings
-    #   metric "High ratings" do
-    #     model Rating, :conditions=>["stars >= 4"]
-    #   end
-    # @example Track only high ratings (using scope)
-    #   metric "High ratings" do
-    #     model Rating.high
-    #   end
-    #
-    # @since 1.2.0
-    def model(class_or_scope, options = nil)
-      options = (options || {}).clone
-      conditions = options.delete(:conditions)
-      scoped = conditions ? class_or_scope.scoped(:conditions=>conditions) : class_or_scope
-      aggregate = AGGREGATES.find { |key| options.has_key?(key) }
-      column = options.delete(aggregate)
-      fail "Cannot use multiple aggregates in a single metric" if AGGREGATES.find { |key| options.has_key?(key) }
-      timestamp = options.delete(:timestamp) || :created_at
-      fail "Unrecognized options: #{options.keys * ", "}" unless options.empty?
-
-      # Hook into model's after_create
-      scoped.after_create do |record|
-        count = column ? (record.send(column) || 0) : 1
-        call_hooks record.send(timestamp), count if count > 0 && scoped.exists?(record)
-      end
-      # Redefine values method to perform query
-      eigenclass = class << self ; self ; end
-      eigenclass.send :define_method, :values do |sdate, edate|
-        query = { :conditions=>{ timestamp=>(sdate.to_time...(edate + 1).to_time) }, :group=>"date(#{scoped.connection.quote_column_name timestamp})" }
-        grouped = column ? scoped.calculate(aggregate, column, query) : scoped.count(query)
-        (sdate..edate).inject([]) { |ordered, date| ordered << (grouped[date.to_s] || 0) }
-      end
-      # Redefine track! method to call on hooks
-      eigenclass.send :define_method, :track! do |*args|
-        count = args.first || 1
-        call_hooks Time.now, count if count > 0
-      end
-    end
-
-
     # -- Storage --
 
     def destroy!

data/lib/vanity/metric/google_analytics.rb

@@ -0,0 +1,76 @@
+module Vanity
+  class Metric
+    
+    # Use Google Analytics metric.  Note: you must +require "garb"+ before
+    # vanity.
+    # 
+    # @example Page views
+    #   metric "Page views" do
+    #     google_analytics "UA-1828623-6"
+    #   end
+    # @example Visits
+    #   metric "Visits" do
+    #     google_analytics "UA-1828623-6", :visits
+    #   end
+    #
+    # @since 1.3.0
+    # @see Vanity::Metric::GoogleAnalytics
+    def google_analytics(web_property_id, *args)
+      require "garb"
+      options = Hash === args.last ? args.pop : {}
+      metric = args.shift || :pageviews
+      @ga_resource = Vanity::Metric::GoogleAnalytics::Resource.new(web_property_id, metric)
+      @ga_mapper = options[:mapper] ||= lambda { |entry| entry.send(@ga_resource.metrics.elements.first).to_i }
+      extend GoogleAnalytics
+    rescue LoadError
+      fail LoadError, "Google Analytics metrics require Garb, please gem install garb first"
+    end
+
+    # Calling google_analytics method on a metric extends it with these modules,
+    # redefining the values and hook methods.
+    #
+    # @since 1.3.0
+    module GoogleAnalytics
+
+      # Returns values from GA using parameters specified by prior call to
+      # google_analytics.
+      def values(from, to)
+        data = @ga_resource.results(from, to).inject({}) do |hash,entry|
+          hash.merge(entry.date=>@ga_mapper.call(entry))
+        end
+        (from..to).map { |day| data[day.strftime('%Y%m%d')] || 0 }
+      end
+      
+      # Hooks not supported for GA metrics.
+      def hook
+        fail "Cannot use hooks with Google Analytics methods"
+      end
+
+      # Garb report.
+      def report
+        @ga_resource
+      end
+
+      class Resource
+        # GA profile used for this report.  Populated after calling results. 
+        attr_reader :profile
+
+        def initialize(web_property_id, metric)
+          self.class.send :include, Garb::Resource
+          @web_property_id = web_property_id
+          metrics metric
+          dimensions :date
+          sort :date
+        end
+
+        def results(start_date, end_date)
+          @profile = Garb::Profile.all.find { |p| p.web_property_id == @web_property_id }
+          @start_date = start_date
+          @end_date = end_date
+          Garb::ReportResponse.new(send_request_for_body).results
+        end
+      end
+
+    end
+  end
+end