StateMachine Gem

User Manual

Getting Started

1. Prepare your Model

Add a DB field to the model to store the state:

  # e.g. to create a new `Vehicle` model with a `state` field:  
  rails generate model Vehicle state:string
  rake db:migrate

Optional: Use StateMachine Rake task

To quickly generate state machines for any rails class:

rake state_machine:draw CLASS=Vehicle

2. Configure the State Machine for your Model

See all possible configurations are under API.

API

• state_machine
  • Initializing
  • Methods
  • Namespace
  • Dynamic Definition (Advanced)
• state
  • State-Aware Methods
  • Value
  • Symbol VS String Definition
• event
  • Methods
• transition
  • Explicit Vs. Implicit Transitions
  • Transactions
• Callbacks
  • before_transition
  • around_transition
  • after_failure
  • Observers
• Helpers

Testing

To run core test suite (does not contain integration tests):

bundle install
bundle exec rake test

To run integration tests:

bundle install
rake appraisal:install
rake appraisal:test

You can also test a specific version:

rake appraisal:active_model-3.0.0 test
rake appraisal:active_record-2.0.0 test

Automatic Documentation (YARD)

To enable YARD integration, add state_machine plugin to your ~/.yard/config:

load_plugins: true
autoload_plugins:
  - state_machine
  ...

Internationalization

In Rails 2.2`, any error message that is generated from performing invalid transitions can be localized. The following default translations are used:

  en:
    activerecord:
      errors:
        messages:
          invalid: "is invalid"
          # %{value} = attribute value, %{state} = Human state name
          invalid_event: "cannot transition when %{state}"
          # %{value} = attribute value, %{event} = Human event name, %{state} = Human current state name
          invalid_transition: "cannot transition via %{event}"

Notice that the interpolation syntax is %{key} in Rails 3`. In Rails 2.x, the appropriate syntax is .

You can override these for a specific model like so:

  en:
    activerecord:
      errors:
        models:
          user:
            invalid: "is not valid"

In addition to the above, you can also provide translations for the various states / events in each state machine. Using the Vehicle example, state translations will be looked for using the following keys, where model_name = "vehicle", machine_name = "state" and state_name = "parked":

• activerecord.state_machines.#{model_name}.#{machine_name}.states.#{state_name}
• activerecord.state_machines.#{model_name}.states.#{state_name}
• activerecord.state_machines.#{machine_name}.states.#{state_name}
• activerecord.state_machines.states.#{state_name}

Event translations will be looked for using the following keys, where model_name = "vehicle", machine_name = "state" and event_name = "ignite":

• activerecord.state_machines.#{model_name}.#{machine_name}.events.#{event_name}
• activerecord.state_machines.#{model_name}.events.#{event_name}
• activerecord.state_machines.#{machine_name}.events.#{event_name}
• activerecord.state_machines.events.#{event_name}

An example translation configuration might look like so:

  es:
    activerecord:
      state_machines:
        states:
          parked: 'estacionado'
        events:
          park: 'estacionarse'

Developer Manual

Good luck!