vanity 0.3.1 → 0.4.0

data/lib/vanity/experiment/base.rb

@@ -14,65 +14,61 @@ module Vanity
 
       end
 
-      def initialize(playground, id, name, &block)
+      def initialize(playground, id, name, options, &block)
         @playground = playground
         @id, @name = id.to_sym, name
+        @options = options || {}
         @namespace = "#{@playground.namespace}:#{@id}"
         @identify_block = ->(context){ context.vanity_identity }
       end
 
-      # Human readable experiment name, supplied during creation.
+      # Human readable experiment name (first argument you pass when creating a
+      # new experiment).
       attr_reader :name
 
-      # Unique identifier, derived from name, e.g. "Green Button" become :green_button.
+      # Unique identifier, derived from name experiment name, e.g. "Green
+      # Button" becomes :green_button.
       attr_reader :id
-      
-      # Experiment creation timestamp.
+
+      # Time stamp when experiment was created.
       attr_reader :created_at
 
-      # Experiment completion timestamp.
+      # Time stamp when experiment was completed.
       attr_reader :completed_at
 
-      # Returns the type of this class as a symbol (e.g. ab_test).
+      # Returns the type of this experiment as a symbol (e.g. :ab_test).
       def type
         self.class.type
       end
      
-      # Call this method with no argument or block to return an identity.  Call
-      # this method with a block to define how to obtain an identity for the
-      # current experiment.
-      #
-      # For example, this experiment use the identity of the project associated
-      # with the controller:
-      #
-      #   class ProjectController < ApplicationController
-      #     before_filter :set_project
-      #     attr_reader :project
+      # Defines how we obtain an identity for the current experiment.  Usually
+      # Vanity gets the identity form a session object (see use_vanity), but
+      # there are cases where you want a particular experiment to use a
+      # different identity.
       #
-      #     . . .
-      #   end
-      #
-      #   experiment "Project widget" do
+      # For example, if all your experiments use current_user and you need one
+      # experiment to use the current project:
+      #   ab_test "Project widget" do
       #     alternatives :small, :medium, :large
       #     identify do |controller|
       #       controller.project.id
       #     end
       #   end
       def identify(&block)
-        if block_given?
-          @identify_block = block
-          self
-        else
-          @identify_block.call(Vanity.context) or fail "No identity found"
-        end
+        @identify_block = block
+      end
+
+      def identity
+        @identify_block.call(Vanity.context) or fail "No identity found"
       end
+      protected :identity
 
 
       # -- Reporting --
 
       # Sets or returns description. For example
-      #   experiment :simple do
-      #     description "Simple experiment"
+      #   ab_test "Simple" do
+      #     description "A simple A/B experiment"
       #   end
       #
       #   puts "Just defined: " + experiment(:simple).description
@@ -90,8 +86,7 @@ module Vanity
 
       # Define experiment completion condition.  For example:
       #   complete_if do
-      #     alternatives.all? { |alt| alt.participants >= 100 } &&
-      #     alternatives.any? { |alt| alt.confidence >= 0.95 }
+      #     !score(95).chosen.nil?
       #   end
       def complete_if(&block)
         raise ArgumentError, "Missing block" unless block
@@ -129,41 +124,35 @@ module Vanity
         redis[key(:completed_at)].nil?
       end
 
-
       # -- Store/validate --
 
-      # Returns key for this experiment, or with an argument, return a key
-      # using the experiment as the namespace.  Examples:
-      #   key => "vanity:experiments:green_button"
-      #   key("participants") => "vanity:experiments:green_button:participants"
-      def key(name = nil) #:nodoc:
-        name ? "#{@namespace}:#{name}" : @namespace
+      # Get rid of all experiment data.
+      def destroy
+        redis.del key(:created_at)
+        redis.del key(:completed_at)
       end
 
-      # Shortcut for Vanity.playground.redis
-      def redis #:nodoc:
-        @playground.redis
-      end
-      
       # Called by Playground to save the experiment definition.
       def save
         redis.setnx key(:created_at), Time.now.to_i
         @created_at = Time.at(redis[key(:created_at)].to_i)
       end
 
-      # Reset experiment to its initial state.
-      def reset!
-        @created_at = Time.now
-        redis[key(:created_at)] = @created_at.to_i
-        redis.del key(:completed_at)
-      end
+    protected
 
-      # Get rid of all experiment data.
-      def destroy
-        redis.del key(:created_at)
-        redis.del key(:completed_at)
+      # Returns key for this experiment, or with an argument, return a key
+      # using the experiment as the namespace.  Examples:
+      #   key => "vanity:experiments:green_button"
+      #   key("participants") => "vanity:experiments:green_button:participants"
+      def key(name = nil)
+        name ? "#{@namespace}:#{name}" : @namespace
       end
 
+      # Shortcut for Vanity.playground.redis
+      def redis
+        @playground.redis
+      end
+      
     end
   end
 end

data/lib/vanity/playground.rb

@@ -1,7 +1,21 @@
 module Vanity
 
-  # Vanity.playground.configuration
-  class Configuration
+  # These methods are available from experiment definitions (files located in
+  # the experiments directory, automatically loaded by Vanity).  Use these
+  # methods to define you experiments, for example:
+  #   ab_test "New Banner" do
+  #     alternatives :red, :green, :blue
+  #   end
+  module Definition
+
+  protected
+    # Defines a new experiment, given the experiment's name, type and
+    # definition block.
+    def define(name, type, options = nil, &block)
+      options ||= {}
+      Vanity.playground.define(name, type, options, &block)
+    end
+
   end
 
   # Playground catalogs all your experiments, holds the Vanity configuration.
@@ -40,14 +54,12 @@ module Vanity
     attr_accessor :logger
 
     # Defines a new experiment. Generally, do not call this directly,
-    # use #experiment instead.
-    def define(name, options = nil, &block)
+    # use one of the definition methods (ab_test, measure, etc).
+    def define(name, type, options = {}, &block)
       id = name.to_s.downcase.gsub(/\W/, "_")
       raise "Experiment #{id} already defined once" if @experiments[id]
-      options ||= {}
-      type = options[:type] || :ab_test
       klass = Experiment.const_get(type.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase })
-      experiment = klass.new(self, id, name)
+      experiment = klass.new(self, id, name, options)
       experiment.instance_eval &block
       experiment.save
       @experiments[id] = experiment
@@ -62,7 +74,23 @@ module Vanity
     def experiment(name)
       id = name.to_s.downcase.gsub(/\W/, "_")
       unless @experiments.has_key?(id)
-        require File.join(load_path, id)
+        @loading ||= []
+        fail "Circular dependency detected: #{@loading.join('=>')}=>#{id}" if @loading.include?(id)
+        begin
+          @loading.push id
+          source = File.read(File.expand_path("#{id}.rb", load_path))
+          context = Object.new
+          context.instance_eval do
+            extend Definition
+            eval source
+          end
+        rescue
+          error = LoadError.exception($!.message)
+          error.set_backtrace $!.backtrace
+          raise error
+        ensure
+          @loading.pop
+        end
       end
       @experiments[id] or fail LoadError, "Expected experiments/#{id}.rb to define experiment #{name}"
     end
@@ -70,11 +98,17 @@ module Vanity
     # Returns list of all loaded experiments.
     def experiments
       Dir[File.join(load_path, "*.rb")].each do |file|
-        require file
+        id = File.basename(file).gsub(/.rb$/, "")
+        experiment id
       end
       @experiments.values
     end
 
