aasm_progressable 1.0.0 → 1.0.1

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: b02c82b67010f9ab734beab0cec83dc3e2aaf0fc
4
- data.tar.gz: 3b159e1d8fc17986bf5593759dec67a072965a02
3
+ metadata.gz: 67995923fc82754ccdc67431ff7f6f5d4e2a5845
4
+ data.tar.gz: 91828b61393744b6636f22b18fc299df3f8bf367
5
5
  SHA512:
6
- metadata.gz: 0319067fe12b531167669eaa3ca4f6850e55b5f2bfb40f23debd0c9481e7d518dab2ab0babbbac44ed5760b93cf35f196a39d2c2c2a65622993082c684f2a9df
7
- data.tar.gz: e47d7ae2467fea32e275f73881433f64a03742deb5b07023d9e8e6879009564873ef836dc4150552d9c63c9fb7f8a4b5488e7d0d7be7f7f0ed3c3a3f8d3c06ce
6
+ metadata.gz: 7f3952b9c8aba571fbee360432899a4cfd76117c4a55eb46e5c2179825eaf6a78512f5ba22aa35bae0366dcea1250fd0a1725f49b0b70e4a9eb4e89b7873e304
7
+ data.tar.gz: 4b721476a8a6d3020d40803b00f8254704091acca710c6951bd32dbe5f64282e0b30a5fee7c042803f3926bc37d567ee48d2ca7bbdf71efd01b5f9f867d2d8b9
data/README.md CHANGED
@@ -1,16 +1,16 @@
1
1
  aasm_progressable
2
2
  =================
3
3
 
4
- Rails helper to render the progress indicators for simple linear [AASM](https://github.com/aasm/aasm) workflows. It allows users to see steps in a workflow they have completed, which step is in progress, and which steps have not been completed. See the following image for an example.
4
+ `aasm_progressable` is a Rails helper to render the progress indicators for simple linear [AASM](https://github.com/aasm/aasm) workflows. It also provides predicates to make it easy to check a model's current position in its workflow. Using `aasm_progressable` allows users to see steps in a workflow they have completed, which step is in progress, and which steps have not been completed. See the following image for an example.
5
5
 
6
6
  ![Example Screenshot](https://raw.github.com/WorkflowsOnRails/aasm_progressable/master/docs/sample-screenshot.png)
7
7
 
8
8
 
9
- Using aasm_progressable
10
- -----------------------
9
+ Usage
10
+ -----
11
11
 
12
12
  Add `aasm_progressable` to your Gemfile, and run bundler to install it. For each model with an appropriate workflow, include `AasmProgressable::ModelMixin`, and add a call to `aasm_state_order` with an array of symbols corresponding to
13
- the expected order in which the states will be traversed. For example, if we have an `Order` class that starts from the `new` state, proceeds to `processing`, and then `shipping`, we might have
13
+ the expected order in which the states will be traversed. For example, if you have an `Order` class that starts from the `new` state, proceeds to `processing`, and then `shipping`, you might have
14
14
 
15
15
  ```rb
16
16
  class Order < ActiveRecord::Base
@@ -32,13 +32,23 @@ class Order < ActiveRecord::Base
32
32
  end
33
33
  ```
34
34
 
35
- In order to render the progress indicator, we need to add `helper AasmProgressable::Helper` to your ApplicationController. Then, in any detailed views for the order (such as orders#show), we can add `<%= render_state_indicator the_model_instance %>` to render an indicator for the state of the specified instance of the model. By default, this will render an ordered list (`ol`) with one element per state, with the elements corresponding to complete, current, and incomplete states being classed with `complete`, `active`, and `incomplete` respectively. You can add a ` *= require aasm_progressable` line to your application stylesheet to include some default styling for the indicator.
35
+ In order to render the progress indicator, you need to add `helper AasmProgressable::Helper` to your ApplicationController. Then in any detailed views for the order (such as `orders#show`), add `<%= render_state_indicator the_model_instance %>` to render an indicator for the state of the specified instance of the model. By default, this will render an ordered list (`ol`) with one element per state, with the elements corresponding to complete, current, and incomplete states being classed with `complete`, `active`, and `incomplete` respectively. You can add a ` *= require aasm_progressable` line to your application stylesheet to include some default styling for the indicator.
36
36
 
37
37
 
38
- Customizing and Localizing aasm_progressable
39
- --------------------------------------------
38
+ Custom Rendering
39
+ ---------------------
40
40
 
41
- aasm_progressable uses `AASM::Localizer#human_state_name` to convert AASM states to output text. By default, this method will replace underscores with spaces, and capitalize the first letter of the state name. However, it can also fetch state names from a locale key of the form `activerecord.attributes.<model-table-name>.<aasm-column-name>/<state-symbol>`. By default, `<aasm-column-name>` will be "aasm_state".
41
+ The default template for `aasm_progressable` can be customized to suit your needs. Run `rails g aasm_progressable:views` to copy the default template to app/views/aasm\_progressable/states/\_list.html.erb, and then customize it to your needs.
42
+
43
+ If you need additional template variables, you can pass local variables to the invocation of `render_state_indicator`. For instance, you can do the following to make the model instance available in a local variable:
44
+ ```erb
45
+ <%= render_state_indicator the_model_instance, locals: {object: the_model_instance } %>`
46
+ ```
47
+
48
+ Localization
49
+ ------------
50
+
51
+ `aasm_progressable `uses `AASM::Localizer#human_state_name` to convert AASM states to output text. By default, this method will replace underscores with spaces, and capitalize the first letter of the state name. However, it can also fetch state names from a locale key of the form `activerecord.attributes.<model-table-name>.<aasm-column-name>/<state-symbol>`. By default, `<aasm-column-name>` will be "aasm_state".
42
52
 
43
53
  As an example, if we wanted to display "Unconfirmed" as English name for the `:new` order state in the previous example, we could add the following to config/locales/en.yml:
44
54
 
@@ -51,7 +61,16 @@ en:
51
61
  ```
52
62
 
53
63
 
64
+ State Predicates
65
+ ----------------
66
+
67
+ `aasm_progressable` also provides a few predicates that you can use to query a model's state:
68
+
69
+ - `#have_completed?` and `#have_not_completed?` can be used to check if a step has already been finished. In the Order example, if the current state of an instance named `order` was `processing`, then `order.have_completed? :new` would return true, while `order.have_completed? :processing` would return false.
70
+
71
+ - `#have_started?` and `#have_not_started?` can be used to check if a step has already started. Again using the Order model defined previously, if an instance named `order` was in the `processing` state, then `order.have_started? :processing` would be true, while `order.have_not_started? :shipping` would return false.
72
+
54
73
  Limitations
55
74
  ------------
56
75
 
57
- Models that use aasm_progressable should have a strictly linear workflow, ie. there should be no branches in the state machine. Loops and skipped states are permitted, but there may not be alternative states. If a model instance is in a state that does not appear in the model's `aasm_state_order` declaration, then the helper will not be able to infer the state transition history of the instance and all states will be rendered as if they were completed.
76
+ Models that use `aasm_progressable` should have a strictly linear workflow, ie. there should be no branches in the state machine. Loops and skipped states are permitted, but there may not be alternative states. If a model instance is in a state that does not appear in the model's `aasm_state_order` declaration, then the helper will not be able to infer the state transition history of the instance and all states will be rendered as if they were completed.
@@ -0,0 +1,15 @@
1
+ require 'rails/generators/base'
2
+
3
+
4
+ module AasmProgressable
5
+ module Generators
6
+ class ViewsGenerator < Rails::Generators::Base
7
+ desc 'Install a copy of the default aasm_progressable views'
8
+ source_root File.expand_path('../../../../app/views', __FILE__)
9
+
10
+ def copy_views
11
+ directory 'aasm_progressable', 'app/views/aasm_progressable'
12
+ end
13
+ end
14
+ end
15
+ end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: aasm_progressable
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.0.0
4
+ version: 1.0.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Brendan MacDonell
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2013-12-29 00:00:00.000000000 Z
11
+ date: 2014-03-31 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: rails
@@ -65,6 +65,7 @@ files:
65
65
  - lib/aasm_progressable.rb
66
66
  - lib/aasm_progressable/engine.rb
67
67
  - lib/aasm_progressable/model_mixin.rb
68
+ - lib/generators/aasm_progressable/views_generator.rb
68
69
  homepage: http://rubygems.org/gems/aasm_progressable
69
70
  licenses:
70
71
  - MIT