fine_print 2.3.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8fd843dfe050f713c606f4abd853060268ab0219
-  data.tar.gz: be4fb77d6b38481e1818e0b027e2898e1caf6ace
+  metadata.gz: 2f81ee20572ca69333bf085618f19c261ef9858a
+  data.tar.gz: 1e17485c34cce0a8881ddacab69a290a3e2cb880
 SHA512:
-  metadata.gz: 2c552a2896a6adb058e3f2cd3be90ff5e53419584f8340191890493c7f612f06e72e4e60d7a37779bebe4108344797533728a92ee925161204f56f1106eede03
-  data.tar.gz: 99904649e084a6280d61092564709519bf4cbd7bb6552f3a9a25f043f61cfbcf8d24f80ffadb9ff6ba349c9029960cca8e73c32c316a53b758c5ede3e1adcfaa
+  metadata.gz: 93a19883752880c9fa1fd4e57fd94b0ca37d6a4e0ba8bbd82b9178111bf59c17307c1b0d2b1b359c6133bf4dca277f753620eb63e0fbd4c5db45d8c5ff93ebdf
+  data.tar.gz: 2d85aae86ba3db77ff0e7072bef2147c754f6617f1bbdd3af2c610127c2a42b25f62e7dec243bb48c6bdf5d754d73f8c794ef9b90454bb5b5a35e89f25b19caa

data/README.md

