fine_print 0.1.1 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d381ead09489e5ca6b883c0ce22c68f7c9b9a623
+  data.tar.gz: 05d8ababdd00605954298ffdb15c0f89dfe9268b
+SHA512:
+  metadata.gz: 01d698b01cc332ba64c925ee1d1a1e9fd0502a398f95a9c654b5b00199e4f0e7eda1ea96623484779defda49541b341801e5d6d0c0dd9490adb0ba869b22512c
+  data.tar.gz: 4aeb8f6fb1b4971033c9ab4c21676d22ffdf60651a4423e63e85286bc3dc606faced415717dd6f4aa8dfe448532f2000b72a59fb09d089ffbd6da16e3b3829f3

data/README.md

@@ -1,6 +1,12 @@
 # FinePrint
 
-FinePrint is a Rails gem that makes managing web site agreements (terms, privacy policy, etc) simple and easy.
+FinePrint is a Rails gem (engine) that makes managing web site agreements (terms, 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.
 
 ## Installation
 
@@ -40,78 +46,97 @@ 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 fine_print engine to manage agreements.
+And provide a link on your site for administrators to access the FinePrint engine to manage contracts.
 
 ```erb
 <%= link_to 'FinePrint', fine_print_path %>
 ```
 
-Finally, make sure your `application.js` requires jquery and jquery_ujs (it usually does by default):
-
-```js
-//= require jquery
-//= require jquery_ujs
-```
-
-**Note:** FinePrint will **automatically** add the fine_print/dialog.js file to your asset precompilation list.
-
 ## 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 agreements unless you set up this proc to return true for your admins.
-
-If you want to use FinePrint's modal dialogs, then make sure `application.js` also requires jquery-ui:
-
-```js
-//= require jquery-ui
-```
+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.
 
 ## Usage
 
-FinePrint adds a new method to all controllers that behaves like a before_filter.
-It can be accessed by calling `fine_print_agreement` from any controller.
-This method takes an agreement name and an options hash.
-Accepted options are (see initializer for more explanation):
+FinePrint adds 3 controller methods to all of your controllers:
+
+`fine_print_get_signatures`, `fine_print_skip_signatures` and `fine_print_return`
 
-- `only` and `except` just like a before_filter
+Additionally, the FinePrint module contains several methods that help you find contracts and mark them as signed.
 
-- `agreement_notice` notice to be shown to the user above the agreement
+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).
 
-- `accept_path` path to redirect users to when an agreement is accepted and no referer information is available
-- `cancel_path` path to redirect users to when an agreement is not accepted and no referer information is available
-- `use_referers` false if you want users to always be redirected to the above paths
+This method takes a list of contract names (given either as strings or as 
+symbols), along with an options hash.
 
-- `use_modal_dialogs` true if you want to use FinePrint's modal dialogs
+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.
 
 Example:
 
 ```rb
-fine_print_agreement 'terms of use', :except => :index, :use_modal_dialogs => true
+class MyController < ApplicationController
+  fine_print_get_signatures :terms_of_use, :privacy_policy,
+                            :except => :index
 ```
 
-This gem also adds the `fine_print_dialog` helper method, which needs to be called (usually from your layout) if you want to use FinePrint's modal dialogs.
-This method only takes an options hash. Accepted options are:
+You should only try to get signatures when you have a user who is logged in
+(FinePrint will raise an exception if you try to get a non-logged in user to sign
+an agreement, as that does not make any sense).  This normally means that before
+the call to `fine_print_get_signatures` you should call whatever `before_filter`
+gets a user to login.
 
-- `width`
-- `height`
+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`.
 
-Example:
+One way you may want to use these methods is to require signatures in every controller
+by default, and then to skip them in certain situations, e.g.:
 
-```erb
-<%= fine_print_dialog, :width => 800, :height => 600 %>
+```rb
+class ApplicationController < ActionController::Base
+  fine_print_get_signatures :terms_of_use
+```
+
+```rb
+class NoSigsRequiredController < ApplicationController
+  fine_print_skip_signatures :terms_of_use
 ```
 
-## Managing Agreements
+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.
 
-Here are some important notes about managing your agreements with FinePrint:
+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).
 
