acts_as_approvable 0.1.1 → 0.7.0

data/lib/acts_as_approvable/model.rb

@@ -0,0 +1,60 @@
+require 'acts_as_approvable/model/class_methods'
+require 'acts_as_approvable/model/instance_methods'
+require 'acts_as_approvable/model/create_instance_methods'
+require 'acts_as_approvable/model/update_instance_methods'
+require 'acts_as_approvable/model/destroy_instance_methods'
+
+module ActsAsApprovable
+  ##
+  # The meat of {ActsAsApprovable}. This applies methods for the configured approval events
+  # and configures the required relationships.
+  module Model
+    # 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`, `:update` or `:destroy`).
+    # @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 = {})
+      extend ClassMethods
+      include InstanceMethods
+
+      cattr_accessor :approvable_on
+      self.approvable_on = Array.wrap(options.delete(:on) { [:create, :update, :destroy] })
+
+      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', primary_key, 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_disabled
+      self.approvals_disabled = false
+
+      has_many :approvals, :as => :item, :dependent => :destroy
+
+      if approvable_on?(:update)
+        include UpdateInstanceMethods
+        before_update :approvable_update, :if => :approvable_update?
+      end
+
+      if approvable_on?(:create)
+        include CreateInstanceMethods
+        before_create :approvable_create, :if => :approvable_create?
+      end
+
+      if approvable_on?(:destroy)
+        include DestroyInstanceMethods
+      end
+
+      after_save :approvable_save, :if => :approvals_enabled?
+    end
+  end
+end

data/lib/acts_as_approvable/model/class_methods.rb

@@ -0,0 +1,63 @@
+module ActsAsApprovable
+  module Model
+    ##
+    # Class methods available after acts_as_approvable has been called
+    module ClassMethods
+      ##
+      # 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?
+        global_approvals_on? and approvals_on?
+      end
+
+      def approvals_disabled?
+        not approvals_enabled?
+      end
+
+      ##
+      # Enable the approval queue for this model.
+      def approvals_on
+        self.approvals_disabled = false
+      end
+
+      ##
+      # Disable the approval queue for this model.
+      def approvals_off
+        self.approvals_disabled = true
+      end
+
+      def approvals_on?
+        not self.approvals_disabled
+      end
+
+      def global_approvals_on?
+        ActsAsApprovable.enabled?
+      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.approvable_on.include?(event)
+      end
+
+      ##
+      # Returns a list of fields that require approval.
+      def approvable_fields
+        return self.approvable_only unless self.approvable_only.empty?
+        column_names - self.approvable_ignore
+      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_on?
+        approvals_off
+        yield(self)
+      ensure
+        approvals_on if enable
+      end
+    end
+  end
+end

data/lib/acts_as_approvable/model/create_instance_methods.rb

