spree-state_machine 2.0.0.beta1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (140) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +8 -0
  3. data/.travis.yml +12 -0
  4. data/.yardopts +5 -0
  5. data/CHANGELOG.md +502 -0
  6. data/Gemfile +3 -0
  7. data/LICENSE +20 -0
  8. data/README.md +1246 -0
  9. data/Rakefile +20 -0
  10. data/examples/AutoShop_state.png +0 -0
  11. data/examples/Car_state.png +0 -0
  12. data/examples/Gemfile +5 -0
  13. data/examples/Gemfile.lock +14 -0
  14. data/examples/TrafficLight_state.png +0 -0
  15. data/examples/Vehicle_state.png +0 -0
  16. data/examples/auto_shop.rb +13 -0
  17. data/examples/car.rb +21 -0
  18. data/examples/doc/AutoShop.html +2856 -0
  19. data/examples/doc/AutoShop_state.png +0 -0
  20. data/examples/doc/Car.html +919 -0
  21. data/examples/doc/Car_state.png +0 -0
  22. data/examples/doc/TrafficLight.html +2230 -0
  23. data/examples/doc/TrafficLight_state.png +0 -0
  24. data/examples/doc/Vehicle.html +7921 -0
  25. data/examples/doc/Vehicle_state.png +0 -0
  26. data/examples/doc/_index.html +136 -0
  27. data/examples/doc/class_list.html +47 -0
  28. data/examples/doc/css/common.css +1 -0
  29. data/examples/doc/css/full_list.css +55 -0
  30. data/examples/doc/css/style.css +322 -0
  31. data/examples/doc/file_list.html +46 -0
  32. data/examples/doc/frames.html +13 -0
  33. data/examples/doc/index.html +136 -0
  34. data/examples/doc/js/app.js +205 -0
  35. data/examples/doc/js/full_list.js +173 -0
  36. data/examples/doc/js/jquery.js +16 -0
  37. data/examples/doc/method_list.html +734 -0
  38. data/examples/doc/top-level-namespace.html +105 -0
  39. data/examples/merb-rest/controller.rb +51 -0
  40. data/examples/merb-rest/model.rb +28 -0
  41. data/examples/merb-rest/view_edit.html.erb +24 -0
  42. data/examples/merb-rest/view_index.html.erb +23 -0
  43. data/examples/merb-rest/view_new.html.erb +13 -0
  44. data/examples/merb-rest/view_show.html.erb +17 -0
  45. data/examples/rails-rest/controller.rb +43 -0
  46. data/examples/rails-rest/migration.rb +7 -0
  47. data/examples/rails-rest/model.rb +23 -0
  48. data/examples/rails-rest/view__form.html.erb +34 -0
  49. data/examples/rails-rest/view_edit.html.erb +6 -0
  50. data/examples/rails-rest/view_index.html.erb +25 -0
  51. data/examples/rails-rest/view_new.html.erb +5 -0
  52. data/examples/rails-rest/view_show.html.erb +19 -0
  53. data/examples/traffic_light.rb +9 -0
  54. data/examples/vehicle.rb +33 -0
  55. data/lib/state_machine/assertions.rb +36 -0
  56. data/lib/state_machine/branch.rb +225 -0
  57. data/lib/state_machine/callback.rb +236 -0
  58. data/lib/state_machine/core.rb +7 -0
  59. data/lib/state_machine/core_ext/class/state_machine.rb +5 -0
  60. data/lib/state_machine/core_ext.rb +2 -0
  61. data/lib/state_machine/error.rb +13 -0
  62. data/lib/state_machine/eval_helpers.rb +87 -0
  63. data/lib/state_machine/event.rb +257 -0
  64. data/lib/state_machine/event_collection.rb +141 -0
  65. data/lib/state_machine/extensions.rb +149 -0
  66. data/lib/state_machine/graph.rb +92 -0
  67. data/lib/state_machine/helper_module.rb +17 -0
  68. data/lib/state_machine/initializers/rails.rb +25 -0
  69. data/lib/state_machine/initializers.rb +4 -0
  70. data/lib/state_machine/integrations/active_model/locale.rb +11 -0
  71. data/lib/state_machine/integrations/active_model/observer.rb +33 -0
  72. data/lib/state_machine/integrations/active_model/observer_update.rb +42 -0
  73. data/lib/state_machine/integrations/active_model/versions.rb +31 -0
  74. data/lib/state_machine/integrations/active_model.rb +585 -0
  75. data/lib/state_machine/integrations/active_record/locale.rb +20 -0
  76. data/lib/state_machine/integrations/active_record/versions.rb +123 -0
  77. data/lib/state_machine/integrations/active_record.rb +525 -0
  78. data/lib/state_machine/integrations/base.rb +100 -0
  79. data/lib/state_machine/integrations.rb +121 -0
  80. data/lib/state_machine/machine.rb +2287 -0
  81. data/lib/state_machine/machine_collection.rb +74 -0
  82. data/lib/state_machine/macro_methods.rb +522 -0
  83. data/lib/state_machine/matcher.rb +123 -0
  84. data/lib/state_machine/matcher_helpers.rb +54 -0
  85. data/lib/state_machine/node_collection.rb +222 -0
  86. data/lib/state_machine/path.rb +120 -0
  87. data/lib/state_machine/path_collection.rb +90 -0
  88. data/lib/state_machine/state.rb +297 -0
  89. data/lib/state_machine/state_collection.rb +112 -0
  90. data/lib/state_machine/state_context.rb +138 -0
  91. data/lib/state_machine/transition.rb +470 -0
  92. data/lib/state_machine/transition_collection.rb +245 -0
  93. data/lib/state_machine/version.rb +3 -0
  94. data/lib/state_machine/yard/handlers/base.rb +32 -0
  95. data/lib/state_machine/yard/handlers/event.rb +25 -0
  96. data/lib/state_machine/yard/handlers/machine.rb +344 -0
  97. data/lib/state_machine/yard/handlers/state.rb +25 -0
  98. data/lib/state_machine/yard/handlers/transition.rb +47 -0
  99. data/lib/state_machine/yard/handlers.rb +12 -0
  100. data/lib/state_machine/yard/templates/default/class/html/setup.rb +30 -0
  101. data/lib/state_machine/yard/templates/default/class/html/state_machines.erb +12 -0
  102. data/lib/state_machine/yard/templates.rb +3 -0
  103. data/lib/state_machine/yard.rb +8 -0
  104. data/lib/state_machine.rb +8 -0
  105. data/lib/yard-state_machine.rb +2 -0
  106. data/state_machine.gemspec +22 -0
  107. data/test/files/en.yml +17 -0
  108. data/test/files/switch.rb +15 -0
  109. data/test/functional/state_machine_test.rb +1066 -0
  110. data/test/test_helper.rb +7 -0
  111. data/test/unit/assertions_test.rb +40 -0
  112. data/test/unit/branch_test.rb +969 -0
  113. data/test/unit/callback_test.rb +704 -0
  114. data/test/unit/error_test.rb +43 -0
  115. data/test/unit/eval_helpers_test.rb +270 -0
  116. data/test/unit/event_collection_test.rb +398 -0
  117. data/test/unit/event_test.rb +1196 -0
  118. data/test/unit/graph_test.rb +98 -0
  119. data/test/unit/helper_module_test.rb +17 -0
  120. data/test/unit/integrations/active_model_test.rb +1245 -0
  121. data/test/unit/integrations/active_record_test.rb +2551 -0
  122. data/test/unit/integrations/base_test.rb +104 -0
  123. data/test/unit/integrations_test.rb +71 -0
  124. data/test/unit/invalid_event_test.rb +20 -0
  125. data/test/unit/invalid_parallel_transition_test.rb +18 -0
  126. data/test/unit/invalid_transition_test.rb +115 -0
  127. data/test/unit/machine_collection_test.rb +603 -0
  128. data/test/unit/machine_test.rb +3395 -0
  129. data/test/unit/matcher_helpers_test.rb +37 -0
  130. data/test/unit/matcher_test.rb +155 -0
  131. data/test/unit/node_collection_test.rb +362 -0
  132. data/test/unit/path_collection_test.rb +266 -0
  133. data/test/unit/path_test.rb +485 -0
  134. data/test/unit/state_collection_test.rb +352 -0
  135. data/test/unit/state_context_test.rb +441 -0
  136. data/test/unit/state_machine_test.rb +31 -0
  137. data/test/unit/state_test.rb +1101 -0
  138. data/test/unit/transition_collection_test.rb +2168 -0
  139. data/test/unit/transition_test.rb +1558 -0
  140. metadata +264 -0
