README.rdoc in transitions-0.1.5 vs README.rdoc in transitions-0.1.6
- old
+ new
@@ -42,11 +42,11 @@
transitions :to => :available, :from => [:out_of_stock], :guard => lambda { |product| product.in_stock > 0 }
end
end
end
-In this example we assume that you are in a rails project using Bundler, which would automitcally require `transitions`.
+In this example we assume that you are in a rails project using Bundler, which would automatically require `transitions`.
If this is not the case for you you have to add
require 'transitions'
whereever you load your dependencies in your application.
@@ -96,19 +96,32 @@
>> Order.create!
=> #<Order id: 3, state: "pick_line_items", description: nil, created_at: "2011-08-23 15:48:46", updated_at: "2011-08-23 15:48:46">
>> Order.pick_line_items
=> [#<Order id: 3, state: "pick_line_items", description: nil, created_at: "2011-08-23 15:48:46", updated_at: "2011-08-23 15:48:46">]
+==== Using <tt>guard</tt>
+
+Each event definition takes an optional "guard" argument, which acts as a predicate for the transition.
+You can pass in a Symbol, a String, or a Proc like this:
+
+ event :discontinue do
+ transitions :to => :discontinued, :from => [:available, :out_of_stock], :guard => :can_discontinue
+ end
+
+Any arguments passed to the event method will be passed on to the <tt>guard</tt> predicate.
+
==== Using <tt>on_transition</tt>
Each event definition takes an optional "on_transition" argument, which allows you to execute methods on transition.
You can pass in a Symbol, a String, a Proc or an Array containing method names as Symbol or String like this:
event :discontinue do
transitions :to => :discontinued, :from => [:available, :out_of_stock], :on_transition => [:do_discontinue, :notify_clerk]
end
+Any arguments passed to the event method will be passed on to the <tt>on_transition</tt> callback.
+
==== Using <tt>success</tt>
In case you need to trigger a method call after a successful transition you can use <tt>success</tt>:
event :discontinue, :success => :notfiy_admin do
@@ -120,10 +133,16 @@
event :discontinue, :success => lambda { |order| AdminNotifier.notify_about_discontinued_order(order) } do
transitions :to => :discontinued, :from => [:available, :out_of_stock]
end
+If you need it, you can even call multiple methods or lambdas just passing an array:
+
+ event :discontinue, :success => [:notify_admin, lambda { |order| AdminNotifier.notify_about_discontinued_order(order) }] do
+ transitions :to => :discontinued, :from => [:available, :out_of_stock]
+ end
+
==== Timestamps
If you'd like to note the time of a state change, Transitions comes with timestamps free!
To activate them, simply pass the :timestamp option to the event definition with a value of either true or
the name of the timestamp column.
@@ -163,9 +182,23 @@
==== Explicitly setting the initial state with the <tt>initial</tt> option
state_machine :initial => :closed do
state :open
state :closed
+ end
+
+=== Configuring a different column name with ActiveRecord
+
+To use a different column than <tt>state</tt> to track it's value simply do this:
+
+ class Product < ActiveRecord::Base
+ include Transitions
+
+ state_machine :attribute_name => :different_column do
+
+ ...
+
+ end
end
=== Documentation, Guides & Examples
- {Online API Documentation}[http://rdoc.info/github/troessner/transitions/master/Transitions]