rails-workflow 1.4.0

data/lib/workflow/adapters/active_record_validations.rb

@@ -0,0 +1,110 @@
+require 'active_support/concern'
+
+module Workflow
+  module Adapter
+    module ActiveRecordValidations
+      extend ActiveSupport::Concern
+
+      ###
+      #
+      # Captures instance method calls of the form `:transitioning_from_<state_name>`
+      #   and `:transitioning_to_<state_name>`.
+      #
+      # For use with validators, e.g. `validates :foobar, presence: true, if: :transitioning_to_some_state?`
+      #
+      def method_missing(method, *args, &block)
+        if method.to_s =~ /^transitioning_(from|to|via_event)_([\w_-]+)\?$/
+          class_eval "
+          def #{method}
+            transitioning? direction: '#{$~[1]}', state: '#{$~[2]}'
+          end
+          "
+          send method
+        else
+          super
+        end
+      end
+
+      def valid?(context=nil)
+        if errors.any?
+          false
+        else
+          super
+        end
+      end
+
+      def can_transition?(event_id)
+        event = current_state.find_event(event_id)
+        return false unless event
+
+        from = current_state.name
+        to = event.evaluate(self)
+
+        return false unless to
+
+        within_transition(from, to, event_id) do
+          valid?
+        end
+      end
+
+      ###
+      #
+      # Executes the given block within a context that is able to give
+      # correct answers to the questions, `:transitioning_from_<old_state>?`.
+      # `:transitioning_to_<new_state>`, `:transitioning_via_event_<event_name>?`
+      #
+      # For use with validators, e.g. `validates :foobar, presence: true, if: :transitioning_to_some_state?`
+      #
+      # = Example:
+      #
+      #    before_transition do |from, to, name, *args|
+      #      @halted = !within_transition from, to, name do
+      #        valid?
+      #      end
+      #    end
+      #
+      def within_transition(from, to, event, &block)
+        begin
+          @transition_context = TransitionContext.new \
+            from: from,
+            to: to,
+            event: event,
+            attributes: {},
+            event_args: []
+
+          return block.call()
+        ensure
+          @transition_context = nil
+        end
+      end
+
+      module ClassMethods
+        def halt_transition_unless_valid!
+          before_transition unless: :valid? do |model|
+            throw :abort
+          end
+        end
+
+        def wrap_transition_in_transaction!
+          around_transition do |model, transition|
+            model.with_lock do
+              transition.call
+            end
+          end
+        end
+      end
+
+      private
+
+      def transitioning?(direction:, state:)
+        state = state.to_sym
+        return false unless transition_context
+        case direction
+        when 'from' then transition_context.from == state
+        when 'to' then transition_context.to == state
+        else transition_context.event == state
+        end
+      end
+    end
+  end
+end

data/lib/workflow/adapters/remodel.rb

@@ -0,0 +1,15 @@
+module Workflow
+  module Adapter
+    module Remodel
+      module InstanceMethods
+        def load_workflow_state
+          send(self.class.workflow_column)
+        end
+
+        def persist_workflow_state(new_value)
+          update(self.class.workflow_column => new_value)
+        end
+      end
+    end
+  end
+end

data/lib/workflow/callbacks.rb

