workflow 0.7.0 → 0.8.0

data/README.markdown

@@ -73,6 +73,10 @@ Events are actually instance methods on a workflow, and depending on the
 state you're in, you'll have a different set of events used to
 transition to other states.
 
+It is also easy to check, if a certain transition is possible from the
+current state . `article.can_submit?` checks if there is a `:submit`
+event (transition) defined for the current state.
+
 
 Installation
 ------------
@@ -246,6 +250,12 @@ couchrest library.
 Please also have a look at 
 [the full source code](http://github.com/geekq/workflow/blob/master/test/couchtiny_example.rb).
 
+Integration with Mongoid
+------------------------
+
+You can integrate with Mongoid following the example above for CouchDB, but there is a gem that does that for you (and includes extensive tests):
+[workflow_on_mongoid](http://github.com/bowsersenior/workflow_on_mongoid)
+
 Accessing your workflow specification
 -------------------------------------
 
@@ -308,6 +318,10 @@ logging then you can use the universal `on_transition` hook:
       end
     end
 
+Please also have a look at the [advanced end to end
+example][advanced_hooks_and_validation_test].
+
+[advanced_hooks_and_validation_test]: http://github.com/geekq/workflow/blob/master/test/advanced_hooks_and_validation_test.rb
 
 ### Guards
 
@@ -332,11 +346,13 @@ You can check `halted?` and `halted_because` values later.
 
 The whole event sequence is as follows:
 
+    * before_transition
     * event specific action
     * on_transition (if action did not halt)
     * on_exit
     * PERSIST WORKFLOW STATE, i.e. transition
     * on_entry
+    * after_transition
 
 
 Multiple Workflows
@@ -446,6 +462,14 @@ when using both a block and a callback method for an event, the block executes p
 Changelog
 ---------
 
+### New in the version 0.8.0
+
+* check if a certain transition possible from the current state with
+  `can_....?`
+* fix workflow_state persistence for multiple_workflows example
+* add before_transition and after_transition hooks as suggested by
+  [kasperbn](https://github.com/kasperbn)
+
 ### New in the version 0.7.0
 
 * fix issue#10 Workflow::create_workflow_diagram documentation and path

data/VERSION

@@ -1 +1 @@
-0.7.0
+0.8.0

data/lib/workflow.rb

@@ -5,7 +5,8 @@ module Workflow
 
   class Specification
 
-    attr_accessor :states, :initial_state, :meta, :on_transition_proc
+    attr_accessor :states, :initial_state, :meta,
+      :on_transition_proc, :before_transition_proc, :after_transition_proc
 
     def initialize(meta = {}, &specification)
       @states = Hash.new
@@ -45,6 +46,14 @@ module Workflow
       @scoped_state.on_exit = proc
     end
 
+    def after_transition(&proc)
+      @after_transition_proc = proc
+    end
+
+    def before_transition(&proc)
+      @before_transition_proc = proc
+    end
+
     def on_transition(&proc)
       @on_transition_proc = proc
     end
@@ -123,6 +132,10 @@ module Workflow
             define_method "#{event_name}!".to_sym do |*args|
               process_event!(event_name, *args)
             end
+
+            define_method "can_#{event_name}?" do
+              return self.current_state.events.include? event_name
+            end
           end
         end
       end
@@ -155,17 +168,29 @@ module Workflow
         if event.nil?
       @halted_because = nil
       @halted = false
+
+      check_transition(event)
+
+      from = current_state
+      to = spec.states[event.transitions_to]
+
+      run_before_transition(current_state, spec.states[event.transitions_to], name, *args)
+      return false if @halted
+
       return_value = run_action(event.action, *args) || run_action_callback(event.name, *args)
-      if @halted
-        return false
-      else
-        check_transition(event)
-        run_on_transition(current_state, spec.states[event.transitions_to], name, *args)
-        transition_value = transition(
-          current_state, spec.states[event.transitions_to], name, *args
-        )
-        return_value.nil? ? transition_value : return_value
-      end
+      return false if @halted
+
+      run_on_transition(from, to, name, *args)
+
+      run_on_exit(from, to, name, *args)
+
+      transition_value = persist_workflow_state to.to_s
+
+      run_on_entry(to, from, name, *args)
+
+      run_after_transition(from, to, name, *args)
+
+      return_value.nil? ? transition_value : return_value
     end
 
     def halt(reason = nil)
@@ -206,17 +231,20 @@ module Workflow
       end
     end
 
-    def transition(from, to, name, *args)
-      run_on_exit(from, to, name, *args)
-      val = persist_workflow_state to.to_s
-      run_on_entry(to, from, name, *args)
-      val
+    def run_before_transition(from, to, event, *args)
+      instance_exec(from.name, to.name, event, *args, &spec.before_transition_proc) if
+        spec.before_transition_proc
     end
 
     def run_on_transition(from, to, event, *args)
       instance_exec(from.name, to.name, event, *args, &spec.on_transition_proc) if spec.on_transition_proc
     end
 
+    def run_after_transition(from, to, event, *args)
+      instance_exec(from.name, to.name, event, *args, &spec.after_transition_proc) if
+        spec.after_transition_proc
+    end
+
     def run_action(action, *args)
       instance_exec(*args, &action) if action
     end

data/test/advanced_hooks_and_validation_test.rb

@@ -0,0 +1,118 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+$VERBOSE = false
+require 'active_record'
+require 'sqlite3'
+require 'workflow'
+
+ActiveRecord::Migration.verbose = false
+
+# Transition based validation
+# ---------------------------
+# If you are using ActiveRecord you might want to define different validations
+# for different transitions. There is a `validates_presence_of` hook that let's
+# you specify the attributes that need to be present for an successful transition.
+# If the object is not valid at the end of the transition event the transition
+# is halted and a TransitionHalted exception is thrown.
+#
+# Here is a sample that illustrates how to use the presence validation:
+# (use case suggested by http://github.com/southdesign)
+class Article < ActiveRecord::Base
+  include Workflow
+  workflow do
+    state :new do
+      event :accept, :transitions_to => :accepted, :meta => {:validates_presence_of => [:title, :body]}
+      event :reject, :transitions_to => :rejected
+    end
+    state :accepted do
+      event :blame, :transitions_to => :blamed, :meta => {:validates_presence_of => [:title, :body, :blame_reason]}
+      event :delete, :transitions_to => :deleted
+    end
+    state :rejected do
+      event :delete, :transitions_to => :deleted
+    end
+    state :blamed do
+      event :delete, :transitions_to => :deleted
+    end
+    state :deleted do
+      event :accept, :transitions_to => :accepted
+    end
+
+    on_transition do |from, to, triggering_event, *event_args|
+      if self.class.superclass.to_s.split("::").first == "ActiveRecord"
+        singleton = class << self; self end
+        validations = Proc.new {}
+
+        meta = Article.workflow_spec.states[from].events[triggering_event].meta
+        fields_to_validate = meta[:validates_presence_of]
+        if fields_to_validate
+          validations = Proc.new {
+            errors.add_on_blank(fields_to_validate) if fields_to_validate
+          }
+        end
+
+        singleton.send :define_method, :validate, &validations
+        halt! "Event[#{triggering_event}]'s transitions_to[#{to}] is not valid." if self.invalid?
+      end
+    end
+  end
+end
+
+class AdvancedHooksAndValidationTest < ActiveRecordTestCase
+
+  def setup
+    super
+
+    ActiveRecord::Schema.define do
+      create_table :articles do |t|
+        t.string :title
+        t.string :body
+        t.string :blame_reason
+        t.string :reject_reason
+        t.string :workflow_state
+      end
+    end
+
+    exec "INSERT INTO articles(title, body, blame_reason, reject_reason, workflow_state) VALUES('new1', NULL, NULL, NULL, 'new')"
+    exec "INSERT INTO articles(title, body, blame_reason, reject_reason, workflow_state) VALUES('new2', 'some content', NULL, NULL, 'new')"
+    exec "INSERT INTO articles(title, body, blame_reason, reject_reason, workflow_state) VALUES('accepted1', 'some content', NULL, NULL, 'accepted')"
+
+  end
+
+  def assert_state(title, expected_state, klass = Order)
+    o = klass.find_by_title(title)
+    assert_equal expected_state, o.read_attribute(klass.workflow_column)
+    o
+  end
+
+  test 'deny transition from new to accepted because of the missing presence of the body' do
+    a = Article.find_by_title('new1');
+    assert_raise Workflow::TransitionHalted do
+      a.accept!
+    end
+    assert_state 'new1', 'new', Article
+  end
+
+  test 'allow transition from new to accepted because body is present this time' do
+    a = Article.find_by_title('new2');
+    assert a.accept!
+    assert_state 'new2', 'accepted', Article
+  end
+
+  test 'allow transition from accepted to blamed because of a blame_reason' do
+    a = Article.find_by_title('accepted1');
+    a.blame_reason = "Provocant thesis"
+    assert a.blame!
+    assert_state 'accepted1', 'blamed', Article
+  end
+
+  test 'deny transition from accepted to blamed because of no blame_reason' do
+    a = Article.find_by_title('accepted1');
+    assert_raise Workflow::TransitionHalted do
+      assert a.blame!
+    end
+    assert_state 'accepted1', 'accepted', Article
+  end
+
+end
+

data/test/before_transition_test.rb

@@ -0,0 +1,36 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'workflow'
+
+class BeforeTransitionTest < Test::Unit::TestCase
+  class MyFlow
+    attr_reader :history
+    def initialize
+      @history = []
+    end
+
+    include Workflow
+    workflow do
+      state :first do
+        event :forward, :transitions_to => :second do
+          @history << 'forward'
+        end
+      end
+      state :second do
+        event :back, :transitions_to => :first do
+          @history << 'back'
+        end
+      end
+
+      before_transition { @history << 'before' }
+      after_transition { @history << 'after' }
+      on_transition { @history << 'on' }
+    end
+  end
+
+  test 'that before_transition is run before the action' do
+    flow = MyFlow.new
+    flow.forward!
+    flow.back!
+    assert flow.history == ['before', 'forward', 'on', 'after', 'before', 'back', 'on', 'after']
+  end
+end

data/test/main_test.rb

@@ -437,6 +437,25 @@ class MainTest < ActiveRecordTestCase
     assert article.rejected?, 'Transition should happen now'
   end
 
+  test 'can fire event?' do
+    c = Class.new do
+      include Workflow
+      workflow do
+        state :newborn do
+          event :go_to_school, :transitions_to => :schoolboy
+        end
+        state :schoolboy do
+          event :go_to_college, :transitions_to => :student
+        end
+        state :student
+      end
+    end
+
+    human = c.new
+    assert human.can_go_to_school?
+    assert_equal false, human.can_go_to_college?
+  end
+
   test 'workflow graph generation' do
     Dir.chdir('tmp') do
       capture_streams do

data/test/multiple_workflows_test.rb

@@ -1,4 +1,5 @@
 require File.join(File.dirname(__FILE__), 'test_helper')
+require 'workflow'
 class MultipleWorkflowsTest < ActiveRecordTestCase
 
   test 'multiple workflows' do
@@ -15,12 +16,14 @@ class MultipleWorkflowsTest < ActiveRecordTestCase
     exec "INSERT INTO bookings(title, workflow_state, workflow_type) VALUES('booking2', 'initial', 'workflow_2')"
 
     class Booking < ActiveRecord::Base
+
+      include Workflow
+
       def initialize_workflow
         # define workflow per object instead of per class
         case workflow_type
         when 'workflow_1'
           class << self
-            include Workflow
             workflow do
               state :initial do
                 event :progress, :transitions_to => :last
@@ -30,7 +33,6 @@ class MultipleWorkflowsTest < ActiveRecordTestCase
           end
         when 'workflow_2'
           class << self
-            include Workflow
             workflow do
               state :initial do
                 event :progress, :transitions_to => :intermediate
@@ -67,6 +69,11 @@ class MultipleWorkflowsTest < ActiveRecordTestCase
     assert booking1.workflow_spec, 'can access the individual workflow specification'
     assert_equal 2, booking1.workflow_spec.states.length
     assert_equal 3, booking2.workflow_spec.states.length
+
+    # check persistence
+    booking2reloaded = Booking.find_by_title('booking2')
+    booking2reloaded.initialize_workflow
+    assert booking2reloaded.intermediate?, 'persistence of workflow state does not work'
   end
 
   class Object

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 7
+  - 8
   - 0
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors: 
 - Vladimir Dobriakov
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-08 00:00:00 +02:00
+date: 2010-12-09 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -33,6 +33,8 @@ files:
 - Rakefile
 - VERSION
 - lib/workflow.rb
+- test/advanced_hooks_and_validation_test.rb
+- test/before_transition_test.rb
 - test/couchtiny_example.rb
 - test/main_test.rb
 - test/multiple_workflows_test.rb
@@ -73,7 +75,9 @@ summary: A replacement for acts_as_state_machine.
 test_files: 
 - test/couchtiny_example.rb
 - test/main_test.rb
+- test/before_transition_test.rb
 - test/test_helper.rb
 - test/without_active_record_test.rb
 - test/multiple_workflows_test.rb
 - test/readme_example.rb
+- test/advanced_hooks_and_validation_test.rb