touchstone 0.2.0 → 0.3.0

data/README.markdown

@@ -1,6 +1,6 @@
-Touchstone is a Rails Engine that adds the ability to track advanced metrics for your web app. It is inspired by [this post on the Think Vitamin blog](http://thinkvitamin.com/business/marketing/how-to-get-more-customers/).
+Touchstone is a Rails Engine that adds the ability to track advanced metrics for your web app. It is inspired by [this post on the Think Vitamin blog](http://thinkvitamin.com/business/marketing/how-to-get-more-customers/). I would recommend reading that article to understand what Touchstone does.
 
-Touchstone consists of 3 elements:
+Touchstone consists of 3 classes:
 
 ## Campaigns
 A campaign records the details of a source from which visitors will sign up to your website. It can be a Google Adwords campaign or a link on your homepage.
@@ -9,7 +9,12 @@ A campaign records the details of a source from which visitors will sign up to y
 By adding the parameter ?cid= to each link, the visit will be recorded.
 
 ## Campaign Signups
-When a visitor visits your website via a link containing ?cid= and then signs up, the sign up is tied back to that visit and that campaign. You can then track the revenue obtained from each visitor against the cost of a particular campaign. 
+When a visitor visits your website via a link containing ?cid= and then signs up, the sign up is tied back to that visit and that campaign. You can then track the revenue obtained from each visitor against the cost of a particular campaign.
+
+## Prerequisites & Dependencies
+Touchstone requires your application to have something like a User model. The model doesn't need to be called User (you can configure this) but the purpose of Touchstone is to track users who signup to your application in response to a campaign.
+
+The views are built using Bootstrap so installing Touchstone will introduce dependencies on the sass and sass-bootstrap gems.
 
 ## Installation
 Add the following line to your Gemfile:
@@ -18,13 +23,25 @@ Add the following line to your Gemfile:
 
 Then run `bundle install`
 
-Copy the migrations across to your application by running `touchstone:install:migrations`. This will add models for the 3 elements set out above.
+## Configuration
+Once the gem has been installed run `rails g touchstone`
+
+This will:
+
+* Copy an initializer file to `config/initializers/touchstone.rb`. You should read this file and set your configuration options before proceeding
+* Add a before filter to your application controller. *NB*: This defaults to setting a private method for the filter. If you already have `private` defined in your application controller, you will need to remove the duplicate declaration.
+* Mounts the engine in your routes.rb file
+
+## Installation continued
+Copy the migrations across to your application by running `rake touchstone:install:migrations`. This will add migrations to create the tables for the 3 classes set out above.
+
+If, for any reason the command `rails g touchstone` has not made the correct changes to your files, these are the changes that need to be made and can be made manually. If you do not have a `User` model, the configuration option `association_name` in the Touchstone initializer must be set before running the Touchstone migrations.
 
 You will need to mount Touchstone in your application by adding the following line to your `routes.rb` file:
 
 	mount Touchstone::Engine, :at => "/touchstone/"
 	
-Finally, add the following to your `application_controller.rb` file:
+Add the following to your `application_controller.rb` file:
 
 	before_filter :set_cookie_and_record_visit
 	
@@ -40,6 +57,8 @@ Finally, add the following to your `application_controller.rb` file:
 	end
 
 ## Usage
+Restart your server, and if you now visit `http://yourdomain.com/touchstone`, you will see the default page.
+
 Usage is very simple. Assume you are running a Google Adwords campaign for 1 week at a cost of $100. Create this campaign in Touchstone and it will return a campaign ID. Make sure all your links on Adwords contain the parameter at the end `?cid={campaign_id}` where `campaign_id` is the id generated by Touchstone. Please note:
 
 * Campaigns don't need to be paid campaigns, it can be as simple as a link on your homepage
@@ -62,7 +81,7 @@ The installation steps described above will get you going with tracking visits f
 		end
 	end
 
-Tracking a user's lifetime value will depend on your transactional logic but assuming a common pattern of a user having a subscription and that subscription containing many transactions, the following could be used:
+Touchstone requires your user model to have a method called lifetime\_value in order to calculate the revenue that a user has generated. Tracking a user's lifetime value will depend on your transactional logic but assuming a common pattern of a user having a subscription and that subscription containing many transactions, the following could be used:
 
 	class User < ActiveRecord::Base
 		...
@@ -78,8 +97,5 @@ Tracking a user's lifetime value will depend on your transactional logic but ass
 
 ## Todo
 
-* Don't constrain Touchstone to an application that only has a Users table. Allow this as a configuration option
-* Automatically load routes and application controller content
-* Improve design
 * Add some tests
 * Allow customisation of currency (only displays dollars at moment although amounts are not stored in a particular currency)

data/app/controllers/touchstone/campaigns_controller.rb

@@ -23,6 +23,7 @@ class Touchstone::CampaignsController < ApplicationController
   
   def show
     @campaign = Campaign.find(params[:id])
+    @columns = Touchstone.column_names
   end
   
   def edit

data/app/helpers/touchstone/campaigns_helper.rb

@@ -0,0 +1,21 @@
+module Touchstone
+  module CampaignsHelper
+    
+    def signups_table_headers(columns)
+      item = ""
+      columns.each do |column|
+        item += "<th scope='col' id='#{column}'>#{column.humanize}</th>\n"
+      end
+			item.html_safe
+    end
+    
+    def signups_table_content(columns,signup)
+      item = ""
+      columns.each do |column|
+        item += "<td class='#{column}'>#{signup.user.send(column.to_sym)}</td>\n"
+      end
+			item.html_safe
+    end
+    
+  end
+end

data/app/models/campaign.rb

@@ -12,7 +12,7 @@ class Campaign < ActiveRecord::Base
     if self.campaign_signups.length > 0
       total = Array.new
       self.campaign_signups.each do |signup|
-        total << signup.user.lifetime_value # TODO: Fix this
+        total << signup.user.lifetime_value
       end
       total.inject{|sum,x| sum + x}
     else

data/app/models/campaign_signup.rb

@@ -1,8 +1,8 @@
 class CampaignSignup < ActiveRecord::Base
   
   belongs_to :campaign, :class_name => "Campaign", :foreign_key => "campaign_id"
-  belongs_to :user, :class_name => "User", :foreign_key => "user_id" # TODO: Fix this
+  belongs_to :user, :class_name => Touchstone.association_name.capitalize, :foreign_key => "#{Touchstone.association_name}_id" # TODO: Fix this
   
-  attr_accessible :user_id, :campaign_id
+  attr_accessible "#{Touchstone.association_name}_id".to_sym, :campaign_id
   
 end

data/app/views/touchstone/campaigns/show.html.erb

@@ -28,19 +28,13 @@
 <table class="table table-striped">
 	<thead>
 		<tr>
-			<th scope="col" width="25%">Name</th>
-			<th scope="col" width="30%">Email</th>
-			<th scope="col" width="30%">Registered</th>
-			<th scope="col" width="15%">LTV (inc. VAT)</th>
+			<%= signups_table_headers(@columns) %>
 		</tr>
 	</thead>
 	<tbody>
 	<% @campaign.campaign_signups.each do |signup| %>
 		<tr>
-			<td><%= signup.user.name %></td>
-			<td><%= signup.user.email %></td>
-			<td><%= time_ago_in_words(signup.user.created_at) %> ago</td>
-			<td>$<%= sprintf("%.2f",signup.user.lifetime_value) %></td>
+			<%= signups_table_content(@columns,signup)%>
 		</tr>
 	<% end %>
 	</tbody>

data/db/migrate/002_create_touchstone_campaign_signups.rb

@@ -1,8 +1,11 @@
 class CreateTouchstoneCampaignSignups < ActiveRecord::Migration
   
   def change
+    
+    column = Touchstone.association_name + "_id"
+    
     create_table :campaign_signups do |t|
-      t.integer :user_id
+      t.integer column.to_sym
       t.integer :campaign_id
       t.timestamps
     end

data/lib/generators/touchstone/templates/touchstone.rb

@@ -0,0 +1,19 @@
+Touchstone.config do |c|
+  
+  # By default, Touchstone assumes that you have a User model
+  # in your application and will associate campaign signups
+  # with a user_id in the campaign_signups table. You can
+  # customise the association by using this configuration
+  # option.
+  
+  c.association_name = "User"
+  
+  # When viewing a campaign, Touchstone will show a list of
+  # users who have signed up as a result of that campaign.
+  # Use this option to set an array of fields that you would
+  # like to appear in the view. By default, Touchstone will
+  # only show the id and created_at fields.
+  
+  c.column_names = [:id,:created_at]
+  
+end

data/lib/generators/touchstone/touchstone_generator.rb

@@ -0,0 +1,27 @@
+require 'rails/generators'
+
+class TouchstoneGenerator < Rails::Generators::Base
+  
+  def self.source_root
+    File.join(File.dirname(__FILE__), 'templates')
+  end
+  
+  def copy_initializer_file
+    puts "Copying initializer file..."
+    copy_file 'touchstone.rb', 'config/initializers/touchstone.rb'
+  end
+  
+  def set_before_filter
+    puts "Setting before filter in application_controller.rb..."
+    insert_into_file 'app/controllers/application_controller.rb', "\n\n\tbefore_filter :set_cookie_and_record_visit", :after => 'ActionController::Base'
+    insert_into_file 'app/controllers/application_controller.rb', :before => "end" do
+      "\tprivate\n\n\tdef set_cookie_and_record_visit\n\t\tif params[:cid] && Campaign.find_by_id(params[:cid]) && !CampaignVisit.find_by_request_ip(request.remote_ip)\n\t\t\tif !cookies['touchstone_campaign_id']\n\t\t\t\tcookies['touchstone_campaign_id'] = params[:cid]\n\t\t\t\tCampaignVisit.create(:campaign_id => params[:cid], :request_ip => request.remote_ip)\n\t\t\tend\n\t\tend\n\tend\n"
+    end
+  end
+  
+  def mount_engine
+    puts "Mounting engine into routes.rb..."
+    insert_into_file 'config/routes.rb', "\n\nmount Touchstone::Engine, :at => '/touchstone/'", :after => 'routes.draw do'
+  end
+  
+end

data/lib/tasks/touchstone_tasks.rake

@@ -1,10 +0,0 @@
-# require 'thor'
-# include Thor
-# 
-# namespace :touchstone do
-#   
-#   desc "Injects the necessary code into your application to run Touchstone"
-#   task :install do
-#     inject_into_file "#{Rails.root}/config/routes.rb", "mount Touchstone::Engine, :at => '/touchstone/'", :after => "routes.draw do"
-#   end
-# end

data/lib/touchstone/configuration.rb

@@ -4,15 +4,23 @@ module Touchstone
    
     extend self
     
-    attr_accessor :association_name
+    attr_accessor :association_name, :column_names
     
     def association_name=name
-      @name = name
+      @name = name.downcase
     end
     
     def association_name
       @name || "user"
     end
     
+    def column_names=columns
+      @columns = columns.map(&:to_s)
+    end
+    
+    def column_names
+      @columns || [:id,:created_at]
+    end
+    
   end
 end

data/lib/touchstone/version.rb

@@ -1,3 +1,3 @@
 module Touchstone
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/touchstone.rb

@@ -5,12 +5,20 @@ module Touchstone
   
   include Configuration
   
-  mattr_accessor :app_root
-  
   class << self
-    def configure &block
+    
+    def config &block
       yield Touchstone::Configuration
     end
+    
+    def association_name
+      Touchstone::Configuration.association_name
+    end
+    
+    def column_names
+      Touchstone::Configuration.column_names
+    end
+    
   end
   
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: touchstone
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-14 00:00:00.000000000 Z
+date: 2012-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -89,6 +89,7 @@ files:
 - app/controllers/touchstone/application_controller.rb
 - app/controllers/touchstone/campaigns_controller.rb
 - app/helpers/touchstone/application_helper.rb
+- app/helpers/touchstone/campaigns_helper.rb
 - app/models/campaign.rb
 - app/models/campaign_signup.rb
 - app/models/campaign_visit.rb
@@ -103,6 +104,8 @@ files:
 - db/migrate/001_create_touchstone_campaigns.rb
 - db/migrate/002_create_touchstone_campaign_signups.rb
 - db/migrate/003_create_touchstone_campaign_visits.rb
+- lib/generators/touchstone/templates/touchstone.rb
+- lib/generators/touchstone/touchstone_generator.rb
 - lib/tasks/touchstone_tasks.rake
 - lib/touchstone/configuration.rb
 - lib/touchstone/engine.rb
@@ -156,7 +159,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2775789728872251427
+      hash: -3745211063638779755
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -165,7 +168,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2775789728872251427
+      hash: -3745211063638779755
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.20