alternegro / flojo

ActiveRecord aware workflow (state machine) module

Flojo

Flojo is a simple ActiveRecord aware state machine module, but it will also work with any plain old ruby object.
When used within an ActiveRecord subclass, flojo events can automatically save a record after a transition.

After including the module in your class and configuring it with an event, and a state, you can interact with instances of that class using the dynamically generated methods of the following form:

object.wf_event #Triggers event and invokes any applicable transitions

object.wf_event! #Behaves just like object.wf_event but will also persist object. 

object.wf_state?  #Returns true if the current workflow state is _state_.  

object.wf_current_state #Returns the objects current state.

To avoid method name collisions with your classes, Flojo methods are usually prefixed with wf_.
The wf_ is also handy when you need to interact with your objects in irb. Just type wf_ and tab...

See test.rb, test_active_record.rb and test_helper.rb for concrete examples.

Install

Install the gem with

gem install flojo

Alternatively, download lib/flojo.rb and copy it to your project's lib folder.

Usage

require 'flojo' 

class Baby 
  # Include the module
  include Flojo

  # configure the states. The first element represents the initial state
  workflow_states [:asleep, :crying, :pooping, :chilling, :puking]

  # configure your transitions. Using: transition :begin_state, :end_state
  event :feed do
	transition :crying, :chilling
	transition :chilling, :pooping
  end

  event :rock do
	transition :crying, :chilling
	transition :chilling, :asleep
	transition :asleep, :pooping
  end

  event :burp do
	transition :crying, :chilling
	transition :chilling, :puking
  end

  event :wake do
	transition :asleep, :crying
  end
	
  event :spank do 
	# :any is a wildcard state and is only valid as a begin state.
	transition :any, :crying
  end


  # event, enter state and exit state callbacks should take the following forms:
  # wf_on_event, wf_on_enter_state and wf_on_exit_state and are only called if they are defined  
  def wf_on_spank
	puts "Never spank a baby! Somebody dial 911!"
  end

  def wf_on_enter_chilling
	puts "drool and fart"
  end

  def wf_on_exit_asleep
	puts "waaaaah waaaaah waaaaaah"
  end

  # called only after an event yields a transition.
  def wf_after_transition
	puts "Send a tweet baby is alive and kicking"
  end 

  # called only after an event triggers a save.
  def wf_after_save
	puts "Send a tweet saying baby was saved"
  end
  
end


baby = Baby.new
baby.wf_asleep? 
baby.wf_wake
baby.wf_current_state #Should return :awake          

ActiveRecord specific details

If you want the current workflow state persisted, your table needs to have a string column named wf_state. If your table has a wf_last_event column, that column will store the most recent event triggered on the object. The module will still work if the wf_state is absent but the workflow state will be transient. When used within an ActiveRecord subclass, the "!" versions of the wf_event methods will - trigger a record save immediately after transition.

eg:

baby.wf_feed  #Will not trigger a save. 
baby.wf_feed! #Will trigger a save.

Copyright

Copyright (c) 2010 Joey Adarkwah