aasm_progressable 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b02c82b67010f9ab734beab0cec83dc3e2aaf0fc
+  data.tar.gz: 3b159e1d8fc17986bf5593759dec67a072965a02
+SHA512:
+  metadata.gz: 0319067fe12b531167669eaa3ca4f6850e55b5f2bfb40f23debd0c9481e7d518dab2ab0babbbac44ed5760b93cf35f196a39d2c2c2a65622993082c684f2a9df
+  data.tar.gz: e47d7ae2467fea32e275f73881433f64a03742deb5b07023d9e8e6879009564873ef836dc4150552d9c63c9fb7f8a4b5488e7d0d7be7f7f0ed3c3a3f8d3c06ce

data/README.md

@@ -0,0 +1,57 @@
+aasm_progressable
+=================
+
+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.
+
+![Example Screenshot](https://raw.github.com/WorkflowsOnRails/aasm_progressable/master/docs/sample-screenshot.png)
+
+
+Using aasm_progressable
+-----------------------
+
+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
+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
+
+```rb
+class Order < ActiveRecord::Base
+  include AASM
+  aasm do
+    state :new, initial: true
+    state :processing
+    state :shipping
+    
+    event :confirm do
+      transitions from: :new, to: :processing
+    end
+    event :dispatch do
+      transitions from: :processing, to: :shipping
+    end
+  end
+  
+  aasm_state_order [:new, :processing, :shipping]
+end
+```
+
+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.
+
+
+Customizing and Localizing aasm_progressable
+--------------------------------------------
+
+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".
+
+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:
+
+```yaml
+en:
+  activerecord:
+    attributes:
+      order:
+        aasm_state/new: "Unconfirmed"
+```
+
+
+Limitations
+------------
+
+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.

data/app/assets/stylesheets/aasm_progressable.css.scss

@@ -0,0 +1,32 @@
+.state-indicator {
+  display: table;
+  table-layout: fixed;
+  width: 100%;
+  border-collapse: separate;
+  font-size: 16px;
+
+  ol {
+    display: table-row;
+  }
+  li {
+    display: table-cell;
+    padding: 6px 16px;
+    border-right: 4px solid #fff;
+
+    &:last-child {
+      border-right: none;
+    }
+  }
+  .complete {
+    background: #6aa3d5;
+    color: #fff;
+  }
+  .active {
+    background: #357ebd;
+    color: #fff;
+  }
+  .incomplete {
+    background: #eae8ec;
+    color: #999;
+  }
+}

data/app/helpers/aasm_progressable/helper.rb

@@ -0,0 +1,62 @@
+# The ActionView helper. This should be made accessible to appropriate
+# controllers by adding a `helper AasmProgressable::Helper` declaration
+# to them.
+#
+# @author Brendan MacDonell
+module AasmProgressable
+  # Internal class to manage display attribute associated with each
+  # model state, such as the name to display, and if the state has
+  # been completed yet or not.
+  class State
+    attr_reader :id      # the internal ID for the state (as a string)
+    attr_reader :name    # name displayed to the user
+
+    def initialize(id, name, status_classes)
+      @id = id.to_s
+      @name = name
+      @status_classes = status_classes
+    end
+
+    # html_class may contain complete, previous, active, next, or incomplete.
+    def html_class
+      @status_classes.join(' ')
+    end
+
+    def is?(status_class)
+      @status_classes.include? status_class
+    end
+
+    # Returns an Array of State instances corresponding to the states
+    # of a model instance. The State instances are returned in the order
+    # given by the `aasm_state_order` declaration in the model.
+    def self.create_all(object)
+      localizer = AASM::Localizer.new
+      state_order = object.aasm_state_order
+      current_state = object.aasm.current_state
+
+      current_state_index = state_order.index(current_state)
+
+      object.aasm_state_order.each_with_index.map do |state, index|
+        status_classes = []
+        status_classes << :complete if index < current_state_index
+        status_classes << :previous if index == current_state_index - 1
+        status_classes << :active if index == current_state_index
+        status_classes << :next if index == current_state_index + 1
+        status_classes << :incomplete if index > current_state_index
+
+        name = localizer.human_state_name(object.class, state)
+        State.new(state, name, status_classes)
+      end
+    end
+  end
+
+  module Helper
+    # Renders a state indicator for a specified model instance.
+    def render_state_indicator(object, locals: {})
+      states = State.create_all(object)
+      locals = {states: states}.merge(locals)
+      rendered = render partial: 'aasm_progressable/states/list', locals: locals
+      rendered.html_safe
+    end
+  end
+end

data/app/views/aasm_progressable/states/_list.html.erb

@@ -0,0 +1,9 @@
+<div class="state-indicator">
+  <ol>
+    <% states.each_with_index do |state, index| %>
+    <li class="<%= state.html_class %>">
+      <%= index + 1 %>. <%= state.name %>
+    </li>
+    <% end %>
+  </ol>
+</div>

data/lib/aasm_progressable.rb

@@ -0,0 +1,5 @@
+require "aasm_progressable/engine"
+require "aasm_progressable/model_mixin"
+ 
+module AasmProgressable
+end

data/lib/aasm_progressable/engine.rb

@@ -0,0 +1,5 @@
+module AasmProgressable
+  class Engine < ::Rails::Engine
+    isolate_namespace AasmProgressable
+  end
+end

data/lib/aasm_progressable/model_mixin.rb

@@ -0,0 +1,53 @@
+# Mixin for models with linear AASM-defined workflows.
+#
+# This mixin provides the aasm_state_order class settor, as well as
+# a similarly-named instance gettor.
+#
+# @author Brendan MacDonell
+module AasmProgressable
+  module ModelMixin
+    extend ActiveSupport::Concern
+
+    # Instance gettor to return the state order for the model
+    def aasm_state_order
+      self.class.get_aasm_state_order
+    end
+
+    def have_completed?(state)
+      current_index, target_index = state_index(self.aasm.current_state, state)
+      current_index > target_index
+    end
+
+    def have_not_completed?(state)
+      not have_completed?(state)
+    end
+
+    def have_started?(state)
+      current_index, target_index = state_index(self.aasm.current_state, state)
+      current_index >= target_index
+    end
+
+    def have_not_started?(state)
+      not have_started?(state)
+    end
+
+    # Class gettors and settors for the state order
+    module ClassMethods
+      def aasm_state_order order
+        @state_order = order
+      end
+
+      def get_aasm_state_order
+        @state_order
+      end
+    end
+
+    private
+
+    # Returns an array of zero-index state indices, where each index indicates
+    # the state's position in the ordered state collection.
+    def state_index(*states)
+      states.map { |state| self.aasm_state_order.index(state) }
+    end
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: aasm_progressable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brendan MacDonell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-12-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: aasm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sass-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: Progress indicators for linear AASM workflows
+email: brendan@macdonell.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- app/assets/stylesheets/aasm_progressable.css.scss
+- app/helpers/aasm_progressable/helper.rb
+- app/views/aasm_progressable/states/_list.html.erb
+- lib/aasm_progressable.rb
+- lib/aasm_progressable/engine.rb
+- lib/aasm_progressable/model_mixin.rb
+homepage: http://rubygems.org/gems/aasm_progressable
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: AASM Progressable
+test_files: []
+has_rdoc: