session_logger 0.0.1 → 1.0.1

data/README.rdoc

@@ -1,3 +1,96 @@
 = SessionLogger
 
-This project rocks and uses MIT-LICENSE.
+The session logger is simply a observer that automatically writes data from
+the session to models with matching columns.
+
+
+== What it is good for
+
+Session Logger is great for recording session based activites you want to
+group together.
+
+Questions session logger can help answer:
+
+* How many users came in from a given ad campaign?
+
+* How many invites did those users from that campaign send?
+
+* How many purchases came when we directed people to this landing page?
+
+* Pretty much anything about users activity over a single session...
+
+== Setup
+
+First install the gem:
+  gem install session_logger
+
+And/or add it to your Gemfile
+  gem session_logger
+
+Then create the initializer:
+  rails generate session_logger:initializer
+
+As a performance optimization you can add the list of models to observe in the initializer:
+  config.session_logger.logged_models = [MODEL_CONSTANTS,...]
+
+Finally add 'enable_session_logger' to Application controller (or any controller you want logging to occur)
+  ApplicationController < ActionController::Base
+    enable_session_logger
+  end
+
+
+== Usage
+
+1. Create metadata columns on the models you want metadata recorded on
+2. Be sure to prefix metadata columns with the model prefix ("sl_" by default)
+3. Simply set that same prefixed name in the session and that metadata will be stored anytime a observed record is created during that session.
+   
+
+== How it works
+
+We create a new observer type that has access to both the controller and the
+model level call backs that will write metadata found in the session to models
+at creation time.
+
+When a session key is found that matches a prefixed column for the model that
+is being created we simply append that data before save to the model effectively
+appending the metadata for that users session.
+
+== Gotchas
+
+If you start monitoring a ton of metadata around the user you have to switch
+to db sessions instead of cookie store.
+
+Don't clear your whole session haphazardly. Thats where the metadata is stored
+
+
+== Choice to use columns instead of polymorphic table
+
+One of the primary conerns we had when we were developing this gem was the
+trade offs between adding additional namespaced columns on the records
+and creating a seperate polymorphic join table for the logging information.
+
+At the end of the day we choose to implement the logging solution with
+namespaced columns. Here are the pros and cons.
+
+Columns solution:
+
+Pros:
+* Speed and simplicity in creation of reports.
+* Speed of writes of those rows. (one write call vs two)
+* Customization of metadata per model without Null columns
+
+Cons:
+* Pain to add so many repeated columns to potentially many tables
+* (OK) Slow down in read of individual rows (can be mitigated with scoped select statements)
+* (OK) Metadata doesn't have its own timestamp (not really applicable as it should be the same as the write time of the original record)
+
+
+The only real con that we couldn't work around is the initial number of columns
+you will need to add to all your models. Many of them repeat in practice and
+this will give you a bad taste in your mouth but it seems like a better
+solution overall.
+
+
+== License
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -20,8 +20,6 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
-load 'rails/tasks/engine.rake'
 
 
 Bundler::GemHelper.install_tasks

data/lib/generators/session_logger/initializer_generator.rb

@@ -0,0 +1,12 @@
+module SessionLogger
+  class InitializerGenerator < Rails::Generators::Base
+    source_root File.expand_path("../templates", __FILE__)
+
+    desc "Generator creates a sample initializer for the session_logger"
+
+    def create_config_files
+      copy_file "session_logger.rb", "config/initializers/session_logger.rb"
+    end
+
+  end
+end

data/lib/generators/session_logger/templates/session_logger.rb

@@ -0,0 +1,15 @@
+# The configure step must be run after the rails app has finished initializing
+# for the models to respond to observer registration requests
+Rails.application.config.after_initialize do
+  SessionLogger.configure do |config|
+
+    # Default is to observe all models in the models dir
+    config.logged_models = Dir["#{Rails.root}/app/models/**/*.rb"].map { |f| File.basename(f, '.*').camelize.constantize }
+
+    # Performance optimization for only observing certain models
+    # config.logged_models = [User]
+
+    # Customizable model prefixing
+    # config.model_prefix = "sl_"
+  end
+end

data/lib/session_logger/session_logging.rb

@@ -0,0 +1,70 @@
+module SessionLogger
+
+  module SessionLogging
+    extend ActiveSupport::Concern
+
+    module ClassMethods #:nodoc:
+
+      # Options are the same as the ones for around filter. See docs for around filter
+      def enable_session_logging(options={})
+
+        raise "Session Logging can't occur without specifying logged_models in initializers" if SessionLogger.logged_models.blank?
+
+        SessionLogger::SessionObserver.observe(SessionLogger.logged_models)
+
+        if !ActiveRecord::Base.observers.include? SessionLogger::SessionObserver
+          ActiveRecord::Base.observers << SessionLogger::SessionObserver if defined?(ActiveRecord) and defined?(ActiveRecord::Base)
+        end
+
+        sweeper_instance = SessionLogger::SessionObserver.instance
+
+        around_filter(sweeper_instance, options)
+      end
+    end
+  end
+
+
+  class SessionObserver < ActiveRecord::Observer
+    attr_accessor :controller
+
+    #Required to prevent the observer from un-cleverly looking for Session...
+    def self.observed_class
+      nil
+    end
+
+    # ------------------------------------------- Legacy around filter calls
+    def before(controller)
+      self.controller = controller
+      true # before method from SessionObserver should always return true
+    end
+
+    def after(controller)
+      self.controller = controller
+      # Clean up, so that the controller can be collected after this request
+      self.controller = nil
+    end
+
+    # ------------------------------------------- ActiveRecord callbacks
+    def before_create(record)
+      return if controller.blank? || controller.session.blank?
+
+      candidate_columns = record.attributes.select { |attr| attr.starts_with? SessionLogger.model_prefix }
+      candidate_columns.keys.each do |column|
+        column = column.to_s
+        #Only setting if present prevents empty strings from overriding defaults in the schema
+        set_if_present(record, column, controller.session[column])
+      end
+      #pp controller.session["sl_campaign"]
+      #pp record
+    end
+
+    private
+    def set_if_present(obj, key, val)
+      pp obj
+      pp key
+      pp val
+      obj.send("#{key}=", val) if val.present?
+    end
+  end
+
+end

data/lib/session_logger/version.rb

@@ -1,3 +1,3 @@
 module SessionLogger
-  VERSION = "0.0.1"
+  VERSION = "1.0.1"
 end

data/lib/session_logger.rb

@@ -1,4 +1,31 @@
-require "session_logger/engine"
+require "session_logger/session_logging"
 
 module SessionLogger
+
+  # --------------------------------------------- Rails injection
+  # This injects the session logging class methods into the action_controller
+  ActiveSupport.on_load(:action_controller) do
+    include SessionLogger::SessionLogging
+  end
+
+  # --------------------------------------------- Configuration
+  # Defines the session_logger configuration keys for usage in application.rb
+  SessionLoggerConfig = Struct.new(:logged_models, :model_prefix)
+  @@config = SessionLoggerConfig.new
+
+  #Allows the initializer to set the configuration for session_logger
+  def self.configure(&block)
+    block.call(@@config)
+  end
+
+  def self.logged_models
+    #Returns a list of models (dependant on rails conventions in the models dir)
+    @@config.logged_models
+  end
+
+  def self.model_prefix
+    @@config.model_prefix ||= "sl_"
+  end
+
 end
+

data/test/dummy/app/assets/javascripts/users.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/test/dummy/app/assets/stylesheets/scaffold.css