@@ -0,0 +1,123 @@
1
+ module StateMachine
2
+ module Integrations #:nodoc:
3
+ module ActiveRecord
4
+ version '2.x - 3.0.x' do
5
+ def self.active?
6
+ ::ActiveRecord::VERSION::MAJOR == 2 || ::ActiveRecord::VERSION::MAJOR == 3 && ::ActiveRecord::VERSION::MINOR == 0
7
+ end
8
+
9
+ def define_static_state_initializer
10
+ define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
11
+ def attributes_from_column_definition(*)
12
+ result = super
13
+ self.class.state_machines.initialize_states(self, :static => :force, :dynamic => false, :to => result)
14
+ result
15
+ end
16
+ end_eval
17
+ end
18
+ end
19
+
20
+ version '2.x' do
21
+ def self.active?
22
+ ::ActiveRecord::VERSION::MAJOR == 2
23
+ end
24
+
25
+ def load_locale
26
+ super if defined?(I18n)
27
+ end
28
+
29
+ def create_scope(name, scope)
30
+ if owner_class.respond_to?(:named_scope)
31
+ name = name.to_sym
32
+ machine_name = self.name
33
+
34
+ # Since ActiveRecord does not allow direct access to the model
35
+ # being used within the evaluation of a dynamic named scope, the
36
+ # scope must be generated manually. It's necessary to have access
37
+ # to the model so that the state names can be translated to their
38
+ # associated values and so that inheritance is respected properly.
39
+ owner_class.named_scope(name)
40
+ owner_class.scopes[name] = lambda do |model, *states|
41
+ machine_states = model.state_machine(machine_name).states
42
+ values = states.flatten.map {|state| machine_states.fetch(state).value}
43
+
44
+ ::ActiveRecord::NamedScope::Scope.new(model, :conditions => scope.call(values))
45
+ end
46
+ end
47
+
48
+ # Prevent the Machine class from wrapping the scope
49
+ false
50
+ end
51
+
52
+ def invalidate(object, attribute, message, values = [])
53
+ if defined?(I18n)
54
+ super
55
+ else
56
+ object.errors.add(self.attribute(attribute), generate_message(message, values))
57
+ end
58
+ end
59
+
60
+ def translate(klass, key, value)
61
+ if defined?(I18n)
62
+ super
63
+ else
64
+ value ? value.to_s.humanize.downcase : 'nil'
65
+ end
66
+ end
67
+
68
+ def supports_observers?
69
+ true
70
+ end
71
+
72
+ def supports_validations?
73
+ true
74
+ end
75
+
76
+ def supports_mass_assignment_security?
77
+ true
78
+ end
79
+
80
+ def i18n_scope(klass)
81
+ :activerecord
82
+ end
83
+
84
+ def load_observer_extensions
85
+ super
86
+ ::ActiveRecord::Observer.class_eval do
87
+ include StateMachine::Integrations::ActiveModel::Observer
88
+ end unless ::ActiveRecord::Observer < StateMachine::Integrations::ActiveModel::Observer
89
+ end
90
+ end
91
+
92
+ version '2.0 - 2.2.x' do
93
+ def self.active?
94
+ ::ActiveRecord::VERSION::MAJOR == 2 && ::ActiveRecord::VERSION::MINOR < 3
95
+ end
96
+
97
+ def default_error_message_options(object, attribute, message)
98
+ {:default => @messages[message]}
99
+ end
100
+ end
101
+
102
+ version '2.0 - 2.3.1' do
103
+ def self.active?
104
+ ::ActiveRecord::VERSION::MAJOR == 2 && (::ActiveRecord::VERSION::MINOR < 3 || ::ActiveRecord::VERSION::TINY < 2)
105
+ end
106
+
107
+ def ancestors_for(klass)
108
+ klass.self_and_descendents_from_active_record
109
+ end
110
+ end
111
+
112
+ version '2.3.2 - 2.3.x' do
113
+ def self.active?
114
+ ::ActiveRecord::VERSION::MAJOR == 2 && ::ActiveRecord::VERSION::MINOR == 3 && ::ActiveRecord::VERSION::TINY >= 2
115
+ end
116
+
117
+ def ancestors_for(klass)
118
+ klass.self_and_descendants_from_active_record
119
+ end
120
+ end
121
+ end
122
+ end
123
+ end
@@ -0,0 +1,525 @@
1
+ require 'state_machine/integrations/active_model'
2
+
3
+ module StateMachine
4
+ module Integrations #:nodoc:
5
+ # Adds support for integrating state machines with ActiveRecord models.
6
+ #
7
+ # == Examples
8
+ #
9
+ # Below is an example of a simple state machine defined within an
10
+ # ActiveRecord model:
11
+ #
12
+ # class Vehicle < ActiveRecord::Base
13
+ # state_machine :initial => :parked do
14
+ # event :ignite do
15
+ # transition :parked => :idling
16
+ # end
17
+ # end
18
+ # end
19
+ #
20
+ # The examples in the sections below will use the above class as a
21
+ # reference.
22
+ #
23
+ # == Actions
24
+ #
25
+ # By default, the action that will be invoked when a state is transitioned
26
+ # is the +save+ action. This will cause the record to save the changes
27
+ # made to the state machine's attribute. *Note* that if any other changes
28
+ # were made to the record prior to transition, then those changes will
29
+ # be saved as well.
30
+ #
31
+ # For example,
32
+ #
33
+ # vehicle = Vehicle.create # => #<Vehicle id: 1, name: nil, state: "parked">
34
+ # vehicle.name = 'Ford Explorer'
35
+ # vehicle.ignite # => true
36
+ # vehicle.reload # => #<Vehicle id: 1, name: "Ford Explorer", state: "idling">
37
+ #
38
+ # == Events
39
+ #
40
+ # As described in StateMachine::InstanceMethods#state_machine, event
41
+ # attributes are created for every machine that allow transitions to be
42
+ # performed automatically when the object's action (in this case, :save)
43
+ # is called.
44
+ #
45
+ # In ActiveRecord, these automated events are run in the following order:
46
+ # * before validation - Run before callbacks and persist new states, then validate
47
+ # * before save - If validation was skipped, run before callbacks and persist new states, then save
48
+ # * after save - Run after callbacks
49
+ #
50
+ # For example,
51
+ #
52
+ # vehicle = Vehicle.create # => #<Vehicle id: 1, name: nil, state: "parked">
53
+ # vehicle.state_event # => nil
54
+ # vehicle.state_event = 'invalid'
55
+ # vehicle.valid? # => false
56
+ # vehicle.errors.full_messages # => ["State event is invalid"]
57
+ #
58
+ # vehicle.state_event = 'ignite'
59
+ # vehicle.valid? # => true
60
+ # vehicle.save # => true
61
+ # vehicle.state # => "idling"
62
+ # vehicle.state_event # => nil
63
+ #
64
+ # Note that this can also be done on a mass-assignment basis:
65
+ #
66
+ # vehicle = Vehicle.create(:state_event => 'ignite') # => #<Vehicle id: 1, name: nil, state: "idling">
67
+ # vehicle.state # => "idling"
68
+ #
69
+ # This technique is always used for transitioning states when the +save+
70
+ # action (which is the default) is configured for the machine.
71
+ #
72
+ # === Security implications
73
+ #
74
+ # Beware that public event attributes mean that events can be fired
75
+ # whenever mass-assignment is being used. If you want to prevent malicious
76
+ # users from tampering with events through URLs / forms, the attribute
77
+ # should be protected like so:
78
+ #
79
+ # class Vehicle < ActiveRecord::Base
80
+ # attr_protected :state_event
81
+ # # attr_accessible ... # Alternative technique
82
+ #
83
+ # state_machine do
84
+ # ...
85
+ # end
86
+ # end
87
+ #
88
+ # If you want to only have *some* events be able to fire via mass-assignment,
89
+ # you can build two state machines (one public and one protected) like so:
90
+ #
91
+ # class Vehicle < ActiveRecord::Base
92
+ # attr_protected :state_event # Prevent access to events in the first machine
93
+ #
94
+ # state_machine do
95
+ # # Define private events here
96
+ # end
97
+ #
98
+ # # Public machine targets the same state as the private machine
99
+ # state_machine :public_state, :attribute => :state do
100
+ # # Define public events here
101
+ # end
102
+ # end
103
+ #
104
+ # == Transactions
105
+ #
106
+ # In order to ensure that any changes made during transition callbacks
107
+ # are rolled back during a failed attempt, every transition is wrapped
108
+ # within a transaction.
109
+ #
110
+ # For example,
111
+ #
112
+ # class Message < ActiveRecord::Base
113
+ # end
114
+ #
115
+ # Vehicle.state_machine do
116
+ # before_transition do |vehicle, transition|
117
+ # Message.create(:content => transition.inspect)
118
+ # false
119
+ # end
120
+ # end
121
+ #
122
+ # vehicle = Vehicle.create # => #<Vehicle id: 1, name: nil, state: "parked">
123
+ # vehicle.ignite # => false
124
+ # Message.count # => 0
125
+ #
126
+ # *Note* that only before callbacks that halt the callback chain and
127
+ # failed attempts to save the record will result in the transaction being
128
+ # rolled back. If an after callback halts the chain, the previous result
129
+ # still applies and the transaction is *not* rolled back.
130
+ #
131
+ # To turn off transactions:
132
+ #
133
+ # class Vehicle < ActiveRecord::Base
134
+ # state_machine :initial => :parked, :use_transactions => false do
135
+ # ...
136
+ # end
137
+ # end
138
+ #
139
+ # == Validations
140
+ #
141
+ # As mentioned in StateMachine::Machine#state, you can define behaviors,
142
+ # like validations, that only execute for certain states. One *important*
143
+ # caveat here is that, due to a constraint in ActiveRecord's validation
144
+ # framework, custom validators will not work as expected when defined to run
145
+ # in multiple states. For example:
146
+ #
147
+ # class Vehicle < ActiveRecord::Base
148
+ # state_machine do
149
+ # ...
150
+ # state :first_gear, :second_gear do
151
+ # validate :speed_is_legal
152
+ # end
153
+ # end
154
+ # end
155
+ #
156
+ # In this case, the <tt>:speed_is_legal</tt> validation will only get run
157
+ # for the <tt>:second_gear</tt> state. To avoid this, you can define your
158
+ # custom validation like so:
159
+ #
160
+ # class Vehicle < ActiveRecord::Base
161
+ # state_machine do
162
+ # ...
163
+ # state :first_gear, :second_gear do
164
+ # validate {|vehicle| vehicle.speed_is_legal}
165
+ # end
166
+ # end
167
+ # end
168
+ #
169
+ # == Validation errors
170
+ #
171
+ # If an event fails to successfully fire because there are no matching
172
+ # transitions for the current record, a validation error is added to the
173
+ # record's state attribute to help in determining why it failed and for
174
+ # reporting via the UI.
175
+ #
176
+ # For example,
177
+ #
178
+ # vehicle = Vehicle.create(:state => 'idling') # => #<Vehicle id: 1, name: nil, state: "idling">
179
+ # vehicle.ignite # => false
180
+ # vehicle.errors.full_messages # => ["State cannot transition via \"ignite\""]
181
+ #
182
+ # If an event fails to fire because of a validation error on the record and
183
+ # *not* because a matching transition was not available, no error messages
184
+ # will be added to the state attribute.
185
+ #
186
+ # In addition, if you're using the <tt>ignite!</tt> version of the event,
187
+ # then the failure reason (such as the current validation errors) will be
188
+ # included in the exception that gets raised when the event fails. For
189
+ # example, assuming there's a validation on a field called +name+ on the class:
190
+ #
191
+ # vehicle = Vehicle.new
192
+ # vehicle.ignite! # => StateMachine::InvalidTransition: Cannot transition state via :ignite from :parked (Reason(s): Name cannot be blank)
193
+ #
194
+ # == Scopes
195
+ #
196
+ # To assist in filtering models with specific states, a series of named
197
+ # scopes are defined on the model for finding records with or without a
198
+ # particular set of states.
199
+ #
200
+ # These named scopes are essentially the functional equivalent of the
201
+ # following definitions:
202
+ #
203
+ # class Vehicle < ActiveRecord::Base
204
+ # named_scope :with_states, lambda {|*states| {:conditions => {:state => states}}}
205
+ # # with_states also aliased to with_state
206
+ #
207
+ # named_scope :without_states, lambda {|*states| {:conditions => ['state NOT IN (?)', states]}}
208
+ # # without_states also aliased to without_state
209
+ # end
210
+ #
211
+ # *Note*, however, that the states are converted to their stored values
212
+ # before being passed into the query.
213
+ #
214
+ # Because of the way named scopes work in ActiveRecord, they can be
215
+ # chained like so:
216
+ #
217
+ # Vehicle.with_state(:parked).all(:order => 'id DESC')
218
+ #
219
+ # Note that states can also be referenced by the string version of their
220
+ # name:
221
+ #
222
+ # Vehicle.with_state('parked')
223
+ #
224
+ # == Callbacks
225
+ #
226
+ # All before/after transition callbacks defined for ActiveRecord models
227
+ # behave in the same way that other ActiveRecord callbacks behave. The
228
+ # object involved in the transition is passed in as an argument.
229
+ #
230
+ # For example,
231
+ #
232
+ # class Vehicle < ActiveRecord::Base
233
+ # state_machine :initial => :parked do
234
+ # before_transition any => :idling do |vehicle|
235
+ # vehicle.put_on_seatbelt
236
+ # end
237
+ #
238
+ # before_transition do |vehicle, transition|
239
+ # # log message
240
+ # end
241
+ #
242
+ # event :ignite do
243
+ # transition :parked => :idling
244
+ # end
245
+ # end
246
+ #
247
+ # def put_on_seatbelt
248
+ # ...
249
+ # end
250
+ # end
251
+ #
252
+ # Note, also, that the transition can be accessed by simply defining
253
+ # additional arguments in the callback block.
254
+ #
255
+ # === Failure callbacks
256
+ #
257
+ # +after_failure+ callbacks allow you to execute behaviors when a transition
258
+ # is allowed, but fails to save. This could be useful for something like
259
+ # auditing transition attempts. Since callbacks run within transactions in
260
+ # ActiveRecord, a save failure will cause any records that get created in
261
+ # your callback to roll back. You can work around this issue like so:
262
+ #
263
+ # class TransitionLog < ActiveRecord::Base
264
+ # establish_connection Rails.env.to_sym
265
+ # end
266
+ #
267
+ # class Vehicle < ActiveRecord::Base
268
+ # state_machine do
269
+ # after_failure do |vehicle, transition|
270
+ # TransitionLog.create(:vehicle => vehicle, :transition => transition)
271
+ # end
272
+ #
273
+ # ...
274
+ # end
275
+ # end
276
+ #
277
+ # The +TransitionLog+ model establishes a second connection to the database
278
+ # that allows new records to be saved without being affected by rollbacks
279
+ # in the +Vehicle+ model's transaction.
280
+ #
281
+ # === Callback Order
282
+ #
283
+ # Callbacks occur in the following order. Callbacks specific to state_machine
284
+ # are bolded. The remaining callbacks are part of ActiveRecord.
285
+ #
286
+ # * (-) save
287
+ # * (-) begin transaction (if enabled)
288
+ # * (1) *before_transition*
289
+ # * (-) valid
290
+ # * (2) before_validation
291
+ # * (-) validate
292
+ # * (3) after_validation
293
+ # * (4) before_save
294
+ # * (5) before_create
295
+ # * (-) create
296
+ # * (6) after_create
297
+ # * (7) after_save
298
+ # * (8) *after_transition*
299
+ # * (-) end transaction (if enabled)
300
+ # * (9) after_commit
301
+ #
302
+ # == Observers
303
+ #
304
+ # In addition to support for ActiveRecord-like hooks, there is additional
305
+ # support for ActiveRecord observers. Because of the way ActiveRecord
306
+ # observers are designed, there is less flexibility around the specific
307
+ # transitions that can be hooked in. However, a large number of hooks
308
+ # *are* supported. For example, if a transition for a record's +state+
309
+ # attribute changes the state from +parked+ to +idling+ via the +ignite+
310
+ # event, the following observer methods are supported:
311
+ # * before/after/after_failure_to-_ignite_from_parked_to_idling
312
+ # * before/after/after_failure_to-_ignite_from_parked
313
+ # * before/after/after_failure_to-_ignite_to_idling
314
+ # * before/after/after_failure_to-_ignite
315
+ # * before/after/after_failure_to-_transition_state_from_parked_to_idling
316
+ # * before/after/after_failure_to-_transition_state_from_parked
317
+ # * before/after/after_failure_to-_transition_state_to_idling
318
+ # * before/after/after_failure_to-_transition_state
319
+ # * before/after/after_failure_to-_transition
320
+ #
321
+ # The following class shows an example of some of these hooks:
322
+ #
323
+ # class VehicleObserver < ActiveRecord::Observer
324
+ # def before_save(vehicle)
325
+ # # log message
326
+ # end
327
+ #
328
+ # # Callback for :ignite event *before* the transition is performed
329
+ # def before_ignite(vehicle, transition)
330
+ # # log message
331
+ # end
332
+ #
333
+ # # Callback for :ignite event *after* the transition has been performed
334
+ # def after_ignite(vehicle, transition)
335
+ # # put on seatbelt
336
+ # end
337
+ #
338
+ # # Generic transition callback *before* the transition is performed
339
+ # def after_transition(vehicle, transition)
340
+ # Audit.log(vehicle, transition)
341
+ # end
342
+ # end
343
+ #
344
+ # More flexible transition callbacks can be defined directly within the
345
+ # model as described in StateMachine::Machine#before_transition
346
+ # and StateMachine::Machine#after_transition.
347
+ #
348
+ # To define a single observer for multiple state machines:
349
+ #
350
+ # class StateMachineObserver < ActiveRecord::Observer
351
+ # observe Vehicle, Switch, Project
352
+ #
353
+ # def after_transition(record, transition)
354
+ # Audit.log(record, transition)
355
+ # end
356
+ # end
357
+ #
358
+ # == Internationalization
359
+ #
360
+ # In Rails 2.2+, any error message that is generated from performing invalid
361
+ # transitions can be localized. The following default translations are used:
362
+ #
363
+ # en:
364
+ # activerecord:
365
+ # errors:
366
+ # messages:
367
+ # invalid: "is invalid"
368
+ # # %{value} = attribute value, %{state} = Human state name
369
+ # invalid_event: "cannot transition when %{state}"
370
+ # # %{value} = attribute value, %{event} = Human event name, %{state} = Human current state name
371
+ # invalid_transition: "cannot transition via %{event}"
372
+ #
373
+ # Notice that the interpolation syntax is %{key} in Rails 3+. In Rails 2.x,
374
+ # the appropriate syntax is {{key}}.
375
+ #
376
+ # You can override these for a specific model like so:
377
+ #
378
+ # en:
379
+ # activerecord:
380
+ # errors:
381
+ # models:
382
+ # user:
383
+ # invalid: "is not valid"
384
+ #
385
+ # In addition to the above, you can also provide translations for the
386
+ # various states / events in each state machine. Using the Vehicle example,
387
+ # state translations will be looked for using the following keys, where
388
+ # +model_name+ = "vehicle", +machine_name+ = "state" and +state_name+ = "parked":
389
+ # * <tt>activerecord.state_machines.#{model_name}.#{machine_name}.states.#{state_name}</tt>
390
+ # * <tt>activerecord.state_machines.#{model_name}.states.#{state_name}</tt>
391
+ # * <tt>activerecord.state_machines.#{machine_name}.states.#{state_name}</tt>
392
+ # * <tt>activerecord.state_machines.states.#{state_name}</tt>
393
+ #
394
+ # Event translations will be looked for using the following keys, where
395
+ # +model_name+ = "vehicle", +machine_name+ = "state" and +event_name+ = "ignite":
396
+ # * <tt>activerecord.state_machines.#{model_name}.#{machine_name}.events.#{event_name}</tt>
397
+ # * <tt>activerecord.state_machines.#{model_name}.events.#{event_name}</tt>
398
+ # * <tt>activerecord.state_machines.#{machine_name}.events.#{event_name}</tt>
399
+ # * <tt>activerecord.state_machines.events.#{event_name}</tt>
400
+ #
401
+ # An example translation configuration might look like so:
402
+ #
403
+ # es:
404
+ # activerecord:
405
+ # state_machines:
406
+ # states:
407
+ # parked: 'estacionado'
408
+ # events:
409
+ # park: 'estacionarse'
410
+ module ActiveRecord
411
+ include Base
412
+ include ActiveModel
413
+
414
+ require 'state_machine/integrations/active_record/versions'
415
+
416
+ # The default options to use for state machines using this integration
417
+ @defaults = {:action => :save}
418
+
419
+ # Classes that inherit from ActiveRecord::Base will automatically use
420
+ # the ActiveRecord integration.
421
+ def self.matching_ancestors
422
+ %w(ActiveRecord::Base)
423
+ end
424
+
425
+ def self.extended(base) #:nodoc:
426
+ require 'active_record/version'
427
+ super
428
+ end
429
+
430
+ protected
431
+ # Only runs validations on the action if using <tt>:save</tt>
432
+ def runs_validations_on_action?
433
+ action == :save
434
+ end
435
+
436
+ # Gets the db default for the machine's attribute
437
+ def owner_class_attribute_default
438
+ if owner_class.connected? && owner_class.table_exists? && column = owner_class.columns_hash[attribute.to_s]
439
+ column.default
440
+ end
441
+ end
442
+
443
+ # Initializes dynamic states
444
+ def define_state_initializer
445
+ define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
446
+ def initialize(attributes = nil, options = {})
447
+ super(attributes, options) do |*args|
448
+ self.class.state_machines.initialize_states self
449
+ yield(*args) if block_given?
450
+ end
451
+ end
452
+ end_eval
453
+ end
454
+
455
+ # Uses around callbacks to run state events if using the :save hook
456
+ def define_action_hook
457
+ if action_hook == :save
458
+ define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
459
+ def save(*)
460
+ self.class.state_machine(#{name.inspect}).send(:around_save, self) { super }
461
+ end
462
+
463
+ def save!(*)
464
+ self.class.state_machine(#{name.inspect}).send(:around_save, self) { super } || raise(ActiveRecord::RecordInvalid.new(self))
465
+ end
466
+
467
+ def changed_for_autosave?
468
+ super || self.class.state_machines.any? {|name, machine| machine.action == :save && machine.read(self, :event)}
469
+ end
470
+ end_eval
471
+ else
472
+ super
473
+ end
474
+ end
475
+
476
+ # Runs state events around the machine's :save action
477
+ def around_save(object)
478
+ transaction(object) do
479
+ object.class.state_machines.transitions(object, action).perform { yield }
480
+ end
481
+ end
482
+
483
+ # Creates a scope for finding records *with* a particular state or
484
+ # states for the attribute
485
+ def create_with_scope(name)
486
+ create_scope(name, lambda {|values| ["#{attribute_column} IN (?)", values]})
487
+ end
488
+
489
+ # Creates a scope for finding records *without* a particular state or
490
+ # states for the attribute
491
+ def create_without_scope(name)
492
+ create_scope(name, lambda {|values| ["#{attribute_column} NOT IN (?)", values]})
493
+ end
494
+
495
+ # Generates the fully-qualifed column name for this machine's attribute
496
+ def attribute_column
497
+ connection = owner_class.connection
498
+ "#{connection.quote_table_name(owner_class.table_name)}.#{connection.quote_column_name(attribute)}"
499
+ end
500
+
501
+ # Runs a new database transaction, rolling back any changes by raising
502
+ # an ActiveRecord::Rollback exception if the yielded block fails
503
+ # (i.e. returns false).
504
+ def transaction(object)
505
+ result = nil
506
+ object.class.transaction do
507
+ raise ::ActiveRecord::Rollback unless result = yield
508
+ end
509
+ result
510
+ end
511
+
512
+ # Defines a new named scope with the given name
513
+ def create_scope(name, scope)
514
+ lambda {|model, values| model.where(scope.call(values))}
515
+ end
516
+
517
+ # ActiveModel's use of method_missing / respond_to for attribute methods
518
+ # breaks both ancestor lookups and defined?(super). Need to special-case
519
+ # the existence of query attribute methods.
520
+ def owner_class_ancestor_has_method?(scope, method)
521
+ scope == :instance && method == "#{attribute}?" ? owner_class : super
522
+ end
523
+ end
524
+ end
525
+ end