acts-as-approvable 0.6.1

data/lib/acts_as_approvable/acts_as_approvable.rb

@@ -0,0 +1,291 @@
+module ActsAsApprovable
+  ##
+  # The meat of {ActsAsApprovable}. This applies methods for the configured approval events
+  # and configures the required relationships.
+  module Model
+    def self.included(base)
+      base.send :extend, ClassMethods
+    end
+
+    ##
+    # Class methods added to `ActiveRecord::Base`.
+    module ClassMethods
+      # Declare this in your model to require approval on new records or changes to fields.
+      #
+      # @param [Hash] options the options for this models approval workflow.
+      # @option options [Symbol,Array] :on    The events to require approval on (`:create` or `:update`).
+      # @option options [String] :state_field The local field to store `:create` approval state.
+      # @option options [Array]  :ignore      A list of fields to ignore. By default we ignore `:created_at`, `:updated_at` and
+      #                                       the field specified in `:state_field`.
+      # @option options [Array]  :only        A list of fields to explicitly require approval on. This list supercedes `:ignore`.
+      def acts_as_approvable(options = {})
+        include InstanceMethods
+
+        cattr_accessor :approvable_on
+        self.approvable_on = Array.wrap(options.delete(:on) { [:create, :update] })
+
+        cattr_accessor :approvable_field
+        self.approvable_field = options.delete(:state_field)
+
+        cattr_accessor :approvable_ignore
+        ignores = Array.wrap(options.delete(:ignore) { [] })
+        ignores.push('created_at', 'updated_at', self.approvable_field)
+        self.approvable_ignore = ignores.compact.uniq.map(&:to_s)
+
+        cattr_accessor :approvable_only
+        self.approvable_only = Array.wrap(options.delete(:only) { [] }).uniq.map(&:to_s)
+
+        cattr_accessor :approvals_active
+        self.approvals_active = true
+
+        has_many :approvals, :as => :item, :dependent => :destroy
+
+        if self.approvable_on.include?(:update)
+          include UpdateInstanceMethods
+          before_update :approvable_update, :if => :approvable_update?
+        end
+
+        if self.approvable_on.include?(:create)
+          include CreateInstanceMethods
+          before_create :approvable_create, :if => :approvable_create?
+        end
+
+        after_save :approvable_save, :if => :approvals_enabled?
+      end
+
+      ##
+      # Enable the approval queue for this model.
+      def approvals_on
+        self.approvals_active = true
+      end
+
+      ##
+      # Disable the approval queue for this model.
+      def approvals_off
+        self.approvals_active = false
+      end
+
+      ##
+      # Execute a code block while the approval queue is temporarily disabled. The
+      # queue state will be returned to it's previous value, either on or off.
+      def without_approval(&block)
+        enable = self.approvals_active
+        approvals_off
+        yield(self)
+      ensure
+        approvals_on if enable
+      end
+    end
+
+    ##
+    # Instance methods that apply to the `:create` event specifically.
+    module CreateInstanceMethods
+      ##
+      # Retrieve approval record for the creation event.
+      #
+      # @return [Approval]
+      def approval
+        approvals.find_by_event('create')
+      end
+
+      ##
+      # Get the approval state of the current record from either the local state
+      # field or, if no state field exists, the creation approval object.
+      #
+      # @return [String] one of `'pending'`, `'approved`' or `'rejected'`.
+      def approval_state
+        if self.class.approvable_field
+          send(self.class.approvable_field)
+        else
+          approval.state
+        end
+      end
+
+      ##
+      # Set the records local approval state.
+      #
+      # @param [String] state one of `'pending'`, `'approved`' or `'rejected'`.
+      def set_approval_state(state)
+        return unless self.class.approvable_field
+        send("#{self.class.approvable_field}=".to_sym, state)
+      end
+
+      ##
+      # Returns true if the record is pending approval.
+      def pending?
+        approval_state == 'pending' or approval.present? and !approved? and !rejected?
+      end
+
+      ##
+      # Returns true if the record has been approved.
+      def approved?
+        approval_state == 'approved' or approval.nil? or approval.approved?
+      end
+
+      ##
+      # Returns true if the record has been rejected.
+      def rejected?
+        approval_state == 'rejected' or approval.present? and approval.rejected?
+      end
+
+      ##
+      # Approves the record through {Approval#approve!}
+      #
+      # @return [Boolean]
+      def approve!
+        return unless approvable_on?(:create) && approval.present?
+        approval.approve!
+      end
+
+      ##
+      # Rejects the record through {Approval#reject!}
+      #
+      # @return [Boolean]
+      def reject!
+        return unless approvable_on?(:create) && approval.present?
+        approval.reject!
+      end
+
+      private
+      def approvable_create?
+        approvals_enabled? and approvable_on?(:create)
+      end
+
+      def approvable_create
+        @approval = approvals.build(:event => 'create', :state => 'pending')
+        set_approval_state('pending')
+      end
+    end
+
+    ##
+    # Instance methods that apply to the :update event specifically.
+    module UpdateInstanceMethods
+      ##
+      # Retrieve all approval records for `:update` events.
+      def update_approvals
+        approvals.find_all_by_event('update')
+      end
+
+      ##
+      # Returns true if the record has any `#update_approvals` that are pending
+      # approval.
+      def pending_changes?
+        !update_approvals.empty?
+      end
+
+      ##
+      # Returns true if any notable (eg. not ignored) fields have been changed.
+      def changed_notably?
+        notably_changed.any?
+      end
+
+      ##
+      # Returns an array of any notable (eg. not ignored) fields that have not
+      # been changed.
+      #
+      # @return [Array] a list of changed fields.
+      def notably_changed
+        unless self.class.approvable_only.empty?
+          self.class.approvable_only.select { |field| changed.include?(field) }
+        else
+          changed - self.class.approvable_ignore
+        end
+      end
+
+      private
+      def approvable_update?
+        approvals_enabled? and approvable_on?(:update) and changed_notably?
+      end
+
+      def approvable_update
+        changed = {}
+        notably_changed.each do |attr|
+          original, changed_to = changes[attr]
+
+          write_attribute(attr.to_s, original)
+          changed[attr] = changed_to
+        end
+
+        @approval = approvals.build(:event => 'update', :state => 'pending', :object => changed)
+      end
+    end
+
+    ##
+    # Instance methods that apply to both `:update` and `:create` events.
+    module InstanceMethods
+      ##
+      # Returns true if the approval queue is active at both the local and global
+      # level. Note that the global level supercedes the local level.
+      def approvals_enabled?
+        ActsAsApprovable.enabled? and self.class.approvals_active and approvals_on?
+      end
+
+      ##
+      # Returns the inverse of `#approvals_enabled?`
+      def approvals_disabled?
+        !approvals_enabled?
+      end
+
+      def approvals_off
+        @approvals_disabled = true
+      end
+
+      def approvals_on
+        @approvals_disabled = false
+      end
+
+      def approvals_on?
+        not @approvals_disabled
+      end
+
+      ##
+      # Returns true if the model is configured to use the approval queue on the
+      # given event (`:create` or `:update`).
+      def approvable_on?(event)
+        self.class.approvable_on.include?(event)
+      end
+
+      ##
+      # A filter that is run before the record can be approved. Returning false
+      # stops the approval process from completing.
+      def before_approve(approval); end
+
+      ##
+      # A filter that is run after the record has been approved.
+      def after_approve(approval); end
+
+      ##
+      # A filter that is run before the record can be rejected. Returning false
+      # stops the rejection process from completing.
+      def before_reject(approval); end
+
+      ##
+      # A filter that is run after the record has been rejected.
+      def after_reject(approval); end
+
+      ##
+      # Execute a code block while the approval queue is temporarily disabled. The
+      # queue state will be returned to it's previous value, either on or off.
+      def without_approval(&block)
+        enable = approvals_on? # If we use #approvals_enabled? the global state might be incorrectly applied.
+        approvals_off
+        yield(self)
+      ensure
+        approvals_on if enable
+      end
+
+      def save_without_approval(*args)
+        without_approval { |i| save(*args) }
+      end
+
+      def save_without_approval!(*args)
+        without_approval { |i| save!(*args) }
+      end
+
+      private
+      def approvable_save
+        @approval.save if @approval.present? && @approval.new_record?
+      end
+    end
+  end
+end

