Module: StateMachine::Integrations::DataMapper::Observer

Includes:
MatcherHelpers
Defined in:
lib/state_machine/integrations/data_mapper/observer.rb

Overview

Adds support for creating before/after transition callbacks within a DataMapper observer. These callbacks behave very similarly to before/after hooks during save/update/destroy/etc., but with the following modifications:

  • Each callback can define a set of transition conditions (i.e. guards) that must be met in order for the callback to get invoked.
  • An additional transition parameter is available that provides contextual information about the event (see StateMachine::Transition for more information)

To define a single observer for multiple state machines:

class StateMachineObserver
include DataMapper::Observer

observe Vehicle, Switch, Project

after_transition do |transition, saved|
  Audit.log(self, transition) if saved
end
end

Requirements

To use this feature of the DataMapper integration, the dm-observer library must be available. This can be installed either directly or indirectly through dm-more. When loading DataMapper, be sure to load the dm-observer library as well like so:

require 'rubygems'
require 'dm-core'
require 'dm-observer'

If dm-observer is not available, then this feature will be skipped.

Instance Method Summary collapse

Methods included from MatcherHelpers

#all, #same

Instance Method Details

#after_transition(*args, &block) ⇒ Object

Creates a callback that will be invoked after a transition is performed, so long as the given configuration options match the transition. Each part of the transition (event, to state, from state) must match in order for the callback to get invoked.

See StateMachine::Machine#after_transition for more information about the various configuration options available.

Examples

class Vehicle
include DataMapper::Resource

property :id, Serial
property :state, :String

state_machine :initial => :parked do
  event :ignite do
    transition :parked => :idling
  end
end
end

class VehicleObserver
include DataMapper::Observer

observe Vehicle

after :save do |saved|
  # log message
end

# Target all state machines
after_transition :parked => :idling, :on => :ignite do
  # put on seatbelt
end

# Target a specific state machine
after_transition :state, any => :idling do
  # put on seatbelt
end

# Target all state machines without requirements
after_transition do |transition, saved|
  if saved
    # log message
  end
end
end

Note that in each of the above before_transition callbacks, the callback is executed within the context of the object (i.e. the Vehicle instance being transition). This means that self refers to the vehicle record within each callback block.



152
153
154
 
# File 'lib/state_machine/integrations/data_mapper/observer.rb', line 152

def after_transition(*args, &block)
  add_transition_callback(:after, *args, &block)
end

#before_transition(*args, &block) ⇒ Object

Creates a callback that will be invoked before a transition is performed, so long as the given configuration options match the transition. Each part of the transition (event, to state, from state) must match in order for the callback to get invoked.

See StateMachine::Machine#before_transition for more information about the various configuration options available.

Examples

class Vehicle
include DataMapper::Resource

property :id, Serial
property :state, :String

state_machine :initial => :parked do
  event :ignite do
    transition :parked => :idling
  end
end
end

class VehicleObserver
include DataMapper::Observer

observe Vehicle

before :save do
  # log message
end

# Target all state machines
before_transition :parked => :idling, :on => :ignite do
  # put on seatbelt
end

# Target a specific state machine
before_transition :state, any => :idling do
  # put on seatbelt
end

# Target all state machines without requirements
before_transition do |transition|
  # log message
end
end

Note that in each of the above before_transition callbacks, the callback is executed within the context of the object (i.e. the Vehicle instance being transition). This means that self refers to the vehicle record within each callback block.



94
95
96
 
# File 'lib/state_machine/integrations/data_mapper/observer.rb', line 94

def before_transition(*args, &block)
  add_transition_callback(:before, *args, &block)
end