@@ -0,0 +1,56 @@
+body { background-color: #fff; color: #333; }
+
+body, p, ol, ul, td {
+  font-family: verdana, arial, helvetica, sans-serif;
+  font-size:   13px;
+  line-height: 18px;
+}
+
+pre {
+  background-color: #eee;
+  padding: 10px;
+  font-size: 11px;
+}
+
+a { color: #000; }
+a:visited { color: #666; }
+a:hover { color: #fff; background-color:#000; }
+
+div.field, div.actions {
+  margin-bottom: 10px;
+}
+
+#notice {
+  color: green;
+}
+
+.field_with_errors {
+  padding: 2px;
+  background-color: red;
+  display: table;
+}
+
+#error_explanation {
+  width: 450px;
+  border: 2px solid red;
+  padding: 7px;
+  padding-bottom: 0;
+  margin-bottom: 20px;
+  background-color: #f0f0f0;
+}
+
+#error_explanation h2 {
+  text-align: left;
+  font-weight: bold;
+  padding: 5px 5px 5px 15px;
+  font-size: 12px;
+  margin: -7px;
+  margin-bottom: 0px;
+  background-color: #c00;
+  color: #fff;
+}
+
+#error_explanation ul li {
+  font-size: 12px;
+  list-style: square;
+}

data/test/dummy/app/assets/stylesheets/users.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/test/dummy/app/controllers/application_controller.rb

@@ -1,3 +1,4 @@
 class ApplicationController < ActionController::Base
   protect_from_forgery
+  enable_session_logging
 end

data/test/dummy/app/controllers/users_controller.rb