@@ -4,13 +4,25 @@
 [![Build Status](https://travis-ci.org/lml/fine_print.svg?branch=master)](https://travis-ci.org/lml/fine_print)
 [![Code Climate](https://codeclimate.com/github/lml/fine_print/badges/gpa.svg)](https://codeclimate.com/github/lml/fine_print)
 
-FinePrint is a Rails engine in gem form that makes managing web site agreements (terms of use, privacy policy, etc) simple and easy.
-
-As the meaning of 'agreement' can be somewhat ambiguous (meaning either the thing someone agrees to or the record of the agreement between that thing and the user), we call a set of terms a 'contract' and a user's agreement to that contract a 'signature'.
-
-A version history of all contracts is maintained.  Once a particular version of a contract is published, it becomes available for users to sign.  Once a version has been signed, it cannot be changed (to effect a change, a new version must be created and published).  When a new version of a contract is created and published, users visiting pages requiring signature of that contract will be redirected to a page you specify where they can sign the new contract.
-
-FinePrint provides views for admins to manage contracts and signatures, but does not provide views for the application to display contracts to end users, as that functionality is specific to each particular application.  FinePrint does provide convenience methods for finding unsigned contracts and for recording when a user signs a contract.
+FinePrint is a Rails engine in gem form that makes managing web site agreements
+(terms of use, privacy policy, etc) simple and easy.
+
+As the meaning of 'agreement' can be somewhat ambiguous (meaning either the
+thing someone agrees to or the record of the agreement between that thing and
+the user), we call a set of terms a 'contract' and a user's agreement to that
+contract a 'signature'.
+
+A version history of all contracts is maintained. Once a particular version of
+a contract is published, it becomes available for users to sign. Once it has
+been signed, it cannot be changed. To effect a change, a new version must be
+created and published. When a new version of a contract is created and
+published, users visiting pages requiring signature of that contract will be
+redirected to a page where they can sign the new contract.
+
+FinePrint provides views for admins to manage contracts and signatures and for
+users to sign those contracts, although these views can be overriden by
+application-specific views. FinePrint also provides convenience methods for
+finding unsigned contracts and for recording when a user signs a contract.
 
 ## Installation
 
@@ -58,120 +70,145 @@ And provide a link on your site for administrators to access the FinePrint engin
 
 ## Configuration
 
-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 setup this proc to return true for your admins.
+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 `authenticate_manager_proc`,
+as you will be unable to manage your contracts unless you setup
+this proc to return `true` for your admins.
 
 ## Usage
 
-You can choose to check if users signed contracts either as a before_filter or inside your controller actions.
+You can choose to check if users signed contracts either
+as a before_filter or inside your controller actions.
 
 ### Option 1 - As a before_filter
 
-If you choose to have FinePrint work like a before_filter, you can user the following 3 class methods, which are automatically added to all of your controllers:
+If you choose to have FinePrint work like a before_filter, you can user the following class methods, which are automatically added to your controllers:
 
 ```rb
-fine_print_get_signatures(contract_names..., options_hash)
-fine_print_require_signatures(contract_names..., options_hash)
-fine_print_skip_signatures(contract_names..., options_hash)
+fine_print_require(contract_names..., options_hash)
+fine_print_skip(contract_names..., options_hash)
 ```
 
-They work as follows:
-- `fine_print_get_signatures` will redirect the user
-To require that your users sign the most recent version of a contract, call
-`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).
+- `fine_print_require` will redirect users to a page that asks them
+  to sign each contract provided, in order
+- `fine_print_skip` is used to skip asking the user to sign
+  the given contracts for certain controller actions
 
-This method takes a list of contract names to check (given either as strings or as 
-symbols), along with an options hash.
+These methods take a list of contract names to check, 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 options `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 option
+`redirect_to_contracts_proc`, which is a proc that controls
+where users are redirected to in order to sign contracts.
 
 Example:
 
 ```rb
 class MyController < ApplicationController
-  fine_print_get_signatures :terms_of_use, :privacy_policy,
-                            :except => :index
+  fine_print_require :terms_of_use, :privacy_policy, except: :index
+end
 ```
 
-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`.
+Before checking the contracts to be signed, FinePrint will check that the user
+is logged in by calling the authenticate_user_proc. This method should render
+or redirect the user if they are not signed in.
 
 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
 class ApplicationController < ActionController::Base
-  fine_print_get_signatures :terms_of_use
+  fine_print_require :terms_of_use
+end
 ```
 
 ```rb
 class NoSigsRequiredController < ApplicationController
-  fine_print_skip_signatures :terms_of_use
+  fine_print_skip :terms_of_use
+end
 ```
 
 ### 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:
+If, instead, you have to check a contract signature inside a controller action,
+you can use the following instance methods, also available in all controllers:
 
 ```rb
-fine_print_redirect(fine_print_get_unsigned_contract_names(contract_names))
+fine_print_require(contract_names..., options_hash)
+fine_print_return
 ```
 
-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.
+- `fine_print_require` works just like the before_filter version and will
+  redirect the user if they haven't signed one or more of the given contracts
+- `fine_print_return` can be used to return from a redirect
+  made by `fine_print_require`
 
 ### 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:
+When a set of contracts is found by FinePrint to be required but unsigned,
+and the user is allowed to sign contracts, FinePrint will call the
+redirect_to_contracts_proc, which should redirect the user to some action
+that allows the user to sign said contracts, passing along the id's of the
+contract objects that need to be signed. By default, it redirects to one
+of FinePrint's views that presents one contract at a time to the user.
+
+If you choose to create this view yourself, 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...)
+FinePrint.signed_any_version_of_contract?(user, contract_object_or_id_or_name)
 ```
 
 If you require more explanation about these methods and their arguments, check the `lib/fine_print.rb` file.
 
 ### Redirecting users back
 
-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.
+Regardless if you use the class before_filter or instance methods,
+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 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.
+If there are multiple unsigned contracts, you are not required to ask the user
+to sign 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 signing
+path with one less contract id passed in.
 
 ## Managing Contracts
 
 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 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).
+- Contracts have a name and a title; the former is used by your code,
+  the latter is intended for display to end users and 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 either `fine_print_get_signatures` or the controller fine_print instance methods with that contract's name.
+- 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 either `fine_print_require` with that contract's name.
 
 ## Customization
 
-You can customize FinePrint's stylesheets, javascripts, views and even controllers to suit your needs.
+You can customize FinePrint's stylesheets, javascripts, views
+and even controllers to suit your needs.
 
-Run the following command to copy a part of FinePrint into your main application:
+Run the following command to copy a part of FinePrint
+into your main application:
 
 ```sh
 $ rake fine_print:copy:folder
@@ -185,7 +222,8 @@ Example:
 $ rake fine_print:copy:views
 ```
 
-Alternatively, you can run the following command to copy all of the above into your main application:
+Alternatively, you can run the following command
+to copy all of the above into your main application:
 
 ```sh
 $ rake fine_print:copy
@@ -193,7 +231,9 @@ $ rake fine_print:copy
 
 ## Testing
 
-From the gem's main folder, run `bundle install`, `bundle exec rake db:migrate` and then `bundle exec rake` to run all the specs.
+From the gem's main folder, run `bundle install`,
+`bundle exec rake db:migrate` and then
+`bundle exec rake` to run all the specs.
 
 ## Contributing
 

data/Rakefile

@@ -17,6 +17,6 @@ require 'rspec/core'
 require 'rspec/core/rake_task'
 
 desc 'Run all specs in spec directory (excluding plugin specs)'
-RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+RSpec::Core::RakeTask.new(spec: 'app:db:test:prepare')
 
-task :default => :spec
+task default: :spec

data/app/controllers/fine_print/application_controller.rb

@@ -1,23 +1,23 @@
 require 'responders'
 
 module FinePrint
-  class ApplicationController < ActionController::Base
+  class ApplicationController < ::ActionController::Base
     respond_to :html
 
     before_filter :get_user, :can_manage
 
-    layout FinePrint.layout
+    layout FinePrint.config.layout
 
-    helper FinePrint.helpers
+    helper FinePrint.config.helpers
 
     protected
 
     def get_user
-      @user = instance_exec &FinePrint.current_user_proc
+      @user = instance_exec &FinePrint.config.current_user_proc
     end
 
     def can_manage
-      instance_exec @user, &FinePrint.can_manage_proc
+      instance_exec @user, &FinePrint.config.authenticate_manager_proc
     end
   end
 end

data/app/controllers/fine_print/contracts_controller.rb

@@ -2,7 +2,7 @@ module FinePrint
   class ContractsController < FinePrint::ApplicationController
     include FinePrint::ApplicationHelper
 
-    before_filter :get_contract, :except => [:index, :new, :create]
+    before_filter :get_contract, except: [:index, :new, :create]
 
     def index
       @contracts = Contract.includes(:signatures).all.to_a.group_by(&:name)
@@ -19,9 +19,9 @@ module FinePrint
       @contract.content = params[:contract][:content]
   
       if @contract.save
-        redirect_to @contract, :notice => t('fine_print.contract.notices.created')
+        redirect_to @contract, notice: t('fine_print.contract.notices.created')
       else
-        render :action => 'new', :alert => merge_errors_for(@contract)
+        render action: 'new', alert: merge_errors_for(@contract)
       end
     end
 
@@ -30,7 +30,7 @@ module FinePrint
 
     def edit
       @contract.no_signatures
-      redirect_to contracts_path, :alert => merge_errors_for(@contract) \
+      redirect_to contracts_path, alert: merge_errors_for(@contract) \
         unless @contract.errors.empty?
     end
 
@@ -40,33 +40,36 @@ module FinePrint
       @contract.content = params[:contract][:content]
 
       if @contract.save
-        redirect_to @contract, :notice => t('fine_print.contract.notices.updated')
+        redirect_to @contract, notice: t('fine_print.contract.notices.updated')
       else
-        render :action => 'edit', :alert => merge_errors_for(@contract)
+        render action: 'edit', alert: merge_errors_for(@contract)
       end
     end
 
     def destroy
       if @contract.destroy
-        redirect_to contracts_path, :notice => t('fine_print.contract.notices.deleted')
+        redirect_to contracts_path,
+                    notice: t('fine_print.contract.notices.deleted')
       else
-        redirect_to contracts_path, :alert => merge_errors_for(@contract)
+        redirect_to contracts_path, alert: merge_errors_for(@contract)
       end
     end
 
     def publish
       if @contract.publish
-        redirect_to contracts_path, :notice => t('fine_print.contract.notices.published')
+        redirect_to contracts_path,
+                    notice: t('fine_print.contract.notices.published')
       else
-        redirect_to contracts_path, :alert => merge_errors_for(@contract)
+        redirect_to contracts_path, alert: merge_errors_for(@contract)
       end
     end
 
     def unpublish
       if @contract.unpublish
-        redirect_to contracts_path, :notice => t('fine_print.contract.notices.unpublished')
+        redirect_to contracts_path,
+                    notice: t('fine_print.contract.notices.unpublished')
       else
-        redirect_to contracts_path, :alert => merge_errors_for(@contract)
+        redirect_to contracts_path, alert: merge_errors_for(@contract)
       end
     end
 

data/app/controllers/fine_print/signatures_controller.rb

@@ -2,9 +2,10 @@ module FinePrint
   class SignaturesController < FinePrint::ApplicationController
     include FinePrint::ApplicationHelper
 
-    skip_before_filter :can_manage, :only => [:new, :create]
-    before_filter :can_sign, :only => [:new, :create]
-    before_filter :get_contract, :only => [:index, :new, :create]
+    skip_before_filter :can_manage, only: [:new, :create]
+    fine_print_skip only: [:new, :create]
+    before_filter :can_sign, only: [:new, :create]
+    before_filter :get_contract, only: [:index, :new, :create]
 
     def index
       @signatures = @contract.signatures
@@ -18,8 +19,10 @@ module FinePrint
       @signature = Signature.new
 
       unless params[:signature_accept]
-        @signature.errors.add(:contract, t('fine_print.signature.errors.contract.must_agree'))
-        render :action => 'new'
+        @signature.errors.add(
+          :contract, t('fine_print.signature.errors.contract.must_agree')
+        )
+        render action: 'new'
         return
       end
 
@@ -29,7 +32,7 @@ module FinePrint
       if @signature.save
         fine_print_return
       else
-        render :action => 'new', :alert => merge_errors_for(@signature)
+        render action: 'new', alert: merge_errors_for(@signature)
       end
     end
   
@@ -38,13 +41,13 @@ module FinePrint
 
       @signature.destroy
       redirect_to contract_signatures_path(@signature.contract),
-                  :notice => t('fine_print.signature.notices.deleted')
+                  notice: t('fine_print.signature.notices.deleted')
     end
 
     protected
 
     def can_sign
-      instance_exec @user, &FinePrint.can_sign_proc
+      instance_exec @user, &FinePrint.config.authenticate_user_proc
     end
 
     def get_contract

data/app/models/fine_print/contract.rb

@@ -1,20 +1,20 @@
 module FinePrint
   class Contract < ActiveRecord::Base
-    has_many :signatures, :dependent => :destroy, :inverse_of => :contract
+    has_many :signatures, dependent: :destroy, inverse_of: :contract
 
-    has_many :same_name, :class_name => 'Contract',
-             :primary_key => :name, :foreign_key => :name
+    has_many :same_name, class_name: 'Contract',
+             primary_key: :name, foreign_key: :name
 
     before_validation :downcase_name
     before_update :no_signatures
     before_destroy :no_signatures
 
-    validates :name, :presence => true, :format => /\A[\w-]+\z/
-    validates :title, :presence => true
-    validates :content, :presence => true
-    validates :version, :uniqueness => {:scope => :name,
-                                        :case_sensitive => false},
-                        :allow_nil => true
+    validates :name, presence: true, format: /\A[\w-]+\z/
+    validates :title, presence: true
+    validates :content, presence: true
+    validates :version, uniqueness: { scope: :name,
+                                      case_sensitive: false},
+                        allow_nil: true
 
     default_scope lambda { order{[name.asc, version.desc]} }
 
@@ -49,7 +49,7 @@ module FinePrint
     end
 
     def new_version
-      Contract.where(:name => name, :version => nil).first || \
+      Contract.where(name: name, version: nil).first || \
         dup.tap{|contract| contract.version = nil}
     end