### Home Classes Methods

### In Files

- lib/state_machine/callback.rb

### Parent

Object

### Methods

- ::new
- #call
- #known_states

### Included Modules

- StateMachine::EvalHelpers

### Files

- LICENSE

### Class/Module Index

Quicksearch

- StateMachine
- StateMachine::AllMatcher
- StateMachine::Assertions
- StateMachine::AttributeTransitionCollection
- StateMachine::BlacklistMatcher
- StateMachine::Branch
- StateMachine::Callback
- StateMachine::ClassMethods
- StateMachine::Error
- StateMachine::EvalHelpers
- StateMachine::Event
- StateMachine::EventCollection
- StateMachine::Graph
- StateMachine::InstanceMethods
- StateMachine::IntegrationNotFound
- StateMachine::Integrations
- StateMachine::Integrations::ActiveModel
- StateMachine::Integrations::ActiveModel::Observer
- StateMachine::Integrations::ActiveModel::ObserverUpdate
- StateMachine::Integrations::ActiveRecord
- StateMachine::Integrations::Base
- StateMachine::Integrations::Base::ClassMethods
- StateMachine::Integrations::DataMapper
- StateMachine::Integrations::DataMapper::Observer
- StateMachine::Integrations::MongoMapper
- StateMachine::Integrations::Mongoid
- StateMachine::Integrations::Sequel
- StateMachine::InvalidEvent
- StateMachine::InvalidParallelTransition
- StateMachine::InvalidTransition
- StateMachine::LoopbackMatcher
- StateMachine::Machine
- StateMachine::MachineCollection
- StateMachine::MacroMethods
- StateMachine::Matcher
- StateMachine::MatcherHelpers
- StateMachine::NodeCollection
- StateMachine::Path
- StateMachine::PathCollection
- StateMachine::RailsEngine
- StateMachine::State
- StateMachine::StateCollection
- StateMachine::StateContext
- StateMachine::Transition
- StateMachine::TransitionCollection
- StateMachine::WhitelistMatcher
- StateMachine::YARD
- StateMachine::YARD::Handlers
- StateMachine::YARD::Handlers::Base
- StateMachine::YARD::Handlers::Event
- StateMachine::YARD::Handlers::Machine
- StateMachine::YARD::Handlers::State
- StateMachine::YARD::Handlers::Transition
- Object

No matching classes.

# StateMachine::Callback

Callbacks represent hooks into objects that allow logic to be triggered before, after, or around a specific set of transitions.

### Attributes

bind_to_object[RW]

Determines whether to automatically bind the callback to the object being transitioned. This only applies to callbacks that are defined as lambda blocks (or Procs). Some integrations, such as DataMapper, handle callbacks by executing them bound to the object involved, while other integrations, such as ActiveRecord, pass the object as an argument to the callback. This can be configured on an application-wide basis by setting this configuration to `true` or `false`. The default value is `false`.

Note that the DataMapper and Sequel integrations automatically configure this value on a per-callback basis, so it does not have to be enabled application-wide.

## Examples

When not bound to the object:

    class Vehicle
      state_machine do
        before_transition do |vehicle|
          vehicle.set_alarm
        end
      end

      def set_alarm
        ...
      end
    end

When bound to the object:

    StateMachine::Callback.bind_to_object = true

    class Vehicle
      state_machine do
        before_transition do
          self.set_alarm
        end
      end

      def set_alarm
        ...
      end
    end

terminator[RW]

The application-wide terminator to use for callbacks when not explicitly defined. Terminators determine whether to cancel a callback chain based on the return value of the callback.

See StateMachine::Callback#terminator for more information.

branch[R]

The branch that determines whether or not this callback can be invoked based on the context of the transition. The event, from state, and to state must all match in order for the branch to pass.

See StateMachine::Branch for more information.

terminator[R]

An optional block for determining whether to cancel the callback chain based on the return value of the callback. By default, the callback chain never cancels based on the return value (i.e. there is no implicit terminator). Certain integrations, such as ActiveRecord and Sequel, change this default value.

## Examples

Canceling the callback chain without a terminator:

    class Vehicle
      state_machine do
        before_transition do |vehicle|
          throw :halt
        end
      end
    end

Canceling the callback chain with a terminator value of `false`:

    class Vehicle
      state_machine do
        before_transition do |vehicle|
          false
        end
      end
    end

type[RW]

The type of callback chain this callback is for. This can be one of the following:

- `before`

- `after`

- `around`

- `failure`

### Public Class Methods

new(type, *args, &block) click to toggle source

Creates a new callback that can get called based on the configured options.

In addition to the possible configuration options for branches, the following options can be configured:

- `:bind_to_object` - Whether to bind the callback to the object involved. If set to false, the object will be passed as a parameter instead. Default is integration-specific or set to the application default.

- `:terminator` - A block/proc that determines what callback results should cause the callback chain to halt (if not using the default `throw :halt` technique).

More information about how those options affect the behavior of the callback can be found in their attribute definitions.

    # File lib/state_machine/callback.rb, line 123
    def initialize(type, *args, &block)
      @type = type
      raise ArgumentError, 'Type must be :before, :after, :around, or :failure' unless [:before, :after, :around, :failure].include?(type)

      options = args.last.is_a?(Hash) ? args.pop : {}
      @methods = args
      @methods.concat(Array(options.delete(:do)))
      @methods << block if block_given?
      raise ArgumentError, 'Method(s) for callback must be specified' unless @methods.any?

      options = {:bind_to_object => self.class.bind_to_object, :terminator => self.class.terminator}.merge(options)

      # Proxy lambda blocks so that they're bound to the object
      bind_to_object = options.delete(:bind_to_object)
      @methods.map! do |method|
        bind_to_object && method.is_a?(Proc) ? bound_method(method) : method
      end

      @terminator = options.delete(:terminator)
      @branch = Branch.new(options)
    end

### Public Instance Methods

call(object, context = {}, *args, &block) click to toggle source

Runs the callback as long as the transition context matches the branch requirements configured for this callback. If a block is provided, it will be called when the last method has run.

If a terminator has been configured and it matches the result from the evaluated method, then the callback chain should be halted.

    # File lib/state_machine/callback.rb, line 157
    def call(object, context = {}, *args, &block)
      if @branch.matches?(object, context)
        run_methods(object, context, 0, *args, &block)
        true
      else
        false
      end
    end

known_states() click to toggle source

Gets a list of the states known to this callback by looking at the branch's known states

    # File lib/state_machine/callback.rb, line 147
    def known_states
      branch.known_states
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.