acts_as_approvable 0.1.1 → 0.7.0

data/generators/acts_as_approvable/templates/views/erb/_owner_select.html.erb

@@ -0,0 +1,4 @@
+<%% form_for(approval, :url => assign_approval_path(approval.id), :html => {:class => 'assignment'}) do |f| %>
+  <%%= f.select(:owner_id, options_for_select(Approval.options_for_available_owners(true), approval.owner_id)) %>
+  <%%= f.submit('Set') %>
+<%% end %>

data/generators/acts_as_approvable/templates/views/erb/_table.html.erb

@@ -0,0 +1,26 @@
+<table>
+  <thead>
+    <tr>
+      <th>Type</th>
+      <th>Record</th>
+<% if owner? %>      <th>Owner</th>
+<% end %>      <th>State</th>
+      <th>&nbsp;</th>
+    </tr>
+  </thead>
+  <tbody>
+    <%% @approvals.each do |approval| %>
+      <tr>
+        <td><%%= approval.item_type.classify %></td>
+        <td><%%= approval.item.try(:to_s) || approval.item.id %></td>
+<% if owner? %>        <td><%%= render :partial => 'owner_select', :locals => {:approval => approval} %></td>
+<% end %>        <td><%%= approval.state %></td>
+        <td class='actions'>
+          <%%= link_to('Approve', approve_approval_path(approval), :class => 'approve') %>
+          <%%= link_to('Reject', reject_approval_path(approval), :class => 'reject') %>
+        </td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>
+

data/generators/acts_as_approvable/templates/views/erb/index.html.erb

@@ -0,0 +1,17 @@
+<h1>Approval Queue</h1>
+
+<%% form_for(:approval, :url => approvals_path, :html => {:method => :get}) do |f| %>
+  <%% unless @conditions[:state].is_a?(Array) # History page shouldn't allow selecting different states %>
+    <%%= label_tag(:state) %>
+    <%%= select_tag(:state, options_for_select(Approval.options_for_state, @conditions[:state])) %>
+  <%% end %>
+<% if owner? %>  <%%= label_tag(:owner_id) %>
+  <%%= select_tag(:owner_id, options_for_select(Approval.options_for_assigned_owners, @conditions[:owner_id]), :prompt => 'All Users') %>
+<% end %>  <%%= label_tag(:item_type) %>
+  <%%= select_tag(:item_type, options_for_select(Approval.options_for_type, @conditions[:item_type]), :prompt => 'All Types') %>
+  <%%= f.submit('Filter') %>
+<%% end %>
+
+<%%= render :partial => @table_partial %>
+<% if scripts? %>
+<%%= javascript_include_tag 'jquery.form.js', 'approvals.js' %><% end %>

data/generators/acts_as_approvable/templates/views/haml/_owner_select.html.haml

@@ -0,0 +1,3 @@
+- form_for(approval, :url => assign_approval_path(approval.id), :html => {:class => 'assignment'}) do |f|
+  = f.select(:owner_id, options_for_select(Approval.options_for_available_owners(true), approval.owner_id))
+  = f.submit('Set')

data/generators/acts_as_approvable/templates/views/haml/_table.html.haml

@@ -0,0 +1,19 @@
+%table
+  %thead
+    %tr
+      %th Type
+      %th Record
+<% if owner? %>      %th Owner
+<% end %>      %th State
+      %th
+  %tbody
+    - @approvals.each do |approval|
+      %tr
+        %td= approval.item_type.classify
+        %td= approval.item.try(:to_s) || approval.item.id
+<% if owner? %>        %td= render :partial => 'owner_select', :locals => {:approval => approval}
+<% end %>        %td= approval.state
+        %td.actions
+          = link_to('Approve', approve_approval_path(approval), :class => 'approve')
+          = link_to('Reject', reject_approval_path(approval), :class => 'reject')
+

data/generators/acts_as_approvable/templates/views/haml/index.html.haml

@@ -0,0 +1,15 @@
+%h1 Approval Queue
+
+- form_for(:approval, :url => approvals_path, :html => {:method => :get}) do |f|
+  - unless @conditions[:state].is_a?(Array) # History page shouldn't allow selecting different states
+    = label_tag('state', 'State')
+    = select_tag('state', options_for_select(Approval.options_for_state, @conditions[:state]))
+<% if owner? %>  = label_tag('owner_id', 'Owner')
+  = select_tag('owner_id', options_for_select(Approval.options_for_assigned_owners(true), @conditions[:owner_id]))
+<% end %>  = label_tag('item_type', 'Type')
+  = select_tag('item_type', options_for_select(Approval.options_for_type(true), @conditions[:item_type]))
+  %button{:type => 'Submit'} Filter
+
+= render :partial => @table_partial
+<% if scripts? %>
+= javascript_include_tag 'jquery.form.js', 'approvals.js'<% end %>

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/rails/init'

data/lib/acts_as_approvable.rb

@@ -1,4 +1,98 @@
 require 'active_record'
-require 'acts_as_approvable/approver'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'acts_as_approvable/model'
+require 'acts_as_approvable/approval'
+require 'acts_as_approvable/error'
+require 'acts_as_approvable/ownership'
 require 'acts_as_approvable/version'
-ActiveRecord::Base.send :include, ActsAsApprovable::Approver
+
+if defined?(Rails) && Rails.version =~ /^3\./
+  require 'acts_as_approvable/railtie'
+elsif defined?(ActiveRecord)
+  ActiveRecord::Base.send :extend, ActsAsApprovable::Model
+end
+
+$LOAD_PATH.shift
+
+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 class used for overriding Ownership retrieval
+  #
+  # @see Ownership
+  def self.owner_source=(source)
+    @owner_source = source
+  end
+
+  ##
+  # Get the class used for overriding Ownership retrieval
+  #
+  # @see Ownership
+  def self.owner_source
+    @owner_source
+  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
+
+  ##
+  # Enable or disable the stale record check when approving updates.
+  def self.stale_check=(bool)
+    @stale_check = !!bool
+  end
+
+  ##
+  # Get the state of the stale check.
+  def self.stale_check?
+    @stale_check || true
+  end
+end

data/lib/acts_as_approvable/approval.rb

@@ -1,12 +1,206 @@
 class Approval < ActiveRecord::Base
-  belongs_to :approvable, :polymorphic => true
-  belongs_to :approver, :polymorphic => true
-  
-  validates :approvable_id, :approvable_type, :presence => true
-  validates :approvable_id, :uniqueness => {:scope => :approvable_type}
-  
-  # Scoped wrapped in lambdas because ActiveRecord's connection hasn't been established at the
-  # time of this classes' load.
-  scope :pending, lambda{ where(:approved => false) }
-  scope :approved_today, lambda{ where(:approved => true).where(arel_table[:updated_at].eq(Date.today)) }
-end
+  ##
+  # 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 destroy)
+  validates_numericality_of :state, :greater_than_or_equal_to => 0, :less_than => STATES.length
+
+  serialize :object
+  serialize :original
+
+  before_save :able_to_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 able_to_save?
+    unlocked? or state_was == 'pending'
+  end
+
+  ##
+  # Returns true if the affected item has been updated since this approval was
+  # last updated.
+  def stale?
+    unlocked? and item.has_attribute?(:updated_at) and updated_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 the approval is stale and the stale check is enabled.
+  def stale_approval?
+    ActsAsApprovable.stale_check? and update? and 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
+
+  ##
+  # Returns true if this is a `:destroy` approval event.
+  def destroy?
+    event == 'destroy'
+  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 !force and stale_approval?
+    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')
+    elsif destroy?
+      item.destroy_without_approval
+    end
+
+    item.save_without_approval! unless destroy?
+    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)
+
+    item.set_approval_state('rejected') if create?
+
+    item.save_without_approval!
+    update_attributes!(:state => 'rejected', :reason => reason)
+    run_item_callback(:after_reject)
+  end
+
+  ##
+  # Force the approval back into a 'pending' state. Only valid for :create events.
+  #
+  # @raise [ActsAsApprovable::Error::InvalidTransition] raised if the event is not {#create? :create}.
+  def reset!
+    raise ActsAsApprovable::Error::InvalidTransition.new(state, 'pending', self) unless create?
+
+    item.set_approval_state('pending')
+    item.save_without_approval!
+
+    state_will_change! # Force an update to the record
+    update_attributes!(:state => 'rejected')
+  end
+
+  private
+  def run_item_callback(callback)
+    item.send(callback, self) != false
+  end
+end

data/lib/acts_as_approvable/error.rb

@@ -0,0 +1,34 @@
+module ActsAsApprovable
+  class Error < RuntimeError
+    ##
+    # Raised when a locked approval is accepted or rejected.
+    class Locked < ActsAsApprovable::Error
+      def initialize(*args)
+        super('this approval is locked')
+      end
+    end
+
+    ##
+    # Raised when a stale approval is accepted.
+    class Stale < ActsAsApprovable::Error
+      def initialize(*args)
+        super('this approval is stale and should not be approved')
+      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)
+        super('this record cannot be assigned as an owner')
+      end
+    end
+
+    class InvalidTransition < ActsAsApprovable::Error
+      def initialize(from, to, approval)
+        super("you may not transition from #{from} to #{to} in a #{approval.event} approval")
+      end
+    end
+  end
+end