@@ -0,0 +1,88 @@
+module ActsAsApprovable
+  module Model
+    ##
+    # 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)
+        elsif approval.present?
+          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.present? ? approval_state == 'pending' : approval.try(:pending?)
+      end
+
+      ##
+      # Returns true if the record has been approved.
+      def approved?
+        approval_state.present? ? approval_state == 'approved' : approval.try(:approved?)
+      end
+
+      ##
+      # Returns true if the record has been rejected.
+      def rejected?
+        approval_state.present? ? approval_state == 'rejected' : approval.try(: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
+
+      def reset!
+        return unless approvable_on?(:create) && approval.present?
+        approval.reset!
+      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
+  end
+end

data/lib/acts_as_approvable/model/destroy_instance_methods.rb

@@ -0,0 +1,38 @@
+module ActsAsApprovable
+  module Model
+    ##
+    # Instance methods that apply to the `:destroy` event specifically.
+    module DestroyInstanceMethods
+      ##
+      # Retrieve approval records for the destruction event.
+      #
+      # @param [Boolean] all toggle for returning all or pending approvals
+      # @return [Approval]
+      def destroy_approvals(all = true)
+        all ? approvals.find_all_by_event('destroy') : approvals.find_all_by_event_and_state('destroy', 0)
+      end
+
+      ##
+      # Returns true if there are any pending `:destroy` event approvals
+      def pending_destruction?
+        not destroy_approvals(false).empty?
+      end
+
+      ##
+      # Add a `:destrory` approval event to the queue if approvals are enabled, otherwise
+      # destroy the record.
+      def destroy
+        approvable_destroy? ? request_destruction : super
+      end
+
+      private
+      def approvable_destroy?
+        approvals_enabled? and approvable_on?(:destroy)
+      end
+
+      def request_destruction
+        approvals.create!(:event => 'destroy', :state => 'pending', :original => attributes)
+      end
+    end
+  end
+end

data/lib/acts_as_approvable/model/instance_methods.rb

@@ -0,0 +1,107 @@
+module ActsAsApprovable
+  module Model
+    ##
+    # 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?
+        global_approvals_on? and model_approvals_on? and approvals_on?
+      end
+
+      ##
+      # Returns the inverse of `#approvals_enabled?`
+      def approvals_disabled?
+        not approvals_enabled?
+      end
+
+      ##
+      # Turn off approvals for this instance.
+      def approvals_off
+        @approvals_disabled = true
+      end
+
+      ##
+      # Turn on approvals for this instance.
+      def approvals_on
+        @approvals_disabled = false
+      end
+
+      ##
+      # Returns true if the approval queue is on for this instance.
+      def approvals_on?
+        not @approvals_disabled
+      end
+
+      ##
+      # Returns true if the approval queue is on for this model.
+      def model_approvals_on?
+        self.class.approvals_on?
+      end
+
+      ##
+      # Returns true if the approval queue is on globally.
+      def global_approvals_on?
+        ActsAsApprovable.enabled?
+      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?(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) #:nodoc:
+        without_approval { |i| save(*args) }
+      end
+
+      def save_without_approval!(*args) #:nodoc:
+        without_approval { |i| save!(*args) }
+      end
+
+      def destroy_without_approval #:nodoc:
+        without_approval { |i| destroy }
+      end
+
+      def destroy_without_approval! #:nodoc:
+        without_approval { |i| destroy! }
+      end
+
+      private
+      def approvable_save
+        @approval.save if @approval.present? && @approval.new_record?
+      end
+    end
+  end
+end

data/lib/acts_as_approvable/model/update_instance_methods.rb

@@ -0,0 +1,61 @@
+module ActsAsApprovable
+  module Model
+    ##
+    # Instance methods that apply to the :update event specifically.
+    module UpdateInstanceMethods
+      ##
+      # Retrieve all approval records for `:update` events.
+      def update_approvals(all = true)
+        all ? approvals.find_all_by_event('update') : approvals.find_all_by_event_and_state('update', 0)
+      end
+
+      ##
+      # Returns true if the record has any `#update_approvals` that are pending
+      # approval.
+      def pending_changes?
+        !update_approvals(false).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
+        approvable_fields.select { |field| changed.include?(field) }
+      end
+
+      ##
+      # Returns a list of fields that require approval.
+      def approvable_fields
+        self.class.approvable_fields
+      end
+
+      private
+      def approvable_update?
+        approvals_enabled? and approvable_on?(:update) and changed_notably?
+      end
+
+      def approvable_update
+        changed = {}
+        originals = {}
+
+        notably_changed.each do |attr|
+          original, changed_to = changes[attr]
+
+          write_attribute(attr.to_s, original)
+          changed[attr] = changed_to
+          originals[attr] = original
+        end
+
+        @approval = approvals.build(:event => 'update', :state => 'pending', :object => changed, :original => originals)
+      end
+    end
+  end
+end

data/lib/acts_as_approvable/ownership.rb

@@ -0,0 +1,141 @@
+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`).
+    # @option options [Object] :source  class used to override retrieval of owner records.
+    def self.configure(options = {}, &block)
+      approval = options.delete(:model) { Approval }
+      owner = options.delete(:owner) { User }
+
+      approval.send(:include, self)
+
+      ActsAsApprovable.owner_class = owner
+      ActsAsApprovable.owner_source = options.delete(:source)
+
+      approval.send(:belongs_to, :owner, :class_name => owner.to_s, :foreign_key => :owner_id)
+    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
+
+      ##
+      # Source class used to override Owner retrieval methods
+      #
+      # @see ActsAsApprovable::Ownership.configure
+      def owner_source
+        ActsAsApprovable.owner_source
+      end
+
+      ##
+      # Attempt to run a method on the configured #owner_source class. If it does
+      # not exist yield to the given block.
+      def with_owner_source(method, *args)
+        if owner_source && owner_source.singleton_class.method_defined?(method)
+          owner_source.send(method, *args)
+        else
+          yield
+        end
+      end
+
+      ##
+      # A list of records that can be assigned to an approval.
+      #
+      # This method can be overriden by the configured #owner_source.
+      def available_owners
+        with_owner_source(: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.
+      #
+      # This method can be overriden by the configured #owner_source.
+      def assigned_owners
+        with_owner_source(: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`.
+      #
+      # This method can be overriden by the configured #owner_source.
+      #
+      # @return [Array] a 2-index array with a display string and value.
+      def option_for_owner(owner)
+        with_owner_source(:option_for_owner, owner) { [owner.to_str, owner.id] }
+      end
+    end
+  end
+end