Module: Workflow::Transitions

Extended by:
ActiveSupport::Concern
Included in:
Workflow
Defined in:
lib/workflow/transitions.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#halted_because ⇒ String (readonly)

Returns the reason given to a call to #halt or #halt!, if any.

Returns:

  • (String) —

    The reason the transition was aborted.



62
63
64
 
# File 'lib/workflow/transitions.rb', line 62

def halted_because
  @halted_because
end

#transition_context ⇒ Workflow::TransitionContext (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

During a state transition, contains transition-specific information:

  • The name of the State being exited,
  • The name of the State being entered,
  • The name of the Event that was fired,
  • And whatever arguments were passed to the Workflow#transition! method.

Returns:



14
15
16
 
# File 'lib/workflow/transitions.rb', line 14

included do
  attr_reader :transition_context
end

Instance Method Details

#halt(reason = nil) ⇒ nil

Stop the current transition and set the reason for the abort.

Parameters:

  • reason (String) (defaults to: nil) —

    Optional reason for halting transition.

Returns:

  • (nil) 


38
39
40
41
42
 
# File 'lib/workflow/transitions.rb', line 38

def halt(reason = nil)
  @halted_because = reason
  @halted = true
  throw :abort
end

#halt!(reason = nil) ⇒ nil

Sets halt reason and raises [TransitionHaltedError] error.

Parameters:

  • reason (String) (defaults to: nil) —

    Optional reason for halting

Returns:

  • (nil)

Raises:



48
49
50
51
52
 
# File 'lib/workflow/transitions.rb', line 48

def halt!(reason = nil)
  @halted_because = reason
  @halted = true
  raise Errors::TransitionHaltedError, reason
end

#halted? ⇒ Boolean

Deprecated. Check for false return value from #transition!

Returns:

  • (Boolean) —

    true if the last transition was halted by one of the transition callbacks.



56
57
58
 
# File 'lib/workflow/transitions.rb', line 56

def halted?
  @halted
end

#load_workflow_state ⇒ Object

load_workflow_state and persist_workflow_state can be overriden to handle the persistence of the workflow state.

Default (non ActiveRecord) implementation stores the current state in a variable.

Default ActiveRecord implementation uses a 'workflow_state' database column.



71
72
73
 
# File 'lib/workflow/transitions.rb', line 71

def load_workflow_state
  @workflow_state if instance_variable_defined? :@workflow_state
end

#persist_workflow_state(new_value) ⇒ Object 



75
76
77
 
# File 'lib/workflow/transitions.rb', line 75

def persist_workflow_state(new_value)
  @workflow_state = new_value
end

#prepare_transition(name, args, attributes) ⇒ Object

Raises:



79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/workflow/transitions.rb', line 79

def prepare_transition(name, args, attributes)
  event = current_state.find_event(name.to_sym)
  raise Errors::NoTransitionAllowed.new(current_state, name) unless event

  target = event.evaluate(self)

  TransitionContext.new \
    from: current_state.name,
    to: target.name,
    event: event.name,
    event_args: args,
    attributes: attributes,
    named_arguments: workflow_spec.named_arguments
end

#transition!(name, *args, **attributes) ⇒ Symbol

Initiates state transition via the named event

TODO: connect args to documentation on how arguments are accessed during state transitions.

Parameters:

  • name (Symbol) —

    name of event to initiate

  • args (Array) —

    State transition arguments.

Returns:

  • (Symbol) —

    The name of the new state, or false if the transition failed.



24
25
26
27
28
29
30
31
32
 
# File 'lib/workflow/transitions.rb', line 24

def transition!(name, *args, **attributes)
  @transition_context = prepare_transition(name, args, attributes)

  run_all_callbacks do
    persist_workflow_state(@transition_context.to)
  end
ensure
  @transition_context = nil
end