runcoderun-aasm 2.0.5 → 2.0.5.1

data/EXAMPLES.rdoc

@@ -0,0 +1,342 @@
+= Examples
+The examples below show how people have used some of the more or less advanced features of AASM.
+
+== Transitions, events and guards
+Imagine you have a person that is able to 
+ * sleep
+ * work
+ * shower
+ * date
+ 
+It is considered good manner to shower before dating and going to work. ASSM can easily make sure good manners are followed:
+
+ class Person < ActiveRecord::Base  
+   include AASM
+   
+   aasm_initial_state :sleeping
+    
+   aasm_state :sleeping  
+   aasm_state :showering  
+   aasm_state :working  
+   aasm_state :dating  
+   
+   event :shower do  
+     transitions :from => :sleeping, :to => :showering  
+     transitions :from => :working, :to => :showering  
+     transitions :from => :dating, :to => :showering  
+   end  
+   
+   event :work do  
+     transitions :from => :showering, :to => :working  
+     # Going to work before showering?  Stinky.  
+     transitions :from => :sleeping, :to => :working  
+   end  
+   
+   event :date do  
+     transitions :from => :showering, :to => :dating  
+   end  
+   
+   event :sleep do  
+     transitions :from => :showering, :to => :sleeping  
+     transitions :from => :working, :to => :sleeping  
+     transitions :from => :dating, :to => :sleeping  
+   end  
+ end
+
+
+Note: The plugin makes an assumption that the state of your model is saved in field called state. This can be replaced by adding the additional option :aasm_column => :status (which will use the "status" column).
+
+Warning: If you are using a model that stores addresses, be weary of a field called “state”. You can spend hours wondering why things aren’t working like they should be.
+
+Usually a good idea is to describe the states in models as an adjective, and the event as a verb.
+
+Notice how in line 2 we explicitly state the initial state of the model. In lines 3 to 6, we indicate the various states the Person may be in.
+
+== State for ActiveRecord models require they are saved
+There is a peculiar behavior when creating objects via new, in that the model’s state is not specified. It will only be specified when saving the new record. One solution is to specify the default state from within the migration. The other solution then is to call create.
+
+ person = Person.new  
+ person.state # nil  
+ person.save # true  
+ person.state # "sleeping"  
+   
+ person = Person.create  
+ person.state # "sleeping"  
+ person.sleeping? # true  
+ person.rotting? # false  
+   
+ person = Person.new  
+ person.state = "rotting" # "rotting"  
+ person.rotting? # true  
+ person.sleeping? # false
+
+If you didn’t notice the trend, the method to test if the model is in the state, is to append the state with a question mark: "state?"
+
+The events you specified also creates instance methods, to transition the model from one state to another.
+
+The following instance methods were created:
+
+   person.shower!  
+   person.work!  
+   person.date!  
+   person.sleep!  
+
+
+Note: The instance methods created follow the pattern "event!"
+=== Events
+By calling any event, you also call ActiveRecord::Base.save. For when it fails, it only returns false. You can guard yourself by calling valid? and save!
+
+Events help you to transition from one state to another. So suppose your person is sleeping, and you want him to shower, well we’ll just call shower!.
+
+    1. person.state # "sleeping"  
+    2. person.shower!  
+    3. person.state # "showering"   
+
+Events can help your organize the flow of your model. But they can get more powerful with callbacks.
+
+=== Callbacks
+
+The state also comes with a few callbacks that can be used.
+
+    state :sleeping,  
+             :enter => :get_into_bed,  
+             :after => Proc.new {|model| model.whack_alarm_clock },  
+             :exit => :make_up_bed  
+
+Callbacks are called when the model is transitioning into the specified state.
+
+Note:
+
+     * Callbacks can be either a symbol or a Proc. If used as a symbol, the instance method of the model will be called
+     * The callbacks act differently if the model is a new record and hasn’t been saved, versus an already saved model.
+
+When put into consideration with ActiveRecord’s callbacks, a new record’s callback would look like this:
+
+     * ActiveRecord::Base.before_save
+     * ActiveRecord::Base.save
+     * acts_as_state_machine :enter sleeping
+     * acts_as_state_machine :after sleeping
+     * ActiveRecord::Base.after_save
+
+ When the model is no longer a new record, the callbacks execute as follows, if I had called the shower! method.
+
+     * acts_as_state_machine :enter showering
+     * ActiveRecord::Base.before_save
+     * ActiveRecord::Base.save
+     * ActiveRecord::Base.after_save
+     * acts_as_state_machine :after showering
+     * acts_as_state_machine :exit sleeping
+
+== Guarding States
+
+But how about if you want some sort of validation for a transition. You know, just to ensure data integrity.
+
+    event :work do  
+      transitions :from => :showering, :to => :working  
+      # Going to work before showering?  Stinky.  
+      transitions :from => :sleeping, :to => :working, :guard => Proc.new {|o| o.clean? }  
+    end  
+
+The transition can be guarded by specifying a :guard option, with either a symbol or Proc (similar to the Callbacks). The method or Proc has to return true to proceed with the transition, else it will fail silently.
+
+
+== Add a history log to all state changes
+Example from Artem Vasiliev's blog (Note that the blog mentions :log_transitions which is changed to :on_transition 
+
+class ExpenseClaim < ActiveRecord::Base  
+  has_many :action_history, :class_name => 'ActionHistoryItem', :as => :document,  
+    :order => 'id desc'  
+  
+  acts_as_state_machine :initial => States::DRAFT, :on_transition => :log_transitions 
+  
+  state States::DRAFT, :owner => Roles::AUTHOR  
+  state States::MANAGER_APPROVAL_REQUIRED, :owner => Roles::APPROVING_MANAGER  
+  state States::REJECTED_BY_FINANCE, :owner => Roles::APPROVING_MANAGER  
+  
+  #...  
+  event :send_for_manager_approval do  
+    transitions :from => States::DRAFT, :to => States::MANAGER_APPROVAL_REQUIRED  
+    transitions :from => States::REJECTED_BY_MANAGER,  
+      :to => States::MANAGER_APPROVAL_REQUIRED  
+  end  
+  
+  event :approve do  
+    transitions :from => States::MANAGER_APPROVAL_REQUIRED,  
+      :to => States::FINANCE_APPROVAL_REQUIRED  
+  
+    transitions :from => States::FINANCE_APPROVAL_REQUIRED,  
+      :to => States::APPROVED  
+  
+    transitions :from => States::REJECTED_BY_FINANCE,  
+      :to => States::FINANCE_APPROVAL_REQUIRED  
+  end  
+  
+  #...  
+  def log_transition(from, to, event, opts)  
+    user = self.updated_by  
+    raise "user is not set" if user.nil?  
+    as_role = self.class.states_table[from].opts[:owner]  
+    action_history << ActionHistoryItem.new({:from_state => from.to_s,  
+      :to_state => to.to_s, :action => event.to_s, :user_id => user.id,  
+      :as_role => as_role.to_s, :at => Time.now})  
+  end  
+#...  
+end                  
+
+
+= Booking example (complex model with many callbacks)
+Here is a Booking model as an example.Requirements being a lifecycle of states that includes In Progress, Pending, In Review, Cancelled, Confirmed, Awaiting Payment and Service Rendered.
+
+(NOTE that the example below uses outdated AASM syntax. Please submit a fix)
+
+  class Booking < ActiveRecord::Base
+    include Comparable
+    self.abstract_class = true
+    set_table_name 'bookings'
+    acts_as_recent 1.days
+
+    attr_accessor :payment_option
+
+    belongs_to :account
+    belongs_to :user
+    belongs_to :coupon
+
+    has_one :date, :class_name => 'BookingDate', :dependent => :destroy, :foreign_key => :booking_id     
+    has_one :customer, :dependent => :destroy
+    has_one :payment, :as => :payable, :dependent => :destroy
+    has_one :progress, :class_name => 'BookingProgress', :dependent => :destroy
+    has_one :token, :class_name => 'PaymentToken', :dependent => :destroy 
+
+    has_many :booking_products, :class_name => 'BookingProduct', :foreign_key => :booking_id, :dependent => :delete_all, :after_add => [Proc.new{|b,bp| bp.booking_extras.collect{|be| be.save! }}, Proc.new{|b,bp| bp.product.extras.compulsary_included.collect{|e| bp.extras << e }}]
+    has_many :booking_extras, :include => [:extra, :booking_product], :dependent => :delete_all
+
+    has_many :products, :through => :booking_products, :source => :product, :uniq => true
+    has_many :extras, :through => :booking_extras, :source => :extra, :uniq => true
+
+    has_many :events, :class_name => 'BookingEvent', :dependent => :delete_all, :order => 'booking_events.created_at DESC', :extend => BookingEventsExtension
+    has_many :extras, :through => :line_items_extras, :source => :extra
+    has_many :notes, :class_name => 'BookingNote', :dependent => :delete_all, :after_add => Proc.new {|b,bn| BookingMailer.deliver_note( bn )},  :extend => BookingNotesExtension
+
+    delegate :to_s, :to => :name
+    delegate :duration, :to => :date
+    delegate :date_from, :date_to, :duration, :to => :date  
+    delegate :any_progress?, :to => :progress   
+  
+    validates_presence_of :reference, :account_id, :user_id
+    validates_uniqueness_of :reference, :scope => 'account_id', :on => :create
+    validates_length_of :reference, :is => 10 
+  
+  
+    include AASM 
+    aasm_initial_state :in_progress 
+    aasm_column :status   
+
+    state :in_progress
+    state :pending, 
+          :enter => Proc.new{|b| b.commit!; BookingMailer.deliver_received( b ); }
+
+    state :awaiting_payment, 
+          :enter => Proc.new{|b| ( b.create_token({ :account_id => b.account.id, :booking_id => b.id }) if b.token.nil? ); BookingMailer.deliver_payment( b ); }, 
+          :after => Proc.new{|b| b.log( 'Status set to %s.' / b.current_status_to_human ) }
+
+    state :in_review, 
+          :enter => Proc.new{|b| BookingMailer.deliver_review( b ) }, 
+          :after => Proc.new{|b| b.log( 'Booking status set to %s.' / b.current_status_to_human ) }
+
+    state :cancelled, 
+          :enter => Proc.new{|b| BookingMailer.deliver_cancelled( b ); }, 
+          :after => Proc.new{|b| b.log( 'Booking status set to %s.' / b.current_status_to_human ) }
+
+    state :confirmed, 
+          :enter => Proc.new{|b| BookingMailer.deliver_confirmed( b ); }, 
+          :after => Proc.new{|b| b.log( 'Booking status set to %s.' / b.current_status_to_human ) }
+
+    state :service_rendered, 
+          :enter => Proc.new{|b| BookingMailer.deliver_feedback( b ); }, 
+          :after => Proc.new{|b| b.log( 'Booking status set to %s.' / b.current_status_to_human ) }
+
+    event( :pending ){ transitions :to => :pending, :from => :in_progress }   
+
+    event( :awaiting_payment ){ transitions :to => :awaiting_payment, :from => [:pending, :in_review] } 
+
+    event( :in_review ){ transitions :to => :in_review, :from => [:pending, :awaiting_payment] }
+
+    event( :cancelled ){ transitions :to => :cancelled, :from => [:pending, :awaiting_payment, :in_review] }  
+
+    event( :confirmed ){ transitions :to => :confirmed, :from => :awaiting_payment, :guard => Proc.new{|b| !b.payment.nil? && b.payment.authorized? } }
+
+    event( :service_rendered ){ transitions :to => :service_rendered, :from => :confirmed }      
+
+    class << self
+
+      def status_to_human( status = :pending ) status.to_s.sub('_',' ').upcase end
+
+      def running_total
+        self.find(:all, :conditions => ['bookings.status = ?','confirmed']).inject( Globalize::Currency.free ) { |total, booking| booking.total + total }
+      end   
+
+      def total_by_status(state = :in_progress)
+        self.find_in_state(:all, state).inject( Globalize::Currency.free ) { |total, booking| booking.total + total }
+      end
+
+      def count_by_status(state = :in_progress) self.count_in_state(state) end
+
+      def most_recent_by_status(state = :pending)
+        self.find_in_state(:first, state, :order => 'bookings.created_at DESC')
+      end     
+
+    end
+
+    def current_status_to_human; self.class.status_to_human( self.current_state() ) end
+
+    def log( event_description )
+      self.events.create!({ :account_id => self.account.id, :event_description => event_description })
+    end
+
+    def total
+      Globalize::Currency.new( ( self.booking_products.sum(:cents).to_i + self.booking_extras.sum(:cents).to_i ) ) - discount
+    end
+
+    def discount; (!self.coupon.nil? ? self.coupon.price : Globalize::Currency.free) end   
+
+    def name; "[#{self.reference}] #{self.customer.name}" end
+
+    def editable?() [:in_progress, :in_review].include?( self.current_state ) end
+
+    def committed?() self.current_state != :in_progress end
+
+    def <=>(other_booking)
+      self.date.date_from <=> other_booking.date.date_from
+    end
+  end
+
+=== Event definitions
+
+Declare the business logic required to manage the transitions between the required states.
+
+A Booking may only be Confirmed once a payment method has been assigned AND authorized.
+
+    event( :confirmed ){ transitions 
+           :to => :confirmed, 
+           :from => :awaiting_payment, 
+           :guard => Proc.new{|b| !b.payment.nil? && b.payment.authorized? } 
+    }
+
+An event accepts a symbol as the only argument ( :confirmed ).Express the transition within the block, with the following Hash keys allowed as arguments to the transitions singleton method:
+
+  { :from => :the_intial_state,
+    :to => :the_target_state,
+    :guard => Proc.new{|record| record.condition_to_be_met_for_transition_to_occur? } 
+  }  
+
+Do note that the resulting event is a destructive action (modifies the receiver) and should be invoked with
+
+  booking.confirmed! #trailing !
+
+= Credits
+Examples are gathered from existing sources. Especially thanks to 
+ * Artem Vasiliev http://thirstydoh.wordpress.com/2007/12/05/aasm-improvements/
+ * Aizat Faiz http://rails.aizatto.com/2007/05/24/ruby-on-rails-finite-state-machine-plugin-acts_as_state_machine/     
+ * Lourens Naude http://blog.methodmissing.com/2006/11/16/beyond-callbacks-for-complex-model-lifecycles/
+ * Jesper Rønn-Jensen ( http://justaddwater.dk/ ) for collecting examples
+ 

data/README.rdoc

@@ -56,6 +56,8 @@ Here's a quick example highlighting some of the features.
       transitions :to => :closed, :from => [:read, :unread]
     end
   end
+                      
+See the more complex examples in EXAMPLES.rdoc file
 
 = Other Stuff
 

data/lib/aasm.rb

@@ -5,7 +5,7 @@ require File.join(File.dirname(__FILE__), 'persistence')
 
 module AASM
   def self.Version
-    '2.0.5'
+    '2.0.5.1'
   end
 
   class InvalidTransition < RuntimeError

data/lib/event.rb

@@ -34,11 +34,11 @@ module AASM
       
       def execute_success_callback(obj)
         case success
-        when String, Symbol:
+        when String, Symbol
           obj.send(success)
-        when Array:
+        when Array
           success.each { |meth| obj.send(meth) }
-        when Proc:
+        when Proc
           success.call(obj)
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: runcoderun-aasm
 version: !ruby/object:Gem::Version 
-  version: 2.0.5
+  version: 2.0.5.1
 platform: ruby
 authors: 
 - Scott Barron
@@ -24,11 +24,13 @@ extra_rdoc_files:
 - MIT-LICENSE
 - TODO
 - CHANGELOG
+- EXAMPLES.rdoc
 files: 
 - CHANGELOG
 - MIT-LICENSE
 - Rakefile
 - README.rdoc
+- EXAMPLES.rdoc
 - TODO
 - lib/aasm.rb
 - lib/event.rb