fine_print 1.3.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1b2e32a76793d71e6cf6ac6971ba125269c52658
-  data.tar.gz: a95a87faf71c9aefb4bc80d7a7516dfc47c18c49
+  metadata.gz: 5ae19efef1a93bef86de360020973d0c72e58e74
+  data.tar.gz: fd9d302b91cebd30ad20e4aaac6530c0d9d29e95
 SHA512:
-  metadata.gz: 4362c6e678e9ce7eeeebf1f5553e6267b1c7a3a6285ac4663966763a58bca44ec0652b06af57c271c4ac81f654c6fa469e15d220c5780da92f133fb8df422cbe
-  data.tar.gz: b11890e37902d3e00c403ed3b4a6459cb76ff8827f54a99634e7086180124ab3db85d3f66176bc43f4f9f7fe96149bd8370d76f33db75955b274f2032670ea75
+  metadata.gz: eb8a60a9956d17a72e7b8b59725d6ca269a7103ddd1219ad9318b68662b34ec4384ee3529294aae6d1706835e4ade31e5f53a97dfe6fd30434d2bdff95ad4661
+  data.tar.gz: 212e0c1badbd251eba90272f370ef6e77d96755ade8e067ef3c2cd780c618f2b53b064e5ea0b354e0ceb3d0eb6666bef6bbb0557dddd1a2bbd583c56fa2977dd

data/README.md

@@ -46,7 +46,7 @@ Also add FinePrint to your application's routes:
 mount FinePrint::Engine => "/fine_print"
 ```
 
-And provide a link on your site for administrators to access the FinePrint engine to manage contracts.
+And provide a link on your site for administrators to access the FinePrint engine to manage your contracts.
 
 ```erb
 <%= link_to 'FinePrint', fine_print_path %>
@@ -56,37 +56,28 @@ And provide a link on your site for administrators to access the FinePrint engin
 
 After installation, the initializer for FinePrint will be located under `config/initializers/fine_print.rb`.
 Make sure to configure it to suit your needs.
-Pay particular attention to `user_admin_proc`, as you will be unable to manage your contracts unless you set up this proc to return true for your admins.
+Pay particular attention to `user_admin_proc`, as you will be unable to manage your contracts unless you setup this proc to return true for your admins.
 
 ## Usage
 
-The FinePrint module contains several methods that help you find contracts and mark them as signed:
+You can choose to check if users signed contracts either as a before_filter or inside your controller actions.
 
-`get_contract(contract_object_or_id_or_name)`
-`sign_contract(user, contract_object_or_id_or_name)`
-`signed_contract?(user, contract_object_or_id_or_name)`
-`signed_any_contract_version?(user, contract_object_or_id_or_name)`
-`get_unsigned_contract_names(user, contract_names...)`
+### Option 1 - As a before_filter
 
-Additionally, FinePrint adds 2 class methods to all of your controllers:
+If you choose to have FinePrint work like a before_filter, you can user the following 2 class methods, which are automatically added to all of your controllers:
 
-`fine_print_get_signatures(contract_names..., options_hash)`
-`fine_print_skip_signatures(contract_names..., options_hash)`
-
-And 1 instance method, also to all of your controllers:
-
-`fine_print_return`
+```rb
+fine_print_get_signatures(contract_names..., options_hash)
+fine_print_skip_signatures(contract_names..., options_hash)
+```
 
 To require that your users sign the most recent version of a contract, call
-`fine_print_get_signatures` in your controllers, just as you would a
-`before_filter` (in fact, this method works by adding a `before_filter` for you).
+`fine_print_get_signatures` in your controller classes. It works just like a `before_filter` (in fact, it will add a `before_filter` for you).
 