@@ -0,0 +1,83 @@
+class UsersController < ApplicationController
+  # GET /users
+  # GET /users.json
+  def index
+    @users = User.all
+
+    respond_to do |format|
+      format.html # index.html.erb
+      format.json { render json: @users }
+    end
+  end
+
+  # GET /users/1
+  # GET /users/1.json
+  def show
+    @user = User.find(params[:id])
+
+    respond_to do |format|
+      format.html # show.html.erb
+      format.json { render json: @user }
+    end
+  end
+
+  # GET /users/new
+  # GET /users/new.json
+  def new
+    @user = User.new
+
+    respond_to do |format|
+      format.html # new.html.erb
+      format.json { render json: @user }
+    end
+  end
+
+  # GET /users/1/edit
+  def edit
+    @user = User.find(params[:id])
+  end
+
+  # POST /users
+  # POST /users.json
+  def create
+    @user = User.new(params[:user])
+
+    respond_to do |format|
+      if @user.save
+        format.html { redirect_to @user, notice: 'User was successfully created.' }
+        format.json { render json: @user, status: :created, location: @user }
+      else
+        format.html { render action: "new" }
+        format.json { render json: @user.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+
+  # PUT /users/1
+  # PUT /users/1.json
+  def update
+    @user = User.find(params[:id])
+
+    respond_to do |format|
+      if @user.update_attributes(params[:user])
+        format.html { redirect_to @user, notice: 'User was successfully updated.' }
+        format.json { head :ok }
+      else
+        format.html { render action: "edit" }
+        format.json { render json: @user.errors, status: :unprocessable_entity }
+      end
+    end
+  end
+
+  # DELETE /users/1
+  # DELETE /users/1.json
+  def destroy
+    @user = User.find(params[:id])
+    @user.destroy
+
+    respond_to do |format|
+      format.html { redirect_to users_url }
+      format.json { head :ok }
+    end
+  end
+end

data/test/dummy/app/helpers/users_helper.rb

@@ -0,0 +1,2 @@
+module UsersHelper
+end

data/test/dummy/app/models/user.rb

@@ -0,0 +1,2 @@
+class User < ActiveRecord::Base
+end

data/test/dummy/app/views/users/_form.html.erb

@@ -0,0 +1,29 @@
+<%= form_for(@user) do |f| %>
+  <% if @user.errors.any? %>
+    <div id="error_explanation">
+      <h2><%= pluralize(@user.errors.count, "error") %> prohibited this user from being saved:</h2>
+
+      <ul>
+      <% @user.errors.full_messages.each do |msg| %>
+        <li><%= msg %></li>
+      <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <div class="field">
+    <%= f.label :name %><br />
+    <%= f.text_field :name %>
+  </div>
+  <div class="field">
+    <%= f.label :password %><br />
+    <%= f.text_field :password %>
+  </div>
+  <div class="field">
+    <%= f.label :email %><br />
+    <%= f.text_field :email %>
+  </div>
+  <div class="actions">
+    <%= f.submit %>
+  </div>
+<% end %>

data/test/dummy/app/views/users/edit.html.erb

@@ -0,0 +1,6 @@
+<h1>Editing user</h1>
+
+<%= render 'form' %>
+
+<%= link_to 'Show', @user %> |
+<%= link_to 'Back', users_path %>

data/test/dummy/app/views/users/index.html.erb

@@ -0,0 +1,27 @@
+<h1>Listing users</h1>
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Password</th>
+    <th>Email</th>
+    <th></th>
+    <th></th>
+    <th></th>
+  </tr>
+
+<% @users.each do |user| %>
+  <tr>
+    <td><%= user.name %></td>
+    <td><%= user.password %></td>
+    <td><%= user.email %></td>
+    <td><%= link_to 'Show', user %></td>
+    <td><%= link_to 'Edit', edit_user_path(user) %></td>
+    <td><%= link_to 'Destroy', user, confirm: 'Are you sure?', method: :delete %></td>
+  </tr>
+<% end %>
+</table>
+
+<br />
+
+<%= link_to 'New User', new_user_path %>

data/test/dummy/app/views/users/new.html.erb

@@ -0,0 +1,5 @@
+<h1>New user</h1>
+
+<%= render 'form' %>
+
+<%= link_to 'Back', users_path %>

data/test/dummy/app/views/users/show.html.erb

@@ -0,0 +1,20 @@
+<p id="notice"><%= notice %></p>
+
+<p>
+  <b>Name:</b>
+  <%= @user.name %>
+</p>
+
+<p>
+  <b>Password:</b>
+  <%= @user.password %>
+</p>
+
+<p>
+  <b>Email:</b>
+  <%= @user.email %>
+</p>
+
+
+<%= link_to 'Edit', edit_user_path(@user) %> |
+<%= link_to 'Back', users_path %>

data/test/dummy/config/database_example.yml

@@ -0,0 +1,25 @@
+# SQLite version 3.x
+#   gem install sqlite3
+#
+#   Ensure the SQLite 3 gem is defined in your Gemfile
+#   gem 'sqlite3'
+development:
+  adapter: sqlite3
+  database: db/development.sqlite3
+  pool: 5
+  timeout: 5000
+
+# Warning: The database defined as "test" will be erased and
+# re-generated from your development database when you run "rake".
+# Do not set this db to the same as development or production.
+test:
+  adapter: sqlite3
+  database: db/test.sqlite3
+  pool: 5
+  timeout: 5000
+
+production:
+  adapter: sqlite3
+  database: db/production.sqlite3
+  pool: 5
+  timeout: 5000

data/test/dummy/config/initializers/secret_token.rb

@@ -4,4 +4,4 @@
 # If you change this key, all old signed cookies will become invalid!
 # Make sure the secret is at least 30 characters and all random,
 # no regular words or you'll be exposed to dictionary attacks.
-Dummy::Application.config.secret_token = 'd4225e808462cc2cc06cdc92a45ba129fcd1030eb0a28521f3e96c4bdc3633646db81939d7b548cce87965a3e453e910cb6a54bec92a3820c220e9b18b3698de'
+Dummy::Application.config.secret_token = 'ad4026366010c90ed5b554f3c9fd6b6c23377f5f071842f365fb583ed657fe0d827b49b8b07ef6441d0723333c6190ac06ce869298a8fae47ef5fa0b42485933'

data/test/dummy/config/initializers/session_logger.rb

@@ -0,0 +1,17 @@
+# The configure step must be run right before the after_initialize callback
+# This allows both tests (which don't wait for after_initialize) and the app
+# to get the appropriate models after they have been initialized. The to_prepare
+# call is the prefect callback for preparing plugins
+Rails.application.config.to_prepare do
+  SessionLogger.configure do |config|
+
+    # Default is to observe all models in the models dir
+    config.logged_models = Dir["#{Rails.root}/app/models/**/*.rb"].map { |f| File.basename(f, '.*').camelize.constantize }
+
+    # Performance optimization for only observing certain models
+    # config.logged_models = [User]
+
+    # Customizable model prefixing
+    # config.model_prefix = "sl_"
+  end
+end

data/test/dummy/config/routes.rb

@@ -1,4 +1,60 @@
-Rails.application.routes.draw do
+Dummy::Application.routes.draw do
+  resources :users
 
-  mount SessionLogger::Engine => "/session_logger"
+  # The priority is based upon order of creation:
+  # first created -> highest priority.
+
+  # Sample of regular route:
+  #   match 'products/:id' => 'catalog#view'
+  # Keep in mind you can assign values other than :controller and :action
+
+  # Sample of named route:
+  #   match 'products/:id/purchase' => 'catalog#purchase', :as => :purchase
+  # This route can be invoked with purchase_url(:id => product.id)
+
+  # Sample resource route (maps HTTP verbs to controller actions automatically):
+  #   resources :products
+
+  # Sample resource route with options:
+  #   resources :products do
+  #     member do
+  #       get 'short'
+  #       post 'toggle'
+  #     end
+  #
+  #     collection do
+  #       get 'sold'
+  #     end
+  #   end
+
+  # Sample resource route with sub-resources:
+  #   resources :products do
+  #     resources :comments, :sales
+  #     resource :seller
+  #   end
+
+  # Sample resource route with more complex sub-resources
+  #   resources :products do
+  #     resources :comments
+  #     resources :sales do
+  #       get 'recent', :on => :collection
+  #     end
+  #   end
+
+  # Sample resource route within a namespace:
+  #   namespace :admin do
+  #     # Directs /admin/products/* to Admin::ProductsController
+  #     # (app/controllers/admin/products_controller.rb)
+  #     resources :products
+  #   end
+
+  # You can have the root of your site routed with "root"
+  # just remember to delete public/index.html.
+  # root :to => 'welcome#index'
+
+  # See how all your routes lay out with "rake routes"
+
+  # This is a legacy wild controller route that's not recommended for RESTful applications.
+  # Note: This route will make all actions in every controller accessible via GET requests.
+  # match ':controller(/:action(/:id(.:format)))'
 end

data/test/dummy/db/migrate/20111104001311_create_users.rb

@@ -0,0 +1,11 @@
+class CreateUsers < ActiveRecord::Migration
+  def change
+    create_table :users do |t|
+      t.string :name
+      t.string :password
+      t.string :email
+
+      t.timestamps
+    end
+  end
+end

data/test/dummy/db/migrate/20111105072946_add_sl_campaign_to_user.rb

@@ -0,0 +1,5 @@
+class AddSlCampaignToUser < ActiveRecord::Migration
+  def change
+    add_column :users, :sl_campaign, :string
+  end
+end

data/test/dummy/db/schema.rb

@@ -0,0 +1,25 @@
+# encoding: UTF-8
+# This file is auto-generated from the current state of the database. Instead
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
+#
+# Note that this schema.rb definition is the authoritative source for your
+# database schema. If you need to create the application database on another
+# system, you should be using db:schema:load, not running all the migrations
+# from scratch. The latter is a flawed and unsustainable approach (the more migrations
+# you'll amass, the slower it'll run and the greater likelihood for issues).
+#
+# It's strongly recommended to check this file into your version control system.
+
+ActiveRecord::Schema.define(:version => 20111105072946) do
+
+  create_table "users", :force => true do |t|
+    t.string   "name"
+    t.string   "password"
+    t.string   "email"
+    t.datetime "created_at"
+    t.datetime "updated_at"
+    t.string   "sl_campaign"
+  end
+
+end