+    # Reloads all experiments.
+    def reload!
+      @experiments.clear
+    end
+
     # Use this instance to access the Redis database.
     def redis
       redis = Redis.new(host: self.host, port: self.port, db: self.db,
@@ -100,7 +134,7 @@ module Vanity
     end
 
     # Sets the Vanity context.  For example, when using Rails this would be
-    # set by the set_vanity_context before filter (via use_vanity).
+    # set by the set_vanity_context before filter (via Vanity::Rails#use_vanity).
     def context=(context)
       Thread.current[:vanity_context] = context
     end
@@ -115,22 +149,12 @@ module Vanity
   end
 end
 
+
 class Object
 
-  # Use this method to define or access an experiment.
-  # 
-  # To define an experiment, call with a name, options and a block.  For
-  # example:
-  #   experiment "Text size" do
-  #     alternatives :small, :medium, :large
-  #   end
-  #
+  # Use this method to access an experiment by name.  For example:
   #   puts experiment(:text_size).alternatives
-  def experiment(name, options = nil, &block)
-    if block
-      Vanity.playground.define(name, options, &block)
-    else
-      Vanity.playground.experiment(name)
-    end
+  def experiment(name)
+    Vanity.playground.experiment(name)
   end
 end

data/lib/vanity/rails.rb

@@ -1,7 +1,7 @@
 require "vanity"
 require "vanity/rails/helpers"
 require "vanity/rails/testing"
-require "vanity/rails/console"
+require "vanity/rails/dashboard"
 
 # Use Rails logger by default.
 Vanity.playground.logger ||= ActionController::Base.logger
@@ -9,6 +9,7 @@ Vanity.playground.load_path = "#{RAILS_ROOT}/experiments"
 
 # Include in controller, add view helper methods.
 ActionController::Base.class_eval do
+  extend Vanity::Rails::ClassMethods
   include Vanity::Rails
   helper Vanity::Rails
 end

data/lib/vanity/rails/dashboard.rb

@@ -0,0 +1,15 @@
+module Vanity
+  module Rails
+    module Dashboard
+      def index
+        render 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

data/lib/vanity/rails/helpers.rb

@@ -14,43 +14,33 @@ module Vanity
   # 3) Measure conversion:
   #
   #   def signup
-  #     ab_goal! :pricing
+  #     track! :pricing
   #     . . .
   #   end
   module Rails
     module ClassMethods
 
-      # Defines the vanity_identity method, and the set_identity_context before
-      # filter.
+      # Defines the vanity_identity method and the set_identity_context filter.
       #
-      # Single argument names a method that returns an object whose identity is
-      # the vanity identity.  Identity is used to present an experiment
-      # consistently to the same person or people.  It can be the user's
-      # identity, group, project.  The object must provide its identity in
-      # response to the method +id+.
-      #
-      # For example, if +current_user+ returns a +User+ object, then to use the
-      # user's id:
+      # 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
-      #   end
-      #
-      # If that method returns nil (e.g. the user has not signed in), a random
-      # value will be used, instead.  That random value is maintained using a
-      # cookie.
-      #
-      # Alternatively, if you call use_vanity with a block, it will yield to the
-      # block with controller.
-      #
-      # If there is no identity you can use, call use_vanity with the value +nil+.
       #
-      # For 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.project_id }
+      #     use_vanity { |controller| controller.params[:project_id] }
       #   end
       def use_vanity(symbol = nil, &block)
         define_method :vanity_identity do
@@ -71,13 +61,10 @@ module Vanity
           Vanity.context = self
         end
         before_filter :set_vanity_context
+        before_filter { Vanity.playground.reload! } unless ::Rails.configuration.cache_classes
       end
     end
 
-    def self.included(base) #:nodoc:
-      base.extend ClassMethods
-    end
-
     # This method returns one of the alternative values in the named A/B test.
     #
     # Examples using ab_test inside controller:
@@ -113,11 +100,11 @@ module Vanity
 
     # This method records conversion on the named A/B test. For example:
     #   def create
-    #     ab_goal! :call_to_action
+    #     track! :call_to_action
     #     Acccount.create! params[:account]
     #   end
-    def ab_goal!(name)
-      Vanity.playground.experiment(name).conversion!
+    def track!(name, *args)
+      Vanity.playground.experiment(name).track! *args
     end
   end
 end

data/lib/vanity/rails/testing.rb

@@ -1,6 +1,8 @@
-module ActionController #:nodoc:
+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

data/lib/vanity/templates/_ab_test.erb

@@ -1,21 +1,23 @@
 <% score = experiment.score %>
 <table>
-  <caption><%= experiment.conclusion(score).join(" ") %></caption>
+  <caption>
+    <%= experiment.conclusion(score).join(" ") %></caption>
   <% score.alts.each do |alt| %>
     <tr class="<%= "choice" if score.choice == alt %>">
       <td class="option"><%= alt.name.gsub(/^o/, "O") %>:</td>
-      <td class="value"><code><%= CGI.escape_html alt.value.to_s %></code></td>
+      <td class="value"><code><%=h alt.value.to_s %></code></td>
       <td>
         <%= "%.1f%%" % [alt.conversion_rate * 100] %>
         <%= "(%d%% better than %s)" % [alt.difference, score.least.name] if alt.difference && alt.difference >= 1 %>
       </td>
       <td class="action">
         <% if experiment.active? && respond_to?(:chooses_experiments_url) %>
-          <% if experiment.chosen?(alt) %>
+          <% if experiment.showing?(alt) %>
             showing
           <% else %>
-            <%= link_to "show", chooses_experiments_url(e: experiment.id, a: alt.id), method: :post,
-                  class: "button", title: "Show me this alternative from now on" %>
+            <%= link_to_remote "show", update: "experiment_#{experiment.id}",
+                  url: chooses_experiments_url(e: experiment.id, a: alt.id), method: :post,
+                  html: { class: "button", title: "Show me this alternative from now on" } %>
           <% end %>
         <% end %>
       </td>

data/lib/vanity/templates/_experiment.erb

@@ -0,0 +1,5 @@
+<h2><%=h experiment.name %> <span class="type">(<%= experiment.class.friendly_name %>)</span></h2>
+<%= experiment.description.to_s.split(/\n\s*\n/).map { |para| %{<p class="description">#{h para}</p>} }.join %>
+<%= render Vanity.template(experiment.type), experiment: experiment %>
+<p class="meta">Started <%= experiment.created_at.strftime("%a, %b %-d") %>
+  <%= " | Completed #{experiment.completed_at.strftime("%a, %b %-d")}" unless experiment.active? %></p>