README.adoc in workflow-3.0.0 vs README.adoc in workflow-3.1.0.pre

- old
+ new

@@ -100,11 +100,11 @@ article.current_state >= :accepted # => false article.current_state.between? :awaiting_review, :rejected # => true ``` Now we can call the submit event, which transitions to the -<tt>:awaiting_review</tt> state: +`:awaiting_review` state: ```rb article.submit! article.awaiting_review? # => true ``` @@ -129,11 +129,11 @@ **Important**: If you're interested in graphing your workflow state machine, you will also need to install the `activesupport` and `ruby-graphviz` gems. Versions up to and including 1.0.0 are also available as a single file download - -[lib/workflow.rb file](https://github.com/geekq/workflow/blob/v1.0.0/lib/workflow.rb). +link:https://github.com/geekq/workflow/blob/v1.0.0/lib/workflow.rb[lib/workflow.rb file]. === Examples After installation or downloading the library you can easily try out @@ -343,47 +343,10 @@ favorite database. Advanced usage -------------- -### Accessing your workflow specification - -You can easily reflect on workflow specification programmatically - for -the whole class or for the current object. Examples: - -```rb -article2.current_state.events # lists possible events from here -article2.current_state.events[:reject].transitions_to # => :rejected - -Article.workflow_spec.states.keys -#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new] - -Article.workflow_spec.state_names -#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new] - -# list all events for all states -Article.workflow_spec.states.values.collect &:events -``` - -You can also store and later retrieve additional meta data for every -state and every event: - -```rb -class MyProcess - include Workflow - workflow do - state :main, :meta => {:importance => 8} - state :supplemental, :meta => {:importance => 1} - end -end -puts MyProcess.workflow_spec.states[:supplemental].meta[:importance] # => 1 -``` - -The workflow library itself uses this feature to tweak the graphical -representation of the workflow. See below. - - ### Conditional event transitions Conditions can be a "method name symbol" with a corresponding instance method, a `proc` or `lambda` which are added to events, like so: ```rb @@ -405,10 +368,12 @@ * With no `:if` check, proceed as usual. * If an `:if` check is present, proceed if it evaluates to true, or drop to the next event. * If you've run out of events to check (eg. `battery_level == 0`), then the transition isn't possible. +You can also pass additional arguments, which can be evaluated by :if methods or procs. See examples in +link:test/conditionals_test.rb#L45[conditionals_test.rb] ### Advanced transition hooks #### on_entry/on_exit @@ -485,15 +450,64 @@ * before_transition * event specific action * on_transition (if action did not halt) * on_exit - * PERSIST WORKFLOW STATE, i.e. transition + * PERSIST WORKFLOW STATE (i.e. transition) or on_error * on_entry * after_transition +### Accessing your workflow specification + +You can easily reflect on workflow specification programmatically - for +the whole class or for the current object. Examples: + +```rb +article2.current_state.events # lists possible events from here +article2.current_state.events[:reject].transitions_to # => :rejected + +Article.workflow_spec.states.keys +#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new] + +Article.workflow_spec.state_names +#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new] + +# list all events for all states +Article.workflow_spec.states.values.collect &:events +``` + +You can also store and later retrieve additional meta data for every +state and every event: + +```rb +class MyProcess + include Workflow + workflow do + state :main, :meta => {:importance => 8} + state :supplemental, :meta => {:importance => 1} + end +end +puts MyProcess.workflow_spec.states[:supplemental].meta[:importance] # => 1 +``` + +The workflow library itself uses this feature to tweak the graphical +representation of the workflow. See below. + + +### Defining workflow dynamically from JSON + +For an advance example please see +link:https://github.com/geekq/workflow/blob/develop/test/workflow_from_json_test.rb[workflow_from_json_test.rb]. + + +### Compose workflow definition with `include` + +In case you have very extensive workflow definition or would like to reuse +workflow definition for different classes, you can include parts like in +the link:https://github.com/geekq/workflow/blob/develop/test/main_test.rb#L95-L110[`including a child workflow definition` example]. + Documenting with diagrams ------------------------- You can generate a graphical representation of the workflow for a particular class for documentation purposes. @@ -511,15 +525,21 @@ Changelog --------- +=== New in the version 3.1.0 + +* link:https://github.com/geekq/workflow/pull/227[#227] Allow event arguments to be taken into account when selecting the event +* link:https://github.com/geekq/workflow/pull/232[#232] Add ability to include partial workflow definitions for composability +* link:https://github.com/geekq/workflow/pull/241[#241] Example for defining workflow dynamically from JSON + === New in the version 3.0.0 -* gh-228 Support for Ruby 3 keyword args, provided by @agirling +* link:https://github.com/geekq/workflow/pull/228[#228] Support for Ruby 3 keyword args, provided by @agirling * retire Ruby 2.6 since it has reached end of live; please use workflow 2.x, if you still depend on that Ruby version -* gh-229 Switch from travis CI to GihHub actions for continuous integration +* link:https://github.com/geekq/workflow/pull/229[#229] Switch from travis CI to GihHub actions for continuous integration ### New in the versions 2.x * extract persistence adapters, Rails/ActiveRecord integration is now a separate gem workflow-activerecord @@ -541,24 +561,28 @@ bundle install # run all the tests bundle exec rake test ``` +### Check list for you pull request + +* [ ] unit tests for the new behavior provided: new tests fail without you change, all tests succeed with your change +* [ ] documentation update included + ### Other 3rd party libraries https://github.com/kwent/active_admin-workflow[ActiveAdmin-Workflow] - is an integration with https://github.com/activeadmin/activeadmin[ActiveAdmin]. ### About Author: Vladimir Dobriakov, <https://infrastructure-as-code.de> -Copyright (c) 2010-2022 Vladimir Dobriakov and Contributors +Copyright (c) 2010-2024 Vladimir Dobriakov and Contributors Copyright (c) 2008-2009 Vodafone Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd Based on the work of Ryan Allen and Scott Barron Licensed under MIT license, see the MIT-LICENSE file. -