data/lib/acts_as_approvable/approval.rb

@@ -0,0 +1,179 @@
+class Approval < ActiveRecord::Base
+  ##
+  # Enumeration of available states.
+  STATES = %w(pending approved rejected)
+
+  belongs_to :item,  :polymorphic => true
+
+  validates_presence_of  :item
+  validates_inclusion_of :event, :in => %w(create update)
+  validates_numericality_of :state, :greater_than_or_equal_to => 0, :less_than => STATES.length
+
+  serialize :object
+
+  before_save :can_save?
+
+  ##
+  # Find the enumerated value for a given state.
+  #
+  # @return [Integer]
+  def self.enumerate_state(state)
+    enumerate_states(state).first
+  end
+
+  ##
+  # Find the enumerated values for a list of states.
+  #
+  # @return [Array]
+  def self.enumerate_states(*states)
+    states.map { |name| STATES.index(name) }.compact
+  end
+
+  ##
+  # Build an array of states usable by Rails' `#options_for_select`.
+  def self.options_for_state
+    options = [['All', -1]]
+    STATES.each_index { |x| options << [STATES[x].capitalize, x] }
+    options
+  end
+
+  ##
+  # Build an array of types usable by Rails' `#options_for_select`.
+  def self.options_for_type(with_prompt = false)
+    types = all(:select => 'DISTINCT(item_type)').map { |row| row.item_type }
+    types.unshift(['All Types', nil]) if with_prompt
+    types
+  end
+
+  ##
+  # Get the current state of the approval. Converts from integer via {STATES} constant.
+  def state
+    STATES[(read_attribute(:state) || 0)]
+  end
+
+  ##
+  # Get the previous state of the approval. Converts from integer via {STATES} constant.
+  def state_was
+    STATES[(changed_attributes[:state] || 0)]
+  end
+
+  ##
+  # Set the state of the approval. Converts from string to integer via {STATES} constant.
+  def state=(state)
+    state = self.class.enumerate_state(state) if state.is_a?(String)
+    write_attribute(:state, state)
+  end
+
+  ##
+  # Returns true if the approval is still pending.
+  def pending?
+    state == 'pending'
+  end
+
+  ##
+  # Returns true if the approval has been approved.
+  def approved?
+    state == 'approved'
+  end
+
+  ##
+  # Returns true if the approval has been rejected.
+  def rejected?
+    state == 'rejected'
+  end
+
+  ##
+  # Returns true if the approval has been approved or rejected.
+  def locked?
+    approved? or rejected?
+  end
+
+  ##
+  # Returns true if the approval has not been approved or rejected.
+  def unlocked?
+    not locked?
+  end
+
+  ##
+  # Returns true if the approval able to be saved. This requires an unlocked
+  # approval, or an approval just leaving the 'pending' state.
+  def can_save?
+    unlocked? or state_was == 'pending'
+  end
+
+  ##
+  # Returns true if the affected item has been updated since this approval was
+  # created.
+  def stale?
+    unlocked? and item.has_attribute?(:updated_at) and created_at < item.updated_at
+  end
+
+  ##
+  # Returns true if the affected item has not been updated since this approval
+  # was created.
+  def fresh?
+    not stale?
+  end
+
+  ##
+  # Returns true if this is an `:update` approval event.
+  def update?
+    event == 'update'
+  end
+
+  ##
+  # Returns true if this is a `:create` approval event.
+  def create?
+    event == 'create'
+  end
+
+  ##
+  # Attempt to approve the record change.
+  #
+  # @param [Boolean] force if the approval record is stale force the acceptance.
+  # @raise [ActsAsApprovable::Error::Locked] raised if the record is {#locked? locked}.
+  # @raise [ActsAsApprovable::Error::Stale] raised if the record is {#stale? stale} and `force` is false.
+  def approve!(force = false)
+    raise ActsAsApprovable::Error::Locked if locked?
+    raise ActsAsApprovable::Error::Stale if stale? and !force
+    return unless run_item_callback(:before_approve)
+
+    if update?
+      data = {}
+      object.each do |attr, value|
+        data[attr] = value if item.attribute_names.include?(attr)
+      end
+
+      item.attributes = data
+    elsif create?
+      item.set_approval_state('approved')
+    end
+
+    item.save_without_approval!
+    update_attributes!(:state => 'approved')
+    run_item_callback(:after_approve)
+  end
+
+  ##
+  # Attempt to reject the record change.
+  #
+  # @param [String] reason a reason for rejecting the change.
+  # @raise [ActsAsApprovable::Error::Locked] raised if the record is {#locked? locked}.
+  def reject!(reason = nil)
+    raise ActsAsApprovable::Error::Locked if locked?
+    return unless run_item_callback(:before_reject)
+
+    if create?
+      item.set_approval_state('rejected')
+    end
+
+    item.save_without_approval!
+    update_attributes!(:state => 'rejected', :reason => reason)
+    run_item_callback(:after_reject)
+  end
+
+  private
+  def run_item_callback(callback)
+    item.send(callback, self) != false
+  end
+end

