workflow 2.0.2 → 3.1.0.pre
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.adoc +588 -0
- data/lib/workflow/event.rb +13 -3
- data/lib/workflow/event_collection.rb +2 -2
- data/lib/workflow/specification.rb +4 -0
- data/lib/workflow/version.rb +1 -1
- data/lib/workflow.rb +32 -32
- metadata +18 -18
- data/README.markdown +0 -664
data/README.markdown
DELETED
@@ -1,664 +0,0 @@
|
|
1
|
-
[](https://badge.fury.io/rb/workflow)
|
2
|
-
[](https://travis-ci.org/geekq/workflow)
|
3
|
-
[](https://codeclimate.com/github/geekq/workflow)
|
4
|
-
[](https://codeclimate.com/github/geekq/workflow/coverage)
|
5
|
-
|
6
|
-
# Workflow
|
7
|
-
|
8
|
-
Note: you can find documentation for specific workflow rubygem versions
|
9
|
-
at http://rubygems.org/gems/workflow : select a version (optional,
|
10
|
-
default is latest release), click "Documentation" link. When reading on
|
11
|
-
github.com, the README refers to the upcoming release.
|
12
|
-
|
13
|
-
**Note: Workflow 2.0 is a major refactoring of the library.
|
14
|
-
For different options/troubleshooting using it with your Rails application see
|
15
|
-
[State persistence with ActiveRecord](#state-persistence-with-activerecord).**
|
16
|
-
|
17
|
-
Note for contributors: it looks like github closed all the pull requests after
|
18
|
-
I had changed the default branch on 2019-01-12. Please check the new refactored
|
19
|
-
workflow 2.0, complementing workflow-activerecord and recreate your pull
|
20
|
-
request if needed.
|
21
|
-
|
22
|
-
What is workflow?
|
23
|
-
-----------------
|
24
|
-
|
25
|
-
Workflow is a finite-state-machine-inspired API for modeling and
|
26
|
-
interacting with what we tend to refer to as 'workflow'.
|
27
|
-
|
28
|
-
A lot of business modeling tends to involve workflow-like concepts, and
|
29
|
-
the aim of this library is to make the expression of these concepts as
|
30
|
-
clear as possible, using similar terminology as found in state machine
|
31
|
-
theory.
|
32
|
-
|
33
|
-
So, a workflow has a state. It can only be in one state at a time. When
|
34
|
-
a workflow changes state, we call that a transition. Transitions occur
|
35
|
-
on an event, so events cause transitions to occur. Additionally, when an
|
36
|
-
event fires, other arbitrary code can be executed, we call those actions.
|
37
|
-
So any given state has a bunch of events, any event in a state causes a
|
38
|
-
transition to another state and potentially causes code to be executed
|
39
|
-
(an action). We can hook into states when they are entered, and exited
|
40
|
-
from, and we can cause transitions to fail (guards), and we can hook in
|
41
|
-
to every transition that occurs ever for whatever reason we can come up
|
42
|
-
with.
|
43
|
-
|
44
|
-
Now, all that's a mouthful, but we'll demonstrate the API bit by bit
|
45
|
-
with a real-ish world example.
|
46
|
-
|
47
|
-
Let's say we're modeling article submission from journalists. An article
|
48
|
-
is written, then submitted. When it's submitted, it's awaiting review.
|
49
|
-
Someone reviews the article, and then either accepts or rejects it.
|
50
|
-
Here is the expression of this workflow using the API:
|
51
|
-
|
52
|
-
class Article
|
53
|
-
include Workflow
|
54
|
-
workflow do
|
55
|
-
state :new do
|
56
|
-
event :submit, :transitions_to => :awaiting_review
|
57
|
-
end
|
58
|
-
state :awaiting_review do
|
59
|
-
event :review, :transitions_to => :being_reviewed
|
60
|
-
end
|
61
|
-
state :being_reviewed do
|
62
|
-
event :accept, :transitions_to => :accepted
|
63
|
-
event :reject, :transitions_to => :rejected
|
64
|
-
end
|
65
|
-
state :accepted
|
66
|
-
state :rejected
|
67
|
-
end
|
68
|
-
end
|
69
|
-
|
70
|
-
Nice, isn't it!
|
71
|
-
|
72
|
-
Note: the first state in the definition (`:new` in the example, but you
|
73
|
-
can name it as you wish) is used as the initial state - newly created
|
74
|
-
objects start their life cycle in that state.
|
75
|
-
|
76
|
-
Let's create an article instance and check in which state it is:
|
77
|
-
|
78
|
-
article = Article.new
|
79
|
-
article.accepted? # => false
|
80
|
-
article.new? # => true
|
81
|
-
|
82
|
-
You can also access the whole `current_state` object including the list
|
83
|
-
of possible events and other meta information:
|
84
|
-
|
85
|
-
article.current_state
|
86
|
-
=> #<Workflow::State:0x7f1e3d6731f0 @events={
|
87
|
-
:submit=>#<Workflow::Event:0x7f1e3d6730d8 @action=nil,
|
88
|
-
@transitions_to=:awaiting_review, @name=:submit, @meta={}>},
|
89
|
-
name:new, meta{}
|
90
|
-
|
91
|
-
You can also check, whether a state comes before or after another state (by the
|
92
|
-
order they were defined):
|
93
|
-
|
94
|
-
article.current_state
|
95
|
-
=> being_reviewed
|
96
|
-
article.current_state < :accepted
|
97
|
-
=> true
|
98
|
-
article.current_state >= :accepted
|
99
|
-
=> false
|
100
|
-
article.current_state.between? :awaiting_review, :rejected
|
101
|
-
=> true
|
102
|
-
|
103
|
-
Now we can call the submit event, which transitions to the
|
104
|
-
<tt>:awaiting_review</tt> state:
|
105
|
-
|
106
|
-
article.submit!
|
107
|
-
article.awaiting_review? # => true
|
108
|
-
|
109
|
-
Events are actually instance methods on a workflow, and depending on the
|
110
|
-
state you're in, you'll have a different set of events used to
|
111
|
-
transition to other states.
|
112
|
-
|
113
|
-
It is also easy to check, if a certain transition is possible from the
|
114
|
-
current state . `article.can_submit?` checks if there is a `:submit`
|
115
|
-
event (transition) defined for the current state.
|
116
|
-
|
117
|
-
|
118
|
-
Installation
|
119
|
-
------------
|
120
|
-
|
121
|
-
gem install workflow
|
122
|
-
|
123
|
-
**Important**: If you're interested in graphing your workflow state machine, you will also need to
|
124
|
-
install the `activesupport` and `ruby-graphviz` gems.
|
125
|
-
|
126
|
-
Versions up to and including 1.0.0 are also available as a single file download -
|
127
|
-
[lib/workflow.rb file](https://github.com/geekq/workflow/blob/v1.0.0/lib/workflow.rb).
|
128
|
-
|
129
|
-
|
130
|
-
Examples
|
131
|
-
--------
|
132
|
-
|
133
|
-
After installation or downloading of the library you can easily try out
|
134
|
-
all the example code from this README in irb.
|
135
|
-
|
136
|
-
$ irb
|
137
|
-
require 'rubygems'
|
138
|
-
require 'workflow'
|
139
|
-
|
140
|
-
Now just copy and paste the source code from the beginning of this README
|
141
|
-
file snippet by snippet and observe the output.
|
142
|
-
|
143
|
-
|
144
|
-
Transition event handler
|
145
|
-
------------------------
|
146
|
-
|
147
|
-
The best way is to use convention over configuration and to define a
|
148
|
-
method with the same name as the event. Then it is automatically invoked
|
149
|
-
when event is raised. For the Article workflow defined earlier it would
|
150
|
-
be:
|
151
|
-
|
152
|
-
class Article
|
153
|
-
def reject
|
154
|
-
puts 'sending email to the author explaining the reason...'
|
155
|
-
end
|
156
|
-
end
|
157
|
-
|
158
|
-
`article.review!; article.reject!` will cause state transition to
|
159
|
-
`being_reviewed` state, persist the new state (if integrated with
|
160
|
-
ActiveRecord), invoke this user defined `reject` method and finally
|
161
|
-
persist the `rejected` state.
|
162
|
-
|
163
|
-
Note: on successful transition from one state to another the workflow
|
164
|
-
gem immediately persists the new workflow state with `update_column()`,
|
165
|
-
bypassing any ActiveRecord callbacks including `updated_at` update.
|
166
|
-
This way it is possible to deal with the validation and to save the
|
167
|
-
pending changes to a record at some later point instead of the moment
|
168
|
-
when transition occurs.
|
169
|
-
|
170
|
-
You can also define event handler accepting/requiring additional
|
171
|
-
arguments:
|
172
|
-
|
173
|
-
class Article
|
174
|
-
def review(reviewer = '')
|
175
|
-
puts "[#{reviewer}] is now reviewing the article"
|
176
|
-
end
|
177
|
-
end
|
178
|
-
|
179
|
-
article2 = Article.new
|
180
|
-
article2.submit!
|
181
|
-
article2.review!('Homer Simpson') # => [Homer Simpson] is now reviewing the article
|
182
|
-
|
183
|
-
|
184
|
-
### The old, deprecated way
|
185
|
-
|
186
|
-
The old way, using a block is still supported but deprecated:
|
187
|
-
|
188
|
-
event :review, :transitions_to => :being_reviewed do |reviewer|
|
189
|
-
# store the reviewer
|
190
|
-
end
|
191
|
-
|
192
|
-
We've noticed, that mixing the list of events and states with the blocks
|
193
|
-
invoked for particular transitions leads to a bumpy and poorly readable code
|
194
|
-
due to a deep nesting. We tried (and dismissed) lambdas for this. Eventually
|
195
|
-
we decided to invoke an optional user defined callback method with the same
|
196
|
-
name as the event (convention over configuration) as explained before.
|
197
|
-
|
198
|
-
State persistence with ActiveRecord
|
199
|
-
-----------------------------------
|
200
|
-
|
201
|
-
Note: Workflow 2.0 is a major refactoring for the `worklow` library.
|
202
|
-
If your application suddenly breaks after the workflow 2.0 release, you've
|
203
|
-
probably got your Gemfile wrong ;-). workflow uses [semantic versioning][]. For
|
204
|
-
highest compatibility please reference the desired major+minor version.
|
205
|
-
|
206
|
-
Note on ActiveRecord/Rails 4.\*, 5.\* Support:
|
207
|
-
|
208
|
-
Since integration with ActiveRecord makes over 90% of the issues and
|
209
|
-
maintenance effort, and also to allow for an independent (faster) release cycle
|
210
|
-
for Rails support, starting with workflow **version 2.0** in January 2019 the
|
211
|
-
support for ActiveRecord (4.\*, 5.\* and newer) has been extracted into a separate
|
212
|
-
gem. Read at [workflow-activerecord][], how to include the right gem.
|
213
|
-
|
214
|
-
To use legacy built-in ActiveRecord 2.3 - 4.* support, reference Workflow 1.2 in
|
215
|
-
your Gemfile:
|
216
|
-
|
217
|
-
gem 'workflow', '~> 1.2'
|
218
|
-
|
219
|
-
[semantic versioning]: https://guides.rubygems.org/patterns/#semantic-versioning
|
220
|
-
[workflow-activerecord]: https://github.com/geekq/workflow-activerecord
|
221
|
-
|
222
|
-
Custom workflow state persistence
|
223
|
-
---------------------------------
|
224
|
-
|
225
|
-
If you do not use a relational database and ActiveRecord, you can still
|
226
|
-
integrate the workflow very easily. To implement persistence you just
|
227
|
-
need to override `load_workflow_state` and
|
228
|
-
`persist_workflow_state(new_value)` methods. Next section contains an example for
|
229
|
-
using CouchDB, a document oriented database.
|
230
|
-
|
231
|
-
[Tim Lossen](http://tim.lossen.de/) implemented support
|
232
|
-
for [remodel](http://github.com/tlossen/remodel) / [redis](http://github.com/antirez/redis)
|
233
|
-
key-value store.
|
234
|
-
|
235
|
-
Integration with CouchDB
|
236
|
-
------------------------
|
237
|
-
|
238
|
-
We are using the compact [couchtiny library](http://github.com/geekq/couchtiny)
|
239
|
-
here. But the implementation would look similar for the popular
|
240
|
-
couchrest library.
|
241
|
-
|
242
|
-
require 'couchtiny'
|
243
|
-
require 'couchtiny/document'
|
244
|
-
require 'workflow'
|
245
|
-
|
246
|
-
class User < CouchTiny::Document
|
247
|
-
include Workflow
|
248
|
-
workflow do
|
249
|
-
state :submitted do
|
250
|
-
event :activate_via_link, :transitions_to => :proved_email
|
251
|
-
end
|
252
|
-
state :proved_email
|
253
|
-
end
|
254
|
-
|
255
|
-
def load_workflow_state
|
256
|
-
self[:workflow_state]
|
257
|
-
end
|
258
|
-
|
259
|
-
def persist_workflow_state(new_value)
|
260
|
-
self[:workflow_state] = new_value
|
261
|
-
save!
|
262
|
-
end
|
263
|
-
end
|
264
|
-
|
265
|
-
Please also have a look at
|
266
|
-
[the full source code](http://github.com/geekq/workflow/blob/master/test/couchtiny_example.rb).
|
267
|
-
|
268
|
-
|
269
|
-
Adapters to support other databases
|
270
|
-
-----------------------------------
|
271
|
-
|
272
|
-
I get a lot of requests to integrate persistence support for different
|
273
|
-
databases, object-relational adapters, column stores, document
|
274
|
-
databases.
|
275
|
-
|
276
|
-
To enable highest possible quality, avoid too many dependencies and to
|
277
|
-
avoid unneeded maintenance burden on the `workflow` core it is best to
|
278
|
-
implement such support as a separate gem.
|
279
|
-
|
280
|
-
Only support for the ActiveRecord will remain for the foreseeable
|
281
|
-
future. So Rails beginners can expect `workflow` to work with Rails out
|
282
|
-
of the box. Other already included adapters stay for a while but should
|
283
|
-
be extracted to separate gems.
|
284
|
-
|
285
|
-
If you want to implement support for your favorite ORM mapper or your
|
286
|
-
favorite NoSQL database, you just need to implement a module which
|
287
|
-
overrides the persistence methods `load_workflow_state` and
|
288
|
-
`persist_workflow_state`. Example:
|
289
|
-
|
290
|
-
module Workflow
|
291
|
-
module SuperCoolDb
|
292
|
-
module InstanceMethods
|
293
|
-
def load_workflow_state
|
294
|
-
# Load and return the workflow_state from some storage.
|
295
|
-
# You can use self.class.workflow_column configuration.
|
296
|
-
end
|
297
|
-
|
298
|
-
def persist_workflow_state(new_value)
|
299
|
-
# save the new_value workflow state
|
300
|
-
end
|
301
|
-
end
|
302
|
-
|
303
|
-
module ClassMethods
|
304
|
-
# class methods of your adapter go here
|
305
|
-
end
|
306
|
-
|
307
|
-
def self.included(klass)
|
308
|
-
klass.send :include, InstanceMethods
|
309
|
-
klass.extend ClassMethods
|
310
|
-
end
|
311
|
-
end
|
312
|
-
end
|
313
|
-
|
314
|
-
The user of the adapter can use it then as:
|
315
|
-
|
316
|
-
class Article
|
317
|
-
include Workflow
|
318
|
-
include Workflow:SuperCoolDb
|
319
|
-
workflow do
|
320
|
-
state :submitted
|
321
|
-
# ...
|
322
|
-
end
|
323
|
-
end
|
324
|
-
|
325
|
-
I can then link to your implementation from this README. Please let me
|
326
|
-
also know, if you need any interface beyond `load_workflow_state` and
|
327
|
-
`persist_workflow_state` methods to implement an adapter for your
|
328
|
-
favorite database.
|
329
|
-
|
330
|
-
|
331
|
-
Accessing your workflow specification
|
332
|
-
-------------------------------------
|
333
|
-
|
334
|
-
You can easily reflect on workflow specification programmatically - for
|
335
|
-
the whole class or for the current object. Examples:
|
336
|
-
|
337
|
-
article2.current_state.events # lists possible events from here
|
338
|
-
article2.current_state.events[:reject].transitions_to # => :rejected
|
339
|
-
|
340
|
-
Article.workflow_spec.states.keys
|
341
|
-
#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
|
342
|
-
|
343
|
-
Article.workflow_spec.state_names
|
344
|
-
#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
|
345
|
-
|
346
|
-
# list all events for all states
|
347
|
-
Article.workflow_spec.states.values.collect &:events
|
348
|
-
|
349
|
-
|
350
|
-
You can also store and later retrieve additional meta data for every
|
351
|
-
state and every event:
|
352
|
-
|
353
|
-
class MyProcess
|
354
|
-
include Workflow
|
355
|
-
workflow do
|
356
|
-
state :main, :meta => {:importance => 8}
|
357
|
-
state :supplemental, :meta => {:importance => 1}
|
358
|
-
end
|
359
|
-
end
|
360
|
-
puts MyProcess.workflow_spec.states[:supplemental].meta[:importance] # => 1
|
361
|
-
|
362
|
-
The workflow library itself uses this feature to tweak the graphical
|
363
|
-
representation of the workflow. See below.
|
364
|
-
|
365
|
-
|
366
|
-
Conditional event transitions
|
367
|
-
-----------------------------
|
368
|
-
|
369
|
-
Conditions can be a "method name symbol" with a corresponding instance method, a `proc` or `lambda` which are added to events, like so:
|
370
|
-
|
371
|
-
state :off
|
372
|
-
event :turn_on, :transition_to => :on,
|
373
|
-
:if => :sufficient_battery_level?
|
374
|
-
|
375
|
-
event :turn_on, :transition_to => :low_battery,
|
376
|
-
:if => proc { |device| device.battery_level > 0 }
|
377
|
-
end
|
378
|
-
|
379
|
-
# corresponding instance method
|
380
|
-
def sufficient_battery_level?
|
381
|
-
battery_level > 10
|
382
|
-
end
|
383
|
-
|
384
|
-
When calling a `device.can_<fire_event>?` check, or attempting a `device.<event>!`, each event is checked in turn:
|
385
|
-
|
386
|
-
* With no `:if` check, proceed as usual.
|
387
|
-
* If an `:if` check is present, proceed if it evaluates to true, or drop to the next event.
|
388
|
-
* If you've run out of events to check (eg. `battery_level == 0`), then the transition isn't possible.
|
389
|
-
|
390
|
-
|
391
|
-
Advanced transition hooks
|
392
|
-
-------------------------
|
393
|
-
|
394
|
-
### on_entry/on_exit
|
395
|
-
|
396
|
-
We already had a look at the declaring callbacks for particular workflow
|
397
|
-
events. If you would like to react to all transitions to/from the same state
|
398
|
-
in the same way you can use the on_entry/on_exit hooks. You can either define it
|
399
|
-
with a block inside the workflow definition or through naming
|
400
|
-
convention, e.g. for the state :pending just define the method
|
401
|
-
`on_pending_exit(new_state, event, *args)` somewhere in your class.
|
402
|
-
|
403
|
-
### on_transition
|
404
|
-
|
405
|
-
If you want to be informed about everything happening everywhere, e.g. for
|
406
|
-
logging then you can use the universal `on_transition` hook:
|
407
|
-
|
408
|
-
workflow do
|
409
|
-
state :one do
|
410
|
-
event :increment, :transitions_to => :two
|
411
|
-
end
|
412
|
-
state :two
|
413
|
-
on_transition do |from, to, triggering_event, *event_args|
|
414
|
-
Log.info "#{from} -> #{to}"
|
415
|
-
end
|
416
|
-
end
|
417
|
-
|
418
|
-
### on_error
|
419
|
-
|
420
|
-
If you want to do custom exception handling internal to workflow, you can define an `on_error` hook in your workflow.
|
421
|
-
For example:
|
422
|
-
|
423
|
-
workflow do
|
424
|
-
state :first do
|
425
|
-
event :forward, :transitions_to => :second
|
426
|
-
end
|
427
|
-
state :second
|
428
|
-
|
429
|
-
on_error do |error, from, to, event, *args|
|
430
|
-
Log.info "Exception(#error.class) on #{from} -> #{to}"
|
431
|
-
end
|
432
|
-
end
|
433
|
-
|
434
|
-
If forward! results in an exception, `on_error` is invoked and the workflow stays in a 'first' state. This capability
|
435
|
-
is particularly useful if your errors are transient and you want to queue up a job to retry in the future without
|
436
|
-
affecting the existing workflow state.
|
437
|
-
|
438
|
-
### Guards
|
439
|
-
|
440
|
-
If you want to halt the transition conditionally, you can just raise an
|
441
|
-
exception in your [transition event handler](#transition_event_handler).
|
442
|
-
There is a helper called `halt!`, which raises the
|
443
|
-
Workflow::TransitionHalted exception. You can provide an additional
|
444
|
-
`halted_because` parameter.
|
445
|
-
|
446
|
-
def reject(reason)
|
447
|
-
halt! 'We do not reject articles unless the reason is important' \
|
448
|
-
unless reason =~ /important/i
|
449
|
-
end
|
450
|
-
|
451
|
-
The traditional `halt` (without the exclamation mark) is still supported
|
452
|
-
too. This just prevents the state change without raising an
|
453
|
-
exception.
|
454
|
-
|
455
|
-
You can check `halted?` and `halted_because` values later.
|
456
|
-
|
457
|
-
### Hook order
|
458
|
-
|
459
|
-
The whole event sequence is as follows:
|
460
|
-
|
461
|
-
* before_transition
|
462
|
-
* event specific action
|
463
|
-
* on_transition (if action did not halt)
|
464
|
-
* on_exit
|
465
|
-
* PERSIST WORKFLOW STATE, i.e. transition
|
466
|
-
* on_entry
|
467
|
-
* after_transition
|
468
|
-
|
469
|
-
|
470
|
-
Documenting with diagrams
|
471
|
-
-------------------------
|
472
|
-
|
473
|
-
You can generate a graphical representation of the workflow for
|
474
|
-
a particular class for documentation purposes.
|
475
|
-
Use `Workflow::create_workflow_diagram(class)` in your rake task like:
|
476
|
-
|
477
|
-
namespace :doc do
|
478
|
-
desc "Generate a workflow graph for a model passed e.g. as 'MODEL=Order'."
|
479
|
-
task :workflow => :environment do
|
480
|
-
require 'workflow/draw'
|
481
|
-
Workflow::Draw::workflow_diagram(ENV['MODEL'].constantize)
|
482
|
-
end
|
483
|
-
end
|
484
|
-
|
485
|
-
|
486
|
-
Development Setup
|
487
|
-
-----------------
|
488
|
-
|
489
|
-
sudo apt-get install graphviz # Linux
|
490
|
-
brew cask install graphviz # Mac OS
|
491
|
-
cd workflow
|
492
|
-
gem install bundler
|
493
|
-
bundle install
|
494
|
-
# run all the tests
|
495
|
-
bundle exec rake test
|
496
|
-
|
497
|
-
|
498
|
-
Changelog
|
499
|
-
---------
|
500
|
-
|
501
|
-
### New in the version 2.0.2
|
502
|
-
|
503
|
-
* finalize extraction of persistence adapters, remove remodel adapter
|
504
|
-
|
505
|
-
### New in the version 2.0.1
|
506
|
-
|
507
|
-
* retire Ruby 2.3 since it has reached end of live
|
508
|
-
* fix #213 ruby-graphiz warnings
|
509
|
-
|
510
|
-
### New in the version 2.0.0
|
511
|
-
|
512
|
-
* extract Rails/ActiveRecord integration into a separate gem
|
513
|
-
workflow-activerecord
|
514
|
-
* Remodel integration removed - needs to be a separate gem
|
515
|
-
|
516
|
-
Special thanks to [voltechs][] for implementing Rails 5 support
|
517
|
-
and helping to revive `workflow`!
|
518
|
-
|
519
|
-
[voltechs]: https://github.com/voltechs
|
520
|
-
|
521
|
-
### New in the upcoming version 1.3.0 (never released)
|
522
|
-
|
523
|
-
* Retiring Ruby 1.8.7 and Rails 2 support #118. If you still need this older
|
524
|
-
versions despite security issues and missing updates, you can use
|
525
|
-
workflow 1.2.0 or older. In your Gemfile put
|
526
|
-
|
527
|
-
gem 'workflow', '~> 1.2.0'
|
528
|
-
|
529
|
-
or when using github source just reference the v1.2.0 tag.
|
530
|
-
* improved callback method handling: #113 and #125
|
531
|
-
|
532
|
-
### New in the version 1.2.0
|
533
|
-
|
534
|
-
* Fix issue #98 protected on\_\* callbacks in Ruby 2
|
535
|
-
* #106 Inherit exceptions from StandardError instead of Exception
|
536
|
-
* #109 Conditional event transitions, contributed by [damncabbage](http://robhoward.id.au/)
|
537
|
-
Please note: this introduces incompatible changes to the meta data API, see also #131.
|
538
|
-
* New policy for supporting other databases - extract to separate
|
539
|
-
gems. See the README section above.
|
540
|
-
* #111 Custom Versions of Existing Adapters by [damncabbage](http://robhoward.id.au/)
|
541
|
-
|
542
|
-
|
543
|
-
### New in the version 1.1.0
|
544
|
-
|
545
|
-
* Tested with ActiveRecord 4.0 (Rails 4.0)
|
546
|
-
* Tested with Ruby 2.0
|
547
|
-
* automatically generated scopes with names based on state names
|
548
|
-
* clean workflow definition override for class inheritance - undefining
|
549
|
-
the old convinience methods, s. <http://git.io/FZO02A>
|
550
|
-
|
551
|
-
### New in the version 1.0.0
|
552
|
-
|
553
|
-
* **Support to private/protected callback methods.**
|
554
|
-
See also issues [#53](https://github.com/geekq/workflow/pull/53)
|
555
|
-
and [#58](https://github.com/geekq/workflow/pull/58). With the new
|
556
|
-
implementation:
|
557
|
-
|
558
|
-
* callback methods can be hidden (non public): both private methods
|
559
|
-
in the immediate class and protected methods somewhere in the class
|
560
|
-
hierarchy are supported
|
561
|
-
* no unintentional calls on `fail!` and other Kernel methods
|
562
|
-
* inheritance hierarchy with workflow is supported
|
563
|
-
|
564
|
-
* using Rails' 3.1 `update_column` whenever available so only the
|
565
|
-
workflow state column and not other pending attribute changes are
|
566
|
-
saved on state transition. Fallback to `update_attribute` for older
|
567
|
-
Rails and other ORMs. [commit](https://github.com/geekq/workflow/commit/7e091d8ded1aeeb0a86647bbf7d78ab3c9d0c458)
|
568
|
-
|
569
|
-
### New in the version 0.8.7
|
570
|
-
|
571
|
-
* switch from [jeweler][] to pure bundler for building gems
|
572
|
-
|
573
|
-
### New in the version 0.8.0
|
574
|
-
|
575
|
-
* check if a certain transition possible from the current state with
|
576
|
-
`can_....?`
|
577
|
-
* fix workflow_state persistence for multiple_workflows example
|
578
|
-
* add before_transition and after_transition hooks as suggested by
|
579
|
-
[kasperbn](https://github.com/kasperbn)
|
580
|
-
|
581
|
-
### New in the version 0.7.0
|
582
|
-
|
583
|
-
* fix issue#10 Workflow::create_workflow_diagram documentation and path
|
584
|
-
escaping
|
585
|
-
* fix issue#7 workflow_column does not work STI (single table
|
586
|
-
inheritance) ActiveRecord models
|
587
|
-
* fix issue#5 Diagram generation fails for models in modules
|
588
|
-
|
589
|
-
### New in the version 0.6.0
|
590
|
-
|
591
|
-
* enable multiple workflows by connecting workflow to object instances
|
592
|
-
(using metaclass) instead of connecting to a class, s. "Multiple
|
593
|
-
Workflows" section
|
594
|
-
|
595
|
-
### New in the version 0.5.0
|
596
|
-
|
597
|
-
* fix issue#3 change the behaviour of halt! to immediately raise an
|
598
|
-
exception. See also http://github.com/geekq/workflow/issues/#issue/3
|
599
|
-
|
600
|
-
### New in the version 0.4.0
|
601
|
-
|
602
|
-
* completely rewritten the documentation to match my branch
|
603
|
-
* switch to [jeweler][] for building gems
|
604
|
-
* use [gemcutter][] for gem distribution
|
605
|
-
* every described feature is backed up by an automated test
|
606
|
-
|
607
|
-
[jeweler]: http://github.com/technicalpickles/jeweler
|
608
|
-
[gemcutter]: http://gemcutter.org/gems/workflow
|
609
|
-
|
610
|
-
### New in the version 0.3.0
|
611
|
-
|
612
|
-
Intermixing of transition graph definition (states, transitions)
|
613
|
-
on the one side and implementation of the actions on the other side
|
614
|
-
for a bigger state machine can introduce clutter.
|
615
|
-
|
616
|
-
To reduce this clutter it is now possible to use state entry- and
|
617
|
-
exit- hooks defined through a naming convention. For example, if there
|
618
|
-
is a state :pending, then instead of using a
|
619
|
-
block:
|
620
|
-
|
621
|
-
state :pending do
|
622
|
-
on_entry do
|
623
|
-
# your implementation here
|
624
|
-
end
|
625
|
-
end
|
626
|
-
|
627
|
-
you can hook in by defining method
|
628
|
-
|
629
|
-
def on_pending_exit(new_state, event, *args)
|
630
|
-
# your implementation here
|
631
|
-
end
|
632
|
-
|
633
|
-
anywhere in your class. You can also use a simpler function signature
|
634
|
-
like `def on_pending_exit(*args)` if your are not interested in
|
635
|
-
arguments. Please note: `def on_pending_exit()` with an empty list
|
636
|
-
would not work.
|
637
|
-
|
638
|
-
If both a function with a name according to naming convention and the
|
639
|
-
on_entry/on_exit block are given, then only on_entry/on_exit block is used.
|
640
|
-
|
641
|
-
|
642
|
-
Support
|
643
|
-
-------
|
644
|
-
|
645
|
-
### Reporting bugs
|
646
|
-
|
647
|
-
<http://github.com/geekq/workflow/issues>
|
648
|
-
|
649
|
-
|
650
|
-
About
|
651
|
-
-----
|
652
|
-
|
653
|
-
Author: Vladimir Dobriakov, <https://infrastructure-as-code.de>
|
654
|
-
|
655
|
-
Copyright (c) 2010-2019 Vladimir Dobriakov and Contributors
|
656
|
-
|
657
|
-
Copyright (c) 2008-2009 Vodafone
|
658
|
-
|
659
|
-
Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
|
660
|
-
|
661
|
-
Based on the work of Ryan Allen and Scott Barron
|
662
|
-
|
663
|
-
Licensed under MIT license, see the MIT-LICENSE file.
|
664
|
-
|