fine_print 0.1.1 → 1.0.0

data/config/initializers/fine_print.rb~

@@ -1,53 +1,36 @@
 # Change the settings below to suit your needs
 # All settings are initially set to their default values
 FinePrint.configure do |config|
-
-  # Engine Options (initializer only)
+  # Engine Configuration
 
   # Name of the ApplicationController helper method that returns the current user
-  # Default: "current_user"
-  config.current_user_method = "current_user"
+  # Default: 'current_user'
+  config.current_user_method = 'current_user'
 
   # Proc called with user as argument that should return true if and only if the user is an admin
   # Admins can create and edit agreements and terminate accepted agreements
   # Default: lambda { |user| false } (no admins)
   config.user_admin_proc = lambda { |user| false }
 
-  # Path to redirect users to when an error occurs (e.g. permission denied on admin pages)
-  # Default: "/"
-  config.redirect_path = "/"
-
-  # Path to link users to if they need to sign in
-  # Set to nil to disable the link
-  # Default: "/"
-  config.sign_in_path = "/"
-
-
-
-  # Agreement Options (initializer or inline)
+  # Proc that returns true if and only if the provided user is logged in
+  # In many systems, a non-logged-in user is represented by nil
+  # However, some systems use something like an AnonymousUser class to represent this state
+  # This proc is mostly used to help the developer realize that they should only be asking
+  # signed in users to sign contracts; without this, developers would get a cryptic SQL error
+  # Default: lambda { |user| !user.nil? }
+  config.user_signed_in_proc = lambda { |user| !user.nil? }
 
-  # Message to be displayed to the user explaining that they need to accept an agreement
-  # Set to nil to disable
-  # Default: "You must accept the following agreement to proceed."
-  config.agreement_notice = "You must accept the following agreement to proceed."
-
-  # Path to redirect users to when an agreement is accepted and referer information is unavailable
-  # Default: "/"
-  config.accept_path = "/"
-
-  # Path to redirect users to when an agreement is not accepted and referer information is unavailable
-  # Default: "/"
-  config.cancel_path = "/"
-
-  # Whether to use referer information to redirect users after (not) accepting an agreement
-  # Default: true
-  config.use_referers = true
-
-  # If set to true, modal jQuery UI dialogs will be used instead of redirecting the user to the agreement page
-  # Note: users with javascript disabled will not even see the agreement and will be able to proceed without accepting it
-  #       if users are not supposed to ever see or interact with a certain page without accepting the agreement,
-  #       disable this option for that particular controller action
-  # Default: false
-  config.use_modal_dialogs = false
-  
+  # Path to redirect users to when an error occurs (e.g. permission denied on admin pages)
+  # Default: '/'
+  config.redirect_path = '/'
+
+  # Signature (fine_print_get_signatures) Configuration
+
+  # Path to redirect users to when they need to agree to contract(s)
+  # A list of contract names that must be agreed to will be available in the 'contracts' parameter
+  # Your code doesn't have to deal with all of them at once, e.g. you can get
+  # the user to agree to the first one and then they'll just eventually be
+  # redirected back to this page with the remaining contract names
+  # Default: '/'
+  config.pose_contracts_path = '/'
 end

data/config/routes.rb

@@ -1,7 +1,13 @@
 FinePrint::Engine.routes.draw do
-  resources :agreements do
-    get :new_version
+  resources :contracts do
+    member do
+      get :new_version
+      put :publish
+      put :unpublish
+    end
   end
-  resources :user_agreements, :only => [:index, :create, :destroy]
+
+  resources :signatures, :only => [:index, :destroy]
+
   root :to => 'home#index'
 end

data/config/routes.rb~

@@ -1,7 +1,12 @@
 FinePrint::Engine.routes.draw do
-  resources :agreements do
-    get :new_version
+  resources :contracts do
+    member do
+    get :new_version, :on => :member
+    put :publish, :on => :member
+    put :unpublish, :on => :member
   end
-  resources :user_agreements, :only => [:index, :create, :destroy]
-  root :to => 'agreements#index'
+
+  resources :signatures, :only => [:index, :destroy]
+
+  root :to => 'home#index'
 end

data/db/migrate/0_install_fine_print.rb

@@ -0,0 +1,26 @@
+class InstallFinePrint < ActiveRecord::Migration
+  def change
+    create_table :fine_print_contracts do |t|
+      t.string :name, :null => false
+      t.integer :version
+      t.string :title, :null => false
+      t.text :content, :null => false
+
+      t.timestamps
+    end
+
+    add_index :fine_print_contracts, [:name, :version], :unique => true
+
+    create_table :fine_print_signatures do |t|
+      t.belongs_to :contract, :null => false
+      t.belongs_to :user, :polymorphic => true, :null => false
+
+      t.timestamps
+    end
+
+    add_index :fine_print_signatures, :contract_id
+    add_index :fine_print_signatures, [:user_id, :user_type, :contract_id], 
+                                      :name => 'index_fine_print_s_on_u_id_and_u_type_and_c_id',
+                                      :unique => true
+  end
+end

data/db/migrate/0_install_fine_print.rb~

@@ -0,0 +1,26 @@
+class InstallFinePrint < ActiveRecord::Migration
+  def change
+    create_table :fine_print_contracts do |t|
+      t.string :name, :null => false
+      t.integer :version
+      t.string :title, :null => false, :default => ''
+      t.text :content, :null => false, :default => ''
+
+      t.timestamps
+    end
+
+    add_index :fine_print_contracts, [:name, :version], :unique => true
+
+    create_table :fine_print_signatures do |t|
+      t.belongs_to :contract, :null => false
+      t.belongs_to :user, :polymorphic => true, :null => false
+
+      t.timestamps
+    end
+
+    add_index :fine_print_signatures, :contract_id
+    add_index :fine_print_signatures, [:user_id, :user_type, :contract_id], 
+                                      :name => 'index_fine_print_s_on_u_id_and_u_type_and_c_id',
+                                      :unique => true
+  end
+end

data/lib/fine_print/controller_additions.rb

@@ -0,0 +1,69 @@
+module FinePrint
+  module ControllerAdditions
+    #
+    # Internally these methods think of contract names as strings, not symbols.
+    # Any names passed in as symbols are converted to strings.
+    #
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def fine_print_skipped_contract_names
+      @fine_print_skipped_contract_names ||= []
+    end
+
+    # See the README
+    def fine_print_return
+      redirect_to session.delete(:fine_print_return_to) || root_path
+    end
+
+    module ClassMethods
+      # See the README
+      def fine_print_get_signatures(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+
+        filter_options = options.except(*FinePrint::SIGNATURE_OPTIONS)
+        fine_print_options = options.slice(*FinePrint::SIGNATURE_OPTIONS)
+
+        # Convert all names to string
+        names = args.collect{|n| n.to_s}
+
+        class_eval do
+          before_filter(filter_options) do |controller|
+            names_to_check = names - fine_print_skipped_contract_names
+
+            # Bail if nothing to do
+            return true if names_to_check.blank?
+
+            user = send FinePrint.current_user_method
+            FinePrint.raise_unless_signed_in(user)
+
+            unsigned_contract_names = 
+              FinePrint.get_unsigned_contract_names(names_to_check, user)
+            return true if unsigned_contract_names.empty?
+
+            # http://stackoverflow.com/a/2165727/1664216
+            session[:fine_print_return_to] = "#{request.protocol}#{request.host_with_port}#{request.fullpath}"
+            # http://stackoverflow.com/a/6561953
+            path = fine_print_options[:pose_contracts_path] || FinePrint.pose_contracts_path
+            redirect_to path + (path.include?('?') ? '&' : '?') + {:terms => unsigned_contract_names}.to_query
+          end
+        end
+      end
+
+      # See the README
+      def fine_print_skip_signatures(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        names = args.collect{|arg| arg.to_s}
+
+        class_eval do
+          prepend_before_filter(options) do |controller|
+            fine_print_skipped_contract_names.push(*names)
+          end
+        end
+      end
+    end
+  end
+end
+
+ActionController::Base.send :include, FinePrint::ControllerAdditions

data/lib/fine_print/controller_additions.rb~

@@ -0,0 +1,69 @@
+module FinePrint
+  module ControllerAdditions
+    #
+    # Internally these methods think of contract names as strings, not symbols.
+    # Any names passed in as symbols are converted to strings.
+    #
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def fine_print_skipped_contract_names
+      @fine_print_skipped_contract_names ||= []
+    end
+
+    # See the README
+    def fine_print_return
+      redirect_to root_path
+    end
+
+    module ClassMethods
+      # See the README
+      def fine_print_get_signatures(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+
+        filter_options = options.except(*FinePrint::SIGNATURE_OPTIONS)
+        fine_print_options = options.slice(*FinePrint::SIGNATURE_OPTIONS)
+
+        # Convert all names to string
+        names = args.collect{|n| n.to_s}
+
+        class_eval do
+          before_filter(filter_options) do |controller|
+            names_to_check = names - fine_print_skipped_contract_names
+
+            # Bail if nothing to do
+            return true if names_to_check.blank?
+
+            user = send FinePrint.current_user_method
+            FinePrint.raise_unless_signed_in(user)
+
+            unsigned_contract_names = 
+              FinePrint.get_unsigned_contract_names(names_to_check, user)
+            return true if unsigned_contract_names.empty?
+
+            # http://stackoverflow.com/a/2165727/1664216
+            session[:fine_print_return_to] = "#{request.protocol}#{request.host_with_port}#{request.fullpath}"
+            # http://stackoverflow.com/a/6561953
+            path = fine_print_options[:pose_contracts_path] || FinePrint.pose_contracts_path
+            redirect_to path + (path.include?('?') ? '&' : '?') + {:terms => unsigned_contract_names}.to_query
+          end
+        end
+      end
+
+      # See the README
+      def fine_print_skip_signatures(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        names = args.collect{|arg| arg.to_s}
+
+        class_eval do
+          prepend_before_filter(options) do |controller|
+            fine_print_skipped_contract_names.push(*names)
+          end
+        end
+      end
+    end
+  end
+end
+
+ActionController::Base.send :include, FinePrint::ControllerAdditions

data/lib/fine_print/engine.rb

@@ -1,5 +1,13 @@
 module FinePrint
   class Engine < ::Rails::Engine
     isolate_namespace FinePrint
+
+    # http://viget.com/extend/rails-engine-testing-with-rspec-capybara-and-factorygirl
+    config.generators do |g|
+      g.test_framework      :rspec,        :fixture => false
+      g.fixture_replacement :factory_girl, :dir => 'spec/factories'
+      g.assets false
+      g.helper false
+    end
   end
 end

data/lib/fine_print/security_transgression.rb

@@ -1,4 +1,3 @@
 module FinePrint
-  class SecurityTransgression < StandardError
-  end
+  class SecurityTransgression < StandardError; end
 end

data/lib/fine_print/utilities.rb~

@@ -0,0 +1,26 @@
+module FinePrint
+  module Utilities
+    # Returns true iff the given user has signed any version of the given contract.
+    #   contract -- can be a Contract object, its ID, or its name as a String or Symbol
+    def self.any_signed_contract_version?(contract, user)
+      contract = FinePrint::get_contract(contract)
+      !user.nil? && 
+      !Signature.joins(:contract)
+                .where(:contract => {:name => contract.name},
+                       :user_type => user.class.name,
+                       :user_id => user.id).first.nil?
+    end
+
+    # Returns the latest version of the named contract (since contracts don't have
+    # versions until they are published this only returns published contracts).
+    # If no such contract exists, returns nil.  
+    #   name -- can be a String or a Symbol
+    def self.latest_contract_named(name)
+      name = name.to_s
+      contract = Contract.where(:name => name).published.first
+      raise IllegalState, "Published version of #{name} not found" \
+        if contract.nil?
+      contract
+    end
+  end
+end

data/lib/fine_print/version.rb

@@ -1,3 +1,3 @@
 module FinePrint
-  VERSION = "0.1.1"
+  VERSION = '1.0.0'
 end

data/lib/fine_print.rb

@@ -1,69 +1,116 @@
-require "fine_print/engine"
-require "fine_print/fine_print_agreement"
+require 'fine_print/engine'
+require 'fine_print/security_transgression'
+require 'fine_print/controller_additions'
 
 module FinePrint
-  ASSET_FILES = %w(dialog.js)
-
   # Attributes
 
   # Can be set in initializer only
   ENGINE_OPTIONS = [
     :current_user_method,
     :user_admin_proc,
-    :redirect_path,
-    :sign_in_path
+    :user_signed_in_proc,
+    :pose_contracts_path,
+    :redirect_path
   ]
 
-  # Can be set in initializer or passed as an option to fine_print_agreement
-  AGREEMENT_OPTIONS = [
-    :agreement_notice,
-    :accept_path,
-    :cancel_path,
-    :use_referers,
-    :use_modal_dialogs
+  # Can be set in initializer or passed as an option to fine_print_get_signatures
+  SIGNATURE_OPTIONS = [
+    :pose_contracts_path
   ]
   
-  (ENGINE_OPTIONS + AGREEMENT_OPTIONS).each do |option|
+  (ENGINE_OPTIONS + SIGNATURE_OPTIONS).each do |option|
     mattr_accessor option
   end
-
-  ActiveSupport.on_load(:before_initialize) do
-    Rails.configuration.assets.precompile += ASSET_FILES
-  end
   
   def self.configure
     yield self
   end
 
-  def self.get_option(options, name)
-    (!options.nil? && !options[name].nil?) ? options[name] : self.send(name)
+  # Gets a contract given either the contract's object, ID or name
+  # If given a name, it returns the latest published version of that contract
+  #
+  def self.get_contract(reference)
+    ref = Integer(reference) rescue reference
+    case ref
+    when Contract
+      ref
+    when Integer
+      Contract.find(ref)
+    when String
+      Contract.where(:name => ref).published.first
+    end
+  end
+
+  # Returns an array of names for the contracts whose latest published
+  # version the given user has not signed.
+  #   - names -- an array of contract names
+  #   - user -- the user in question
+  #
+  def self.get_unsigned_contract_names(names, user)
+    raise_unless_signed_in(user)
+    return [] if names.blank?
+    names_array = names.is_a?(Array) ? names.collect{|name| name.to_s} : [names.to_s]
+
+    signed_contracts = Contract
+      .joins(:signatures)
+      .where({:name => names_array,
+              :fine_print_signatures => {:user_id => user.id,
+                              :user_type => user.class.name}}).latest
+    signed_contract_names = signed_contracts.collect{|c| c.name}
+
+    return names - signed_contract_names
   end
 
-  def self.require_agreements(controller, names, options)
-    user = controller.send current_user_method
-    fine_print_dialog_agreements = []
-    names.each do |name|
-      agreement = Agreement.latest_ready(name)
-      next if agreement.nil? || agreement.accepted_by?(user)
-      if get_option(options, :use_modal_dialogs)
-        fine_print_dialog_agreements << agreement
-      else
-        controller.session[:fine_print_accept_path] = options[:accept_path]
-        controller.session[:fine_print_cancel_path] = options[:cancel_path]
-        if get_option(options, :use_referers)
-          controller.session[:fine_print_request_url] = controller.request.url
-          controller.session[:fine_print_request_ref] = controller.request.referer
-        end
-        controller.redirect_to controller.fine_print.agreement_path(agreement),
-          :notice => get_option(options, :agreement_notice)
-      end
+  # Records that the given user has signed the given contract; the contract
+  # can be a Contract object, a contract ID, or a contract name (string)
+  #
+  def self.sign_contract(contract, user)
+    raise_unless_signed_in(user)
+    contract = get_contract(contract)
+    raise IllegalState, 'Contract not found' if contract.nil?
+
+    Signature.create do |signature|
+      signature.user = user
+      signature.contract = contract
     end
-    controller.instance_variable_set(:@fine_print_dialog_agreements, fine_print_dialog_agreements)
-    controller.instance_variable_set(:@fine_print_user, user)
-    controller.instance_variable_set(:@fine_print_dialog_notice, get_option(options, :agreement_notice))
+  end
+
+  # Returns true iff the given user has signed the given contract; the contract
+  # can be a Contract object, a contract ID, or a contract name (string)
+  #
+  def self.signed_contract?(contract, user)
+    raise_unless_signed_in(user)
+    contract = get_contract(contract)
+
+    !contract.signatures.where(:user_id => user.id,
+                               :user_type => user.class.name).first.nil?
+  end
+
+  # Returns true iff the given user has signed any version of the given contract.
+  #   - contract -- can be a Contract object, its ID, or its name as a String or Symbol
+  def self.signed_any_contract_version?(contract, user)
+    raise_unless_signed_in(user)
+    contract = get_contract(contract)
+    !Signature.joins(:contract)
+              .where(:fine_print_contracts => {:name => contract.name},
+                     :user_type => user.class.name,
+                     :user_id => user.id).first.nil?
+  end
+
+  def self.is_signed_in?(user)
+    user_signed_in_proc.call(user)
   end
 
   def self.is_admin?(user)
-    !user.nil? && user_admin_proc.call(user)
+    is_signed_in?(user) && user_admin_proc.call(user)
+  end
+
+  def self.raise_unless_signed_in(user)
+    raise IllegalState, 'User not signed in' unless is_signed_in?(user)
+  end
+
+  def self.raise_unless_admin(user)
+    raise SecurityTransgression unless is_admin?(user)
   end
 end