data/lib/acts_as_approvable/error.rb

@@ -0,0 +1,31 @@
+module ActsAsApprovable
+  class Error < RuntimeError
+    ##
+    # Raised when a locked approval is accepted or rejected.
+    class Locked < ActsAsApprovable::Error
+      def initialize(*args)
+        args[0] = 'this approval is locked'
+        super(*args)
+      end
+    end
+
+    ##
+    # Raised when a stale approval is accepted.
+    class Stale < ActsAsApprovable::Error
+      def initialize(*args)
+        args[0] = 'this approval is stale and should not be approved'
+        super(*args)
+      end
+    end
+
+    ##
+    # Raised when a record is assigned as owner that is not found in
+    # {ActsAsApprovable::Ownership::ClassMethods#available_owners}.
+    class InvalidOwner < ActsAsApprovable::Error
+      def initialize(*args)
+        args[0] = 'this record cannot be assigned as an owner'
+        super(*args)
+      end
+    end
+  end
+end

data/lib/acts_as_approvable/ownership.rb

@@ -0,0 +1,117 @@
+module ActsAsApprovable
+  ##
+  # This module provides the {Approval} class with the ability to assign records
+  # as an "owner" of the approval. This is especially useful for tracking purposes
+  # when you require it, and can be beneficial when you have an approval queue with
+  # a high rate of insertions.
+  #
+  # By default the ownership functionality will reference a model named `User` and
+  # will allow any user to take ownership of an approval.
+  module Ownership
+    ##
+    # Configure approvals to allow ownership by a User model.
+    #
+    # If a block is given it will be applied to Approval at the class level,
+    # allowing you to override functionality on the fly.
+    #
+    # @param [Hash] options a hash of options for configuration
+    # @option options [Object] :model the model being used for Approval records (defaults to `Approval`).
+    # @option options [Object] :owner the model being used for owner records (defaults to `User`).
+    def self.configure(options = {}, &block)
+      approval = options.delete(:model) { Approval }
+      owner = options.delete(:owner) { User }
+
+      approval.send(:include, self)
+
+      ActsAsApprovable.owner_class = owner
+      approval.send(:belongs_to, :owner, :class_name => owner.to_s, :foreign_key => :owner_id)
+
+      approval.class_exec(&block) if block
+    end
+
+    def self.included(base)
+      base.send(:include, InstanceMethods)
+      base.extend(ClassMethods)
+    end
+
+    ##
+    # Instance methods for approval ownership.
+    module InstanceMethods
+      ##
+      # Set the owner and save the record.
+      #
+      # @return [Boolean]
+      def assign(owner)
+        raise ActsAsApprovable::Error::InvalidOwner unless self.class.available_owners.include?(owner)
+        self.owner = owner
+        save
+      end
+
+      ##
+      # Removed any assigned owner and save the record.
+      #
+      # @return [Boolean]
+      def unassign
+        self.owner = nil
+        save
+      end
+    end
+
+    ##
+    # Class methods for approval ownership.
+    module ClassMethods
+      ##
+      # Get the model that represents an owner.
+      #
+      # @see ActsAsApprovable::Ownership.configure
+      def owner_class
+        ActsAsApprovable.owner_class
+      end
+
+      ##
+      # A list of records that can be assigned to an approval. This should be
+      # overridden in {ActsAsApprovable::Ownership.configure} to return only the
+      # records you wish to manage approvals.
+      def available_owners
+        owner_class.all
+      end
+
+      ##
+      # Build an array from {#available_owners} usable by Rails' `#options_for_select`.
+      # Each element in the array is built with {#option_for_owner}.
+      #
+      # @return [Array]
+      def options_for_available_owners(with_prompt = false)
+        owners = available_owners.map { |owner| option_for_owner(owner) }
+        owners.unshift(['(none)', nil]) if with_prompt
+        owners
+      end
+
+      ##
+      # A list of owners that have assigned approvals.
+      def assigned_owners
+        all(:select => 'DISTINCT(owner_id)', :conditions => 'owner_id IS NOT NULL', :include => :owner).map(&:owner)
+      end
+
+      ##
+      # Build an array from {#assigned_owners} usable by Rails' `#options_for_select`.
+      # Each element in the array is built with {#option_for_owner}.
+      #
+      # @return [Array]
+      def options_for_assigned_owners(with_prompt = false)
+        owners = assigned_owners.map { |owner| option_for_owner(owner) }
+        owners.unshift(['All Users', nil]) if with_prompt
+        owners
+      end
+
+      ##
+      # Helper method that takes an owner record and returns an array for Rails'
+      # `#options_for_select`.
+      #
+      # @return [Array] a 2-index array with a display string and value.
+      def option_for_owner(owner)
+        [owner.to_str, owner.id]
+      end
+    end
+  end
+end