-- Agreements are referred to on your controller by the name you specified
-- Creating another agreement with the same name will make it a new version of a previous agreement
-- Agreements need to be marked as `ready` to be able to be accepted by users
-- The latest version of each agreement that is marked as `ready` will always be used
-- Agreements cannot be modified after at least one user has accepted them, but you can always create new versions
-- When a new version is present, users will be asked to accept it the next time they visit a controller action that calls `fine_print_agreement`
+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
+name 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.
+- 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.
 
 ## Customization
 
@@ -123,7 +148,7 @@ Run the following command to copy a part of FinePrint into your main application
 $ rake fine_print:copy:folder
 ```
 
-Where folder is one of `stylesheets`, `javascripts`, `layouts`, `views` or `controllers`.
+Where folder is one of `stylesheets`, `layouts`, `views` or `controllers`.
 
 Example:
 
@@ -137,6 +162,10 @@ Alternatively, you can run the following command to copy all of the above into y
 $ 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.
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1,23 +1,23 @@
 #!/usr/bin/env rake
+# http://viget.com/extend/rails-engine-testing-with-rspec-capybara-and-factorygirl
 begin
   require 'bundler/setup'
 rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+APP_RAKEFILE = File.expand_path('../spec/dummy/Rakefile', __FILE__)
 load 'rails/tasks/engine.rake'
 
 Bundler::GemHelper.install_tasks
 
-require 'rake/testtask'
+Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each {|f| load f }
 
-Rake::TestTask.new(:test => 'app:db:test:prepare') do |t|
-  t.libs << 'lib'
-  t.libs << 'spec'
-  t.pattern = 'spec/**/*_spec.rb'
-  t.verbose = false
-end
+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')
 
-task :default => :test
+task :default => :spec
 

data/app/assets/javascripts/application.js~

@@ -0,0 +1,16 @@
+// This is a manifest file that'll be compiled into including all the files listed below.
+// Add new JavaScript/Coffee code in separate files in this directory and they'll automatically
+// be included in the compiled file accessible from http://example.com/assets/application.js
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+//= require jquery
+//= require jquery_ujs
+//= require jquery-ui
+//= require columnizer
+//= require jaccordion
+//= require autocomplete-rails
+//= require jcrop
+//= require colorbox
+//= require_tree .
+

data/app/assets/javascripts/fine_print/application.js

@@ -1,4 +1,10 @@
+// This is a manifest file that'll be compiled into including all the files listed below.
+// Add new JavaScript/Coffee code in separate files in this directory and they'll automatically
+// be included in the compiled file accessible from http://example.com/assets/application.js
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
 //= require jquery
 //= require jquery_ujs
-//= require fine_print/agreements
-//= require fine_print/user_agreements
+//= require_tree .
+

data/app/controllers/fine_print/application_controller.rb

@@ -1,13 +1,15 @@
 module FinePrint
   class ApplicationController < ActionController::Base
-    before_filter :get_user
-    
-    rescue_from SecurityTransgression, :with => lambda { redirect_to FinePrint.redirect_path }
-    
+    before_filter :verify_admin
+
+    rescue_from FinePrint::SecurityTransgression, 
+                :with => lambda { redirect_to FinePrint.redirect_path }
+
     protected
-    
-    def get_user
-      @user = self.send FinePrint.current_user_method
+
+    def verify_admin
+      user = send FinePrint.current_user_method
+      FinePrint.raise_unless_admin(user)
     end
   end
 end

data/app/controllers/fine_print/application_controller.rb~

@@ -1,13 +1,15 @@
 module FinePrint
   class ApplicationController < ActionController::Base
-    before_filter :get_user
-    helper MyEngine::Engine.helpers
-    rescue_from SecurityTransgression, :with => lambda { redirect_to FinePrint.redirect_path }
-    
+    before_filter :verify_admin!
+
+    rescue_from FinePrint::SecurityTransgression, 
+                :with => lambda { redirect_to FinePrint.redirect_path }
+
     protected
-    
-    def get_user
-      @user = self.send FinePrint.current_user_method
+
+    def verify_admin!
+      user = send FinePrint.current_user_method
+      FinePrint.raise_unless_admin!(user)
     end
   end
 end

data/app/controllers/fine_print/contracts_controller.rb

@@ -0,0 +1,79 @@
+module FinePrint
+  class ContractsController < FinePrint::ApplicationController
+    include FinePrint::ApplicationHelper
+    before_filter :get_contract, :except => [:index, :new, :create]
+
+    def index
+      @contracts = Contract.all
+    end
+  
+    def show
+    end
+
+    def new
+      @contract = Contract.new
+    end
+  
+    def edit
+    end
+  
+    def create
+      @contract = Contract.new
+      @contract.name = params[:contract][:name]
+      @contract.title = params[:contract][:title]
+      @contract.content = params[:contract][:content]
+  
+      if @contract.save
+        redirect_to @contract, :notice => 'Contract was successfully created.'
+      else
+        render :action => 'new'
+      end
+    end
+  
+    def update
+      @contract.name = params[:contract][:name]
+      @contract.title = params[:contract][:title]
+      @contract.content = params[:contract][:content]
+
+      if @contract.save
+        redirect_to @contract, :notice => 'Contract was successfully updated.'
+      else
+        render :action => 'edit'
+      end
+    end
+
+    def destroy
+      if @contract.destroy
+        redirect_to contracts_path, :notice => 'Contract was successfully deleted.'
+      else
+        redirect_to contracts_path, :alert => merge_errors_for(@contract)
+      end
+    end
+
+    def publish
+      if @contract.publish
+        redirect_to contracts_path, :notice => 'Contract was successfully published.'
+      else
+        redirect_to contracts_path, :alert => merge_errors_for(@contract)
+      end
+    end
+
+    def unpublish
+      if @contract.unpublish
+        redirect_to contracts_path, :notice => 'Contract was successfully unpublished.'
+      else
+        redirect_to contracts_path, :alert => merge_errors_for(@contract)
+      end
+    end
+
+    def new_version
+      @contract = @contract.draft_copy
+    end
+
+    protected
+
+    def get_contract
+      @contract = Contract.find(params[:id])
+    end
+  end
+end

data/app/controllers/fine_print/contracts_controller.rb~

@@ -0,0 +1,79 @@
+module FinePrint
+  class ContractsController < FinePrint::ApplicationController
+    include FinePrint::ApplicationHelper
+    before_filter :get_contract, :except => [:index, :new, :create]
+
+    def index
+      @contracts = Contract.all
+    end
+  
+    def show
+    end
+
+    def new
+      @contract = Contract.new
+    end
+  
+    def edit
+    end
+  
+    def create
+      @contract = Contract.new
+      @contract.name = params[:contract][:name]
+      @contract.title = params[:contract][:title]
+      @contract.content = params[:contract][:content]
+  
+      if @contract.save
+        redirect_to @contract, :notice => 'Contract was successfully created.'
+      else
+        render :action => 'new'
+      end
+    end
+  
+    def update
+      @contract.name = params[:contract][:name]
+      @contract.title = params[:contract][:title]
+      @contract.content = params[:contract][:content]
+
+      if @contract.save
+        redirect_to @contract, :notice => 'Contract was successfully updated.'
+      else
+        render :action => 'edit'
+      end
+    end
+
+    def destroy
+      if @contract.destroy
+        redirect_to contracts_path, :notice => 'Contract was successfully deleted.'
+      else
+        redirect_to contracts_path, :alert => merge_errors_for(@contract)
+      end
+    end
+
+    def publish
+      if @contract.publish
+        redirect_to contracts_path, :notice => 'Contract was successfully published.'
+      else
+        redirect_to contracts_path, :alert => merge_errors_for(@contract)
+      end
+    end
+
+    def unpublish
+      if @contract.unpublish
+        redirect_to contracts_path, :notice => 'Contract was successfully unpublished.'
+      else
+        redirect_to contracts_path, :alert => merge_errors_for(@contract)
+      end
+    end
+
+    def new_version
+      @contract = @contract.draft_copy
+    end
+
+    protected
+
+    def get_contract
+      @contract = Contract.find(params[:id])
+    end
+  end
+end

data/app/controllers/fine_print/home_controller.rb

@@ -1,14 +1,4 @@
-require_dependency "fine_print/application_controller"
-
 module FinePrint
-  class HomeController < ApplicationController
-    # GET /fine_print
-    def index
-      raise SecurityTransgression unless Agreement.can_be_listed_by?(@user) && UserAgreement.can_be_listed_by?(@user)
-  
-      respond_to do |format|
-        format.html # index.html.erb
-      end
-    end
+  class HomeController < FinePrint::ApplicationController
   end
 end

data/app/controllers/fine_print/home_controller.rb~

@@ -1,15 +1,6 @@
-require_dependency "fine_print/application_controller"
+require_dependency 'fine_print/application_controller'
 
 module FinePrint
-  class HomeController < ApplicationController
-    # GET /fine_print
-    def index
-      raise SecurityTransgression unless Agreement.can_be_listed_by?(@user) && UserAgreement.can_be_listed_by?(@user)
-  
-      respond_to do |format|
-        format.html # index.html.erb
-        format.json { render json: @agreements }
-      end
-    end
+  class HomeController < FinePrint::ApplicationController
   end
 end

data/app/controllers/fine_print/signatures_controller.rb

@@ -0,0 +1,14 @@
+module FinePrint
+  class SignaturesController < FinePrint::ApplicationController
+    def index
+      @signatures = Signature.all
+    end
+  
+    def destroy
+      @signature = Signature.find(params[:id])
+
+      @signature.destroy
+      redirect_to signatures_path
+    end
+  end
+end

data/app/controllers/fine_print/signatures_controller.rb~

@@ -0,0 +1,14 @@
+module FinePrint
+  class SignaturesController < FinePrint::ApplicationController
+    def index
+      @signatures = Signature.all
+    end
+  
+    def destroy
+      @signature = Signature.find(params[:id])
+
+      @signature.destroy
+      redirect_to signatures_url
+    end
+  end
+end

data/app/helpers/fine_print/application_helper.rb

@@ -0,0 +1,7 @@
+module FinePrint
+  module ApplicationHelper
+    def merge_errors_for(obj)
+      "#{obj.errors.collect{|f,e| "#{e}"}.join('. ')}."
+    end
+  end
+end

data/app/helpers/fine_print/application_helper.rb~

@@ -0,0 +1,7 @@
+module FinePrint
+  module ApplicationHelper
+    def merge_errors_for(contract)
+      contract.errors.collect{|f,e| "#{contract.name} #{e}"}.join(', ')
+    end
+  end
+end

data/app/helpers/fine_print/contracts_helper.rb~

@@ -0,0 +1,7 @@
+module FinePrint
+  module ContractsHelper
+    def merge_errors_for(obj)
+      "#{obj.errors.collect{|f,e| "#{e}"}.join('. ')}."
+    end
+  end
+end

data/app/models/fine_print/contract.rb

@@ -0,0 +1,96 @@
+module FinePrint
+  class Contract < ActiveRecord::Base
+    has_many :signatures, :inverse_of => :contract
+
+    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_presence_of :name, :title, :content
+    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})
+
+    def is_published?
+      !version.nil?
+    end
+
+    def is_latest?
+      is_published? && version == same_name.maximum(:version)
+    end
+
+    def sign(user)
+      FinePrint.sign_contract(self, user)
+    end
+
+    def signed_by?(user)
+      FinePrint.signed_contract?(self, user)
+    end
+
+    def publish
+      no_signatures
+      errors.add(:base, 'Contract is already published') if is_published?
+      return false unless errors.empty?
+
+      self.version = (same_name.published.first.try(:version) || 0) + 1
+      save
+    end
+
+    def unpublish
+      no_signatures
+      errors.add(:base, 'Contract is not the latest published version') unless is_latest?
+      return false unless errors.empty?
+
+      self.version = nil
+      save
+    end
+
+    def draft_copy
+      Contract.where(:name => name, :version => nil).first || dup.tap{|contract| contract.version = nil}
+    end
+
+    ##################
+    # Access Control #
+    ##################
+
+    def can_be_updated?
+      signatures.empty?
+    end
+
+    def can_be_published?
+      signatures.empty? && !is_published?
+    end
+
+    def can_be_unpublished?
+      signatures.empty? && is_latest?
+    end
+
+    alias_method :can_be_destroyed?, :can_be_updated?
+
+    ##############
+    # Validation #
+    ##############
+
+    def no_signatures
+      return if signatures.empty?
+      errors.add(:base, 'Contract cannot be modified because users have signed it')
+      false
+    end
+
+    protected
+
+    def downcase_name
+      self.name = name.downcase
+    end
+  end
+end