-This method takes a list of contract names (given either as strings or as 
+This method takes a list of contract names to check (given either as strings or as 
 symbols), along with an options hash.
 
-The options hash can include any options you could pass to a `before_filter`, e.g. `only` and `except`,
-plus the FinePrint-specific option `pose_contracts_path`, which can override the value specified
-in the FinePrint initializer.
+The options hash can include any options you could pass to a `before_filter`, e.g. `only` and `except`, plus the FinePrint-specific options `contracts_path`, which can override the value specified in the FinePrint initializer.
 
 Example:
 
@@ -96,16 +87,11 @@ class MyController < ApplicationController
                             :except => :index
 ```
 
-You should only try to get signatures when you have a user who is logged in
-(FinePrint will allow non-logged in users to pass right through without signing
-anything).  This normally means that before the call to `fine_print_get_signatures`
-you should call whatever `before_filter` gets a user to login.
+You should only try to get signatures when you have a user who is logged in (by default FinePrint will allow non-logged in users to pass right through without signing anything).  This normally means that before the call to `fine_print_get_signatures` you should call whatever `before_filter` gets a user to login.
 
-Just like how rails provides a `skip_before_filter` method to offset `before_filter` calls,
-FinePrint provides a `fine_print_skip_signatures` method.  This method takes the same
-arguments as before_filter, and can be called either before or after `fine_print_get_signatures`.
+Just like how rails provides a `skip_before_filter` method to offset `before_filter` calls, FinePrint provides a `fine_print_skip_signatures` method.  This method takes the same arguments as before_filter, and can be called either before or after `fine_print_get_signatures`.
 
-One way you may want to use these methods is to require signatures in every controller
+One way you can use these methods is to require signatures in every controller
 by default, and then to skip them in certain situations, e.g.:
 
 ```rb
@@ -118,22 +104,48 @@ class NoSigsRequiredController < ApplicationController
   fine_print_skip_signatures :terms_of_use
 ```
 
-When a set of contracts is found by FinePrint to be required but unsigned, FinePrint redirects
-the user to the path specified by the `pose_contracts_path` configuration variable, with
-the names of the unsigned contracts passed along in a `terms` array in the URL parameters.
+### Option 2 - Inside your controller actions
+
+If instead you have to check for contracts inside controller action methods, you can use the following 2 instance methods, also automatically added to all of your controllers:
+
+```rb
+fine_print_get_unsigned_contract_names(contract_names)
+fine_print_redirect(unsigned_contract_names)
+```
+
+This can be done in one line, like so:
+
+```rb
+fine_print_redirect(fine_print_get_unsigned_contract_names(contract_names))
+```
+
+The `fine_print_get_unsigned_contract_names` method can return nil if no contracts are provided or if the user cannot sign contracts; otherwise, it returns an array of the contract names the user has not yet signed.
+
+Keep in mind that `fine_print_redirect` might cause a redirect, so if your controller action also needs to redirect, you should check the output of `fine_print_get_unsigned_contract_names`. This method will not redirect the user if either the array of contract names to sign is blank or if the user_can_sign_proc returns false when called with the user as an argument.
+
+### Displaying and signing contracts
+
+When a set of contracts is found by FinePrint to be required but unsigned, and the user is allowed to sign contracts, FinePrint redirects the user to the path specified by the `contract_redirect_path` configuration variable, with the names of the unsigned contracts passed along in the params hash. The param key for the unsigned contract names array is determined by the `contract_param_name` configuration variable (default is :contracts).
+
+Your job as the site developer is to present the terms to the user and ask them to sign them. This normally involves the user clicking an "I have read the above terms" checkbox which enables an "I Agree" button. When the "Agree" button is clicked (and you should verify that the checkbox is actually clicked in the params passed to the server), you need to send the information off to a controller method that will mark the contract as signed using the `FinePrint.sign_contract` method. The following methods in the FinePrint module can be used to help you find contract objects and mark them as signed:
+
+```rb
+FinePrint.get_contract(contract_object_or_id_or_name)
+FinePrint.sign_contract(user, contract_object_or_id_or_name)
+FinePrint.signed_contract?(user, contract_object_or_id_or_name)
+FinePrint.signed_any_contract_version?(user, contract_object_or_id_or_name)
+FinePrint.get_unsigned_contract_names(user, contract_names...)
+```
+
+If you require more explanation about these methods and their arguments, check the `lib/fine_print.rb` file.
+
+### Redirecting users back
 
-Your job as the site developer is to present the terms to the user and ask them to sign them.
-This normally involves the user clicking an "I have read the above terms" checkbox which enables an "I Agree" button.
-When the "Agree" button is clicked (and you should verify that the checkbox is actually clicked in the params passed to the server),
-you need to send the information off to a controller method that can call `FinePrint.sign_contract` which takes
-a user and a contract name, ID, or object. On success, this controller method can send the user back to where
-they were trying to go by calling the `fine_print_return` controller method (only works for GET requests).
+Regardless if you use `fine_print_get_signatures` or `fine_print_redirect`, after your contract is signed you can use the `fine_print_return` controller instance method to send the user back to the place where they came from.
 
 If there are multiple unsigned contracts, you are not required to get the user to sign
-them all in one page.  One strategy is to present only the first unsigned contract to them
-for signature.  Once they sign it, they'll be redirected to where they were trying to 
-go and FinePrint will see again that they still have remaining unsigned contracts, and
-FinePrint will direct them back to your `pose_contracts_path` with one fewer contract
+them all at once.  One strategy is to present only the first unsigned contract to them.  Once they sign it, they'll be redirected to where they were trying to 
+go and FinePrint will once again determine that they still have remaining unsigned contracts, and redirect them back to your `contract_redirect_path` with one less contract
 name passed in.
 
 ## Managing Contracts
@@ -141,12 +153,12 @@ name passed in.
 Here are some important notes about managing your contracts with FinePrint:
 
 - Contracts have a name and a title; the former is used by your code, the latter 
-is intended for display to end users.
+is intended for display to end users and even site admins.
 - Creating another contract with the same name as an existing contract will make it a new version of that existing contract.
 - Contracts need to be explicitly published to be available to users to sign (this can be done on the contracts admin page).
 - The latest published version is what users will see.
 - A contract cannot be modified after at least one user has signed it, but you can always create a new version.
-- When a published contract version is available but has not been signed, users will be asked to accept it the next time they visit a controller action that calls `fine_print_get_signatures` for that contract's name.
+- When a published contract version is available but has not been signed, users will be asked to accept it the next time they visit a controller action that calls either `fine_print_get_signatures` or the controller fine_print instance methods with that contract's name.
 
 ## Customization
 

data/app/controllers/fine_print/application_controller.rb

@@ -2,9 +2,6 @@ module FinePrint
   class ApplicationController < ActionController::Base
     before_filter :verify_admin
 
-    rescue_from FinePrint::SecurityTransgression, 
-                :with => lambda { redirect_to FinePrint.redirect_path }
-
     protected
 
     def verify_admin

data/app/models/fine_print/contract.rb

@@ -12,14 +12,15 @@ module FinePrint
     validates_format_of :name, :with => /\A\w+\z/
     validates_uniqueness_of :version, :scope => :name, :case_sensitive => false
 
-    default_scope order(:name, 'version DESC')
-
-    scope :published, where(arel_table[:version].not_eq(nil))
-    scope :latest, published
-      .joins(:same_name)
-      .group(:id)
-      .having(:version => arel_table.alias(:same_names_fine_print_contracts)[:version]
-                          .maximum.tap{|mvq| mvq.alias = nil})
+    default_scope { order(:name, 'version DESC') }
+
+    scope :published, lambda { where(arel_table[:version].not_eq(nil)) }
+    scope :latest, lambda {
+      published.joins(:same_name)
+               .group('fine_print_contracts.id')
+               .having(:version =>
+                       arel_table.alias(:same_names_fine_print_contracts)[:version].maximum.tap{|mvq| mvq.alias = nil})
+    }
 
     def is_published?
       !version.nil?

data/app/models/fine_print/signature.rb

@@ -8,7 +8,7 @@ module FinePrint
     validates_presence_of :contract, :user_type, :user_id
     validates_uniqueness_of :contract_id, :scope => [:user_type, :user_id]
 
-    default_scope order(:contract_id, :user_type, :user_id)
+    default_scope { order(:contract_id, :user_type, :user_id) }
 
     protected
 

data/config/initializers/fine_print.rb

@@ -1,37 +1,41 @@
 # Change the settings below to suit your needs
-# All settings are initially set to their default values
+# All options are initially set to their default values
 FinePrint.configure do |config|
   # Engine Configuration
 
-  # Proc called with controller as argument that returns the current user.
+  # Proc called with a controller as argument.
+  # Returns the current user.
   # Default: lambda { |controller| controller.current_user }
   config.current_user_proc = lambda { |controller| controller.current_user }
 
-  # Proc called with user as argument that returns true iif the user is an admin.
+  # Proc called with a user as argument.
+  # Returns true iif 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 }
 
-  # Proc called with user as argument that returns true iif the argument is a user
-  # who can sign a contract.  In many systems, a non-logged-in user is represented by nil.
+  # Proc called with a user as argument
+  # Returns true iif the argument the user is allowed to sign a contract.
+  # 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.
-  # If this proc returns false, FinePrint will not ask for signatures and will allow access
-  # to any page, so it's up to the developer to make sure that unsigned users can't access
-  # pages that require a contract signature to use.
-  # Default: lambda { |user| user }
-  config.can_sign_contracts_proc = lambda { |user| user }
+  # If this proc returns false, FinePrint will not ask for signatures and will not redirect the user, so it's up to the developer to make sure that unsigned users can't access pages that should require a signed contract to use.
+  # Default: lambda { |user| !!user }
+  config.user_can_sign_proc = lambda { |user| !!user }
 
-  # 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
+
+  # Contract Configuration
+
+  # What to call the contract names param, passed when the user is redirected
+  # This is visible to the user in the Url
+  # Default: 'contracts'
+  config.contract_param_name = 'contracts'
 
   # 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.
+  # A list of contract names that must be agreed to will be available in the `contract_param_name` 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 = '/'
+  config.contract_redirect_path = '/'
 end

data/db/migrate/0_install_fine_print.rb

@@ -19,8 +19,9 @@ class InstallFinePrint < ActiveRecord::Migration
     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
+    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_includes.rb

@@ -0,0 +1,114 @@
+module FinePrint
+  module ControllerIncludes
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # For the following methods, names passed as Symbols are converted to Strings.
+
+    # Accepts an array of contract names
+    # Returns nil if the array is blank or the current user cannot sign contracts
+    # Otherwise, returns the contract names that the user hasn't signed yet
+    def fine_print_get_unsigned_contract_names(*contract_names)
+      # Convert names to an array of Strings
+      names = contract_names.flatten.collect{|n| n.to_s}
+
+      user = FinePrint.current_user_proc.call(self)
+      
+      # If the user isn't signed in, they can't sign a contract
+      # Since there may be some pages that both logged in and non-logged in users
+      # can visit, we just return quietly instead of raising an exception
+      return nil if names.blank? || !FinePrint.can_sign?(user)
+
+      # Ignore contracts that don't yet exist or aren't yet published (happens 
+      # when adding code that requires a new contract but before that contract 
+      # has been added and published)
+      FinePrint.get_unsigned_contract_names(user, names)
+               .reject{|name| FinePrint.get_contract(name).blank?}
+    end
+
+    # Accepts an array of unsigned contract names and an options hash
+    # Unless the array of unsigned contract names is blank or the request url is
+    # already the contract_redirect_path, it saves the current request path and
+    # redirects the user to the `contract_redirect_path`, with
+    # `contract_param_name` containing the unsigned contract names
+    def fine_print_redirect(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      unsigned_contract_names = args.flatten
+      return if unsigned_contract_names.nil? ||\
+                unsigned_contract_names.all? { |n| n.blank? }
+
+      path = options[:contract_redirect_path] || FinePrint.contract_redirect_path
+      param_name = options[:contract_param_name] || FinePrint.contract_param_name
+
+      # http://stackoverflow.com/a/6561953
+      redirect_path = path + (path.include?('?') ? '&' : '?') +\
+                      {param_name.to_sym => unsigned_contract_names}.to_query
+
+      # Prevent redirect loop
+      return if view_context.current_page?(redirect_path)
+
+      # http://stackoverflow.com/a/2165727/1664216
+      session[:fine_print_return_to] = "#{request.protocol}#{request.host_with_port}#{request.fullpath}"
+      redirect_to redirect_path
+    end
+
+    # Accepts no arguments
+    # Redirects the user to the path saved by either
+    # `fine_print_get_signatures` or `fine_print_redirect`
+    def fine_print_return
+      redirect_to session.delete(:fine_print_return_to) || root_path
+    end
+    
+    protected
+
+    def fine_print_skipped_contract_names
+      @fine_print_skipped_contract_names ||= []
+    end
+
+    module ClassMethods
+      # Accepts an array of contract names and an options hash
+      # Adds a before_filter to the current controller that will check if the
+      # current user has signed the given contracts and redirect them to
+      # `contract_redirect_path` if appropriate
+      # Options relevant to FinePrint are passed to fine_print_redirect, while
+      # other options are passed to the before_filter
+      def fine_print_get_signatures(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+
+        filter_options = options.except(*FinePrint::CONTRACT_OPTIONS)
+        fine_print_options = options.slice(*FinePrint::CONTRACT_OPTIONS)
+
+        # Convert names to an array of Strings
+        contract_names = args.flatten.collect{|n| n.to_s}
+
+        class_eval do
+          before_filter(filter_options) do |controller|
+            controller.fine_print_redirect(
+              controller.fine_print_get_unsigned_contract_names(contract_names - controller.fine_print_skipped_contract_names),
+              fine_print_options)
+          end
+        end
+      end
+
+      # Accepts an array of contract names and an options hash
+      # Excludes the given contracts from the `fine_print_get_signatures` check for
+      # this controller and subclasses
+      # Options are passed to prepend_before_filter
+      def fine_print_skip_signatures(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+
+        # Convert all names to string
+        names = args.flatten.collect{|n| n.to_s}
+
+        class_eval do
+          prepend_before_filter(options) do |controller|
+            controller.fine_print_skipped_contract_names.push(*names)
+          end
+        end
+      end
+    end
+  end
+end
+
+ActionController::Base.send :include, FinePrint::ControllerIncludes

data/lib/fine_print/version.rb

@@ -1,3 +1,3 @@
 module FinePrint
-  VERSION = '1.3.0'
+  VERSION = '1.4.1'
 end

data/lib/fine_print.rb

@@ -1,6 +1,6 @@
 require 'fine_print/engine'
 require 'fine_print/security_transgression'
-require 'fine_print/controller_additions'
+require 'fine_print/controller_includes'
 
 module FinePrint
   # Attributes
@@ -9,17 +9,17 @@ module FinePrint
   ENGINE_OPTIONS = [
     :current_user_proc,
     :user_admin_proc,
-    :can_sign_contracts_proc,
-    :pose_contracts_path,
-    :redirect_path
+    :user_can_sign_proc
   ]
 
-  # Can be set in initializer or passed as an option to fine_print_get_signatures
-  SIGNATURE_OPTIONS = [
-    :pose_contracts_path
+  # Can be set in initializer or passed as an argument to either
+  # `fine_print_get_signatures` or `fine_print_redirect`
+  CONTRACT_OPTIONS = [
+    :contract_param_name,
+    :contract_redirect_path
   ]
   
-  (ENGINE_OPTIONS + SIGNATURE_OPTIONS).each do |option|
+  (ENGINE_OPTIONS + CONTRACT_OPTIONS).each do |option|
     mattr_accessor option
   end
   
@@ -27,10 +27,9 @@ module FinePrint
     yield self
   end
 
-  # Gets a contract given either the contract's object, ID or 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
-  #   - contract -- can be a Contract object, its ID, or its name as a String or Symbol
-  #
+  #   - contract - can be a Contract object, its ID, or its name (String/Symbol)
   def self.get_contract(reference)
     ref = Integer(reference) rescue reference
     case ref
@@ -44,9 +43,8 @@ module FinePrint
   end
 
   # Records that the given user has signed the given contract
-  #   - user -- the user in question
-  #   - contract -- can be a Contract object, its ID, or its name as a String or Symbol
-  #
+  #   - user - the user in question
+  #   - contract - can be a Contract object, its ID, or its name (String/Symbol)
   def self.sign_contract(user, contract)
     raise_unless_can_sign(user)
     contract = get_contract(contract)
@@ -59,9 +57,8 @@ module FinePrint
   end
 
   # Returns true iff the given user has signed the given contract
-  #   - user -- the user in question
-  #   - contract -- can be a Contract object, its ID, or its name as a String or Symbol
-  #
+  #   - user - the user in question
+  #   - contract - can be a Contract object, its ID, or its name (String/Symbol)
   def self.signed_contract?(user, contract)
     raise_unless_can_sign(user)
     contract = get_contract(contract)
@@ -71,8 +68,8 @@ module FinePrint
   end
 
   # Returns true iff the given user has signed any version of the given contract
-  #   - user -- the user in question
-  #   - contract -- can be a Contract object, its ID, or its name as a String or Symbol
+  #   - user - the user in question
+  #   - contract - can be a Contract object, its ID, or its name (String/Symbol)
   def self.signed_any_contract_version?(user, contract)
     raise_unless_can_sign(user)
     contract = get_contract(contract)
@@ -84,9 +81,8 @@ module FinePrint
 
   # Returns an array of names for the contracts whose latest published
   # version the given user has not signed.
-  #   - user -- the user in question
-  #   - names -- contract names to check
-  #
+  #   - user - the user in question
+  #   - names - contract names to check
   def self.get_unsigned_contract_names(user, *names)
     raise_unless_can_sign(user)
     names = names.flatten.collect{|name| name.to_s}
@@ -97,13 +93,13 @@ module FinePrint
       .where({:name => names,
               :fine_print_signatures => {:user_id => user.id,
                                          :user_type => user.class.name}}).latest
-    signed_contract_names = signed_contracts.collect{|c| c.name}
+    signed_contract_names = signed_contracts.to_a.collect{|c| c.name}
 
     return names - signed_contract_names
   end
 
   def self.can_sign?(user)
-    can_sign_contracts_proc.call(user)
+    user_can_sign_proc.call(user)
   end
 
   def self.is_admin?(user)