data/lib/acts_as_approvable/railtie.rb

@@ -0,0 +1,7 @@
+module ActsAsApprovable
+  class Railtie < Rails::Railtie
+    initializer 'acts_as_approvable.configure_rails_initialization' do |app|
+      ActiveRecord::Base.send :include, ActsAsApprovable::Model
+    end
+  end
+end

data/lib/acts_as_approvable.rb

@@ -0,0 +1,66 @@
+require 'active_record'
+
+require 'acts_as_approvable/acts_as_approvable'
+require 'acts_as_approvable/approval'
+require 'acts_as_approvable/error'
+require 'acts_as_approvable/ownership'
+require 'acts-as-approvable/version'
+
+if defined?(Rails) && Rails.version =~ /^3\./
+  require 'acts_as_approvable/railtie'
+elsif defined?(ActiveRecord)
+  ActiveRecord::Base.send :include, ActsAsApprovable::Model
+end
+
+module ActsAsApprovable
+  ##
+  # Enable the approval queue at a global level.
+  def self.enable
+    @enabled = true
+  end
+
+  ##
+  # Disable the approval queue at a global level.
+  def self.disable
+    @enabled = false
+  end
+
+  ##
+  # Returns true if the approval queue is enabled globally.
+  def self.enabled?
+    @enabled = true if @enabled.nil?
+    @enabled
+  end
+
+  ##
+  # Set the referenced Owner class to be used by generic finders.
+  #
+  # @see Ownership
+  def self.owner_class=(klass)
+    @owner_class = klass
+  end
+
+  ##
+  # Get the referenced Owner class to be used by generic finders.
+  #
+  # @see Ownership
+  def self.owner_class
+    @owner_class
+  end
+
+  ##
+  # Set the engine used for rendering view files.
+  def self.view_language=(lang)
+    @lang = lang
+  end
+
+  ##
+  # Get the engine used for rendering view files. Defaults to 'erb'
+  def self.view_language
+    if Rails.version =~ /^3\./
+      Rails.configuration.generators.rails[:template_engine].try(:to_s) || 'erb'
+    else
+      @lang || 'erb'
+    end
+  end
+end

data/lib/generators/acts_as_approvable/USAGE

@@ -0,0 +1 @@
+Generates ApprovalsController, a migration the create the Approval table, and an initializer for the plugin.