Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Update README to include a topic on explicit vs. implicit event trans…

…itions. Closes #225
  • Loading branch information...
commit c6776195f986eb5c885f24c7efccfb471214f91a 1 parent a0fcab0
@obrie obrie authored
Showing with 50 additions and 0 deletions.
  1. +1 −0  CHANGELOG.md
  2. +49 −0 README.md
View
1  CHANGELOG.md
@@ -1,5 +1,6 @@
# master
+* Update README to include a topic on explicit vs. implicit event transitions [Nathan Long]
* Fix around_transition pausing not being marked as unsupported for rubinius [Daniel Huckstep]
* Fix all / any / same matchers not being able to be used in :from / :to options in transitions and callbacks
* Fix ActiveModel locale paths not being loaded properly under certain JRuby environments [Brad Heller]
View
49 README.md
@@ -637,6 +637,55 @@ machines, see `StateMachine::Integrations::Sequel`.
## Additional Topics
+### Explicit vs. Implicit Event Transitions
+
+Every event defined for a state machine generates an instance method on the
+class that allows the event to be explicitly triggered. Most of the examples in
+the state_machine documentation use this technique. However, with some types of
+integrations, like ActiveRecord, you can also *implicitly* fire events by
+setting a special attribute on the instance.
+
+Suppose you're using the ActiveRecord integration and the following model is
+defined:
+
+```ruby
+class Vehicle < ActiveRecord::Base
+ state_machine :initial => :parked do
+ event :ignite do
+ transition :parked => :idling
+ end
+ end
+end
+```
+
+To trigger the `ignite` event, you would typically call the `Vehicle#ignite`
+method like so:
+
+```ruby
+vehicle = Vehicle.create # => #<Vehicle id=1 state="parked" alarm_state="active">
+vehicle.ignite # => true
+vehicle.state # => "idling"
+```
+
+This is referred to as an *explicit* event transition. The same behavior can
+also be achieved *implicitly* by setting the state event attribute and invoking
+the action associated with the state machine. For example:
+
+```ruby
+vehicle = Vehicle.create # => #<Vehicle id=1 state="parked" alarm_state="active">
+vehicle.state_event = "ignite" # => "ignite"
+vehicle.save # => true
+vehicle.state # => "idling"
+vehicle.state_event # => nil
+```
+
+As you can see, the `ignite` event was automatically triggered when the `save`
+action was called. This is particularly useful if you want to allow users to
+drive the state transitions from a web API.
+
+See each integration's API documentation for more information on the implicit
+approach.
+
### Symbols vs. Strings
In all of the examples used throughout the documentation, you'll notice that
Please sign in to comment.
Something went wrong with that request. Please try again.