@@ -0,0 +1,274 @@
+module Workflow
+  module Callbacks
+
+    extend ActiveSupport::Concern
+    include ActiveSupport::Callbacks
+
+    CALLBACK_MAP =   {
+      transition: :event,
+      exit: :from,
+      enter: :to
+    }.freeze
+
+    # @!attribute [r] transition_context
+    #   During state transition events, contains a {TransitionContext} representing the transition underway.
+    #   @return [TransitionContext] representation of current state transition
+    #
+    included do
+      attr_reader :transition_context
+      CALLBACK_MAP.keys.each do |type|
+        define_callbacks type,
+          skip_after_callbacks_if_terminated: true
+      end
+    end
+
+    module ClassMethods
+      ##
+      # @!method before_transition
+      #
+      # :call-seq:
+      #   before_transition(*instance_method_names, options={})
+      #   before_transition(options={}, &block)
+      #
+      # Append a callback before transition.
+      # Instance methods used for `before` and `after` transitions
+      # receive no parameters.  Instance methods for `around` transitions will be given a block,
+      # which must be yielded/called in order for the sequence to continue.
+      #
+      # Using a block notation, the first parameter will be an instance of the object
+      # under transition, while the second parameter (`around` transition only) will be
+      # the block which should be called for the sequence to continue.
+      #
+      # == Transition Metadata
+      #
+      # Within the callback you can access the `transition_context` instance variable,
+      # which will give you metadata and arguments passed to the transition.
+      # See Workflow::TransitionContext
+      #
+      # == Options
+      #
+      # === If / Unless
+      #
+      # The callback will run `if` or `unless` the named method returns a truthy value.
+      #
+      #    #  Assuming some_instance_method returns a boolean,
+      #    before_transition :do_something, if: :some_instance_method
+      #    before_transition :do_something_else, unless: :some_instance_method
+      #
+      # === Only / Except
+      #
+      # The callback will run `if` or `unless` the event being processed is in the list given
+      #
+      #     #  Run this callback only on the `accept` and `publish` events.
+      #     before_transition :do_something, only: [:accept, :publish]
+      #     #  Run this callback on events other than the `accept` and `publish` events.
+      #     before_transition :do_something_else, except: [:accept, :publish]
+      #
+
+      ##
+      # @!method prepend_before_transition(*instance_method_names, options={})
+      #
+      # Something Interesting
+      #
+      # @overload prepend_before_transition(options={}, &block)
+      #
+      # Prepend a callback before transition, making it the first before transition called.
+      # Options are the same as for the standard #before_transition method.
+
+      ##
+      # @!method skip_before_transition
+      #
+      # :call-seq: skip_before_transition(names)
+      #
+      # Skip a callback before transition.
+      # Options are the same as for the standard #before_transition method.
+
+      ##
+      # @!method after_transition
+      #
+      # :call-seq:
+      #   after_transition(*instance_method_names, options={})
+      #   after_transition(options={}, &block)
+      #
+      # Append a callback after transition.
+      # Instance methods used for `before` and `after` transitions
+      # receive no parameters.  Instance methods for `around` transitions will be given a block,
+      # which must be yielded/called in order for the sequence to continue.
+      #
+      # Using a block notation, the first parameter will be an instance of the object
+      # under transition, while the second parameter (`around` transition only) will be
+      # the block which should be called for the sequence to continue.
+      #
+      # == Transition Metadata
+      #
+      # Within the callback you can access the `transition_context` instance variable,
+      # which will give you metadata and arguments passed to the transition.
+      # See Workflow::TransitionContext
+      #
+      # == Options
+      #
+      # === If / Unless
+      #
+      # The callback will run `if` or `unless` the named method returns a truthy value.
+      #
+      #    #  Assuming some_instance_method returns a boolean,
+      #    after_transition :do_something, if: :some_instance_method
+      #    after_transition :do_something_else, unless: :some_instance_method
+      #
+      # === Only / Except
+      #
+      # The callback will run `if` or `unless` the event being processed is in the list given
+      #
+      #     #  Run this callback only on the `accept` and `publish` events.
+      #     after_transition :do_something, only: [:accept, :publish]
+      #     #  Run this callback on events other than the `accept` and `publish` events.
+      #     after_transition :do_something_else, except: [:accept, :publish]
+      #
+
+      ##
+      # @!method prepend_after_transition(*instance_method_names, options={})
+      #
+      # Something Interesting
+      #
+      # @overload prepend_after_transition(options={}, &block)
+      #
+      # Prepend a callback after transition, making it the first after transition called.
+      # Options are the same as for the standard #after_transition method.
+
+      ##
+      # @!method skip_after_transition
+      #
+      # :call-seq: skip_after_transition(names)
+      #
+      # Skip a callback after transition.
+      # Options are the same as for the standard #after_transition method.
+
+      ##
+      # @!method around_transition
+      #
+      # :call-seq:
+      #   around_transition(*instance_method_names, options={})
+      #   around_transition(options={}, &block)
+      #
+      # Append a callback around transition.
+      # Instance methods used for `before` and `after` transitions
+      # receive no parameters.  Instance methods for `around` transitions will be given a block,
+      # which must be yielded/called in order for the sequence to continue.
+      #
+      # Using a block notation, the first parameter will be an instance of the object
+      # under transition, while the second parameter (`around` transition only) will be
+      # the block which should be called for the sequence to continue.
+      #
+      # == Transition Metadata
+      #
+      # Within the callback you can access the `transition_context` instance variable,
+      # which will give you metadata and arguments passed to the transition.
+      # See Workflow::TransitionContext
+      #
+      # == Options
+      #
+      # === If / Unless
+      #
+      # The callback will run `if` or `unless` the named method returns a truthy value.
+      #
+      #    #  Assuming some_instance_method returns a boolean,
+      #    around_transition :do_something, if: :some_instance_method
+      #    around_transition :do_something_else, unless: :some_instance_method
+      #
+      # === Only / Except
+      #
+      # The callback will run `if` or `unless` the event being processed is in the list given
+      #
+      #     #  Run this callback only on the `accept` and `publish` events.
+      #     around_transition :do_something, only: [:accept, :publish]
+      #     #  Run this callback on events other than the `accept` and `publish` events.
+      #     around_transition :do_something_else, except: [:accept, :publish]
+      #
+
+      ##
+      # @!method prepend_around_transition(*instance_method_names, options={})
+      #
+      # Something Interesting
+      #
+      # @overload prepend_around_transition(options={}, &block)
+      #
+      # Prepend a callback around transition, making it the first around transition called.
+      # Options are the same as for the standard #around_transition method.
+
+      ##
+      # @!method skip_around_transition
+      #
+      # :call-seq: skip_around_transition(names)
+      #
+      # Skip a callback around transition.
+      # Options are the same as for the standard #around_transition method.
+
+      [:before, :after, :around].each do |callback|
+        CALLBACK_MAP.each do |type, context_attribute|
+          define_method "#{callback}_#{type}" do |*names, &blk|
+            _insert_callbacks(names, context_attribute, blk) do |name, options|
+              set_callback(type, callback, name, options)
+            end
+          end
+
+          define_method "prepend_#{callback}_#{type}" do |*names, &blk|
+            _insert_callbacks(names, context_attribute, blk) do |name, options|
+              set_callback(type, callback, name, options.merge(prepend: true))
+            end
+          end
+
+          # Skip a before, after or around callback. See _insert_callbacks
+          # for details on the allowed parameters.
+          define_method "skip_#{callback}_#{type}" do |*names|
+            _insert_callbacks(names, context_attribute) do |name, options|
+              skip_callback(type, callback, name, options)
+            end
+          end
+
+          # *_action is the same as append_*_action
+          alias_method :"append_#{callback}_#{type}", :"#{callback}_#{type}"
+        end
+      end
+
+      private
+      def _insert_callbacks(callbacks, context_attribute, block = nil)
+        options = callbacks.extract_options!
+        _normalize_callback_options(options, context_attribute)
+        callbacks.push(block) if block
+        callbacks.each do |callback|
+          yield callback, options
+        end
+      end
+
+      def _normalize_callback_options(options, context_attribute)
+        _normalize_callback_option(options, context_attribute, :only, :if)
+        _normalize_callback_option(options, context_attribute, :except, :unless)
+      end
+
+      def _normalize_callback_option(options, context_attribute, from, to) # :nodoc:
+        if from = options[from]
+          _from = Array(from).map(&:to_sym).to_set
+          from = proc { |record|
+            _from.include? record.transition_context.send(context_attribute).to_sym
+          }
+          options[to] = Array(options[to]).unshift(from)
+        end
+      end
+    end
+
+    private
+    #  TODO: Do something here.
+    def halted_callback_hook(filter)
+    end
+
+    def run_all_callbacks(&block)
+      catch(:abort) do
+        run_callbacks :transition do
+          throw(:abort) if false == run_callbacks(:exit) do
+            throw(:abort) if false == run_callbacks(:enter, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/workflow/configuration.rb

@@ -0,0 +1,10 @@
+module Workflow
+  class Configuration
+    attr_accessor :persist_workflow_state_immediately, :touch_on_update_column
+
+    def initialize
+      self.persist_workflow_state_immediately = true
+      self.touch_on_update_column = false
+    end
+  end
+end

data/lib/workflow/draw.rb

@@ -0,0 +1,79 @@
+begin
+  require 'rubygems'
+
+  gem 'ruby-graphviz', '~> 1.0.0'
+  gem 'activesupport'
+
+  require 'graphviz'
+  require 'active_support/inflector'
+rescue LoadError => e
+  $stderr.puts "Could not load the ruby-graphiz or active_support gems for rendering: #{e.message}"
+end
+
+module Workflow
+  module Draw
+
+    # Generates a `dot` graph of the workflow.
+    # Prerequisite: the `dot` binary. (Download from http://www.graphviz.org/)
+    # You can use this method in your own Rakefile like this:
+    #
+    #     namespace :doc do
+    #       desc "Generate a workflow graph for a model passed e.g. as 'MODEL=Order'."
+    #       task :workflow => :environment do
+    #         require 'workflow/draw'
+    #         Workflow::Draw::workflow_diagram(ENV['MODEL'].constantize)
+    #       end
+    #     end
+    #
+    # You can influence the placement of nodes by specifying
+    # additional meta information in your states and transition descriptions.
+    # You can assign higher `weight` value to the typical transitions
+    # in your workflow. All other states and transitions will be arranged
+    # around that main line. See also `weight` in the graphviz documentation.
+    # Example:
+    #
+    #     state :new do
+    #       event :approve, :transitions_to => :approved, :meta => {:weight => 8}
+    #     end
+    #
+    #
+    # @param klass A class with the Workflow mixin, for which you wish the graphical workflow representation
+    # @param [String] target_dir Directory, where to save the dot and the pdf files
+    # @param [String] graph_options You can change graph orientation, size etc. See graphviz documentation
+    def self.workflow_diagram(klass, options={})
+      options = {
+        :name => "#{klass.name.tableize}_workflow".gsub('/', '_'),
+        :path => '.',
+        :orientation => "landscape",
+        :ratio => "fill",
+        :format => 'png',
+        :font => 'Helvetica'
+        }.merge options
+
+        graph = ::GraphViz.new('G', :rankdir => options[:orientation] == 'landscape' ? 'LR' : 'TB', :ratio => options[:ratio])
+
+      # Add nodes
+      klass.workflow_spec.states.each do |_, state|
+        node = state.draw(graph)
+        node.fontname = options[:font]
+
+        state.uniq_events.each do |event|
+          edge = event.draw(graph, state)
+          edge.fontname = options[:font]
+        end
+      end
+
+      # Generate the graph
+      filename = File.join(options[:path], "#{options[:name]}.#{options[:format]}")
+
+      graph.output options[:format] => "'#{filename}'"
+
+      puts "
+      Please run the following to open the generated file:
+
+      open '#{filename}'
+      "
+      graph
+    end
+  end
+end