aasm_actionable 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ff1e81cf16edd7094a105e73f9aedc2266d8d7ae
+  data.tar.gz: be5ce695a6bb737d076b564e255f3472420c1d24
+SHA512:
+  metadata.gz: b233023e60586033682614fb809ef09d0b3c9550ed58c85e0486aecc25c63f940a3783641c818a50b921d2125fc5e3ec07c88f8130428d675e96b58766be91d3
+  data.tar.gz: 1c523c8679fbfe227026b1093a4f1b9ee4b5a4fa0e200ae63b53a7750c320c9748609135686acddf871e96f0b099a7eb77a6f43b223e040391f863a2812b191f

data/README.md

@@ -0,0 +1,149 @@
+aasm_actionable
+===============
+
+aasm_actionable is a Rails extension that helps factor out boilerplate state and authorization conditionals from view code. Using [pundit](https://github.com/elabs/pundit) for authorization, it allows developers to write partials for user actions that are automatically displayed to the user if the model is in an appropriate state, and the user has sufficient permissions.
+
+
+Installation
+------------
+
+Add `aasm_actionable` to your Gemfile, and run Bundler to install it. You will also want to install Pundit, as described in the [Pundit documentation](https://github.com/elabs/pundit#installation).
+
+
+Using aasm_actionable
+---------------------
+
+Each action that aasm_actionable may display requires the developer to provide three things:
+
+1. An event with the same name as the desired action, ex. `do_action`;
+2. A method on the pundit policy for the model on which the action is to be performed, ex. `do_action?`; and
+3. A partial for the model with the same name as the action, ex. `mymodel/_do_action.html.erb`.
+ 
+Additionally, you may wish to create a controller method and route to handle the action being performed. By convention, the controller method should have the same name as the action, ie. `do_action` for the example above.
+
+Once you have provided one or more actions for a model, you can render a model instance's available actions by including `AasmActionable::ControllerMixin` in your controller, and adding `<%= render_state_actions my_instance %>` in your view.
+
+
+Usage Example
+-------------
+
+Consider the following contrived Order model (in `app/models/order.rb`) for a (trivial) online store:
+
+```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
+end
+```
+
+Suppose that users in an inventory tracking role manually confirm an order by double-checking if the item is in stock, while users in shipping are responsible for marking an order as dispatched. We would like to render appropriate actions on a view of the order, depending on the order's state and the role that the user occupies. Confirmation does not add any new information to the order, but dispatching the order requires a shipping number.
+
+First, we need to define an policy to describe which users can perform which actions. In `app/policies/order.rb`, we create a new `OrderPolicy` class, and define appropriate `confirm?` and `dispatch?` methods:
+
+```rb
+class OrderPolicy < ApplicationPolicy
+  # ... other default policy methods (ex. show?) omitted for conciseness.
+
+  def confirm?
+    user.in_role? :inventory
+  end
+
+  def dispatch?
+    user.in_role? :shipping
+  end
+end
+```
+
+Next, we add methods to the order controller to handle these actions, along with the mixin:
+
+```rb
+class OrderController < ApplicationController
+  include AasmActionable::ControllerMixin
+
+  # ... other controller methods omitted ...
+  
+  def show
+    @order = find_order
+    authorize @order
+  end
+  
+  def confirm
+    @order = find_order
+    authorize @order
+
+    if order.confirm!
+      redirect_to order
+    else
+      # ... handle the error and re-render the order page ...
+    end
+  end
+  
+  def dispatch
+    @order = find_order
+    authorize @order
+    
+    dispatch_params = params.require(:order).permit(:shipping_number)
+    order.assign_attributes(dispatch_params)
+
+    if order.dispatch!
+      redirect_to order
+    else
+      # ... handle the error and re-render the order page ...
+    end
+  end
+  
+  private
+  
+  def find_order
+    Order.find(params[:id])
+  end
+end
+```
+
+(You may want to consider using [responders](https://github.com/plataformatec/responders) or a similar library to cut down on boilerplate in your custom controller methods.)
+
+We must also add the new actions to `config/routes.rb`:
+
+```rb
+  # ... other routes omitted ...
+  
+  resources :orders do
+    member do
+      post 'confirm'
+      post 'dispatch'
+    end
+  end
+  
+  # ...
+```
+
+Next, we create a partial for each action. For example, for the dispatch action we might write the following `app/views/order/_dispatch.html.erb`:
+
+```erb
+<% form_for @order, url: dispatch_order_path, method: :post do %>
+  <div>
+    <%= f.label :shipping_number %>:
+    <%= f.text_field :shipping_number %>
+  </div>
+  <%= f.submit "Dispatch" %>
+<% end %>
+```
+
+Finally, we render the actions in the order view by adding `<%= render_state_actions @order %>` to `app/views/order/show.html.erb`.
+
+
+Customizing Action Rendering
+----------------------------
+
+_TODO (mention that the default template uses the Bootstrap 3 tab component)_

data/app/views/aasm_actionable/_list.html.erb

@@ -0,0 +1,26 @@
+<div class="actions">
+  <% if actions.empty? %>
+  <p>
+    You cannot perform any actions at this time.
+  </p>
+  <% else %>
+  <ul class="nav nav-tabs">
+    <% actions.each_with_index do |action, index| %>
+    <li class="<%= if index == 0 then 'active' end %>">
+      <a href="#<%= action.id %>" data-toggle="tab">
+        <%= action.title %>
+      </a>
+    </li>
+    <% end %>
+  </ul>
+
+  <div class="tab-content">
+    <% actions.each_with_index do |action, index| %>
+    <div class="action-tab tab-pane <%= if index == 0 then 'active' end %>"
+         id="<%= action.id %>">
+      <%= render partial: action.partial, locals: {taskable: taskable} %>
+    </div>
+    <% end %>
+  </div>
+  <% end %>
+</div>

data/lib/aasm_actionable.rb

@@ -0,0 +1,5 @@
+require "aasm_actionable/engine"
+require "aasm_actionable/controller_mixin"
+ 
+module AasmActionable
+end

data/lib/aasm_actionable/controller_mixin.rb

@@ -0,0 +1,65 @@
+module AasmActionable
+  # A StateAction groups together the various attributes for an action
+  # being rendered, such as it's title, HTML ID, and the name of the
+  # partial to render.
+  #
+  # Note that the HTML ID is not unique, so it is not currently possible
+  # to call render_state_actions multiple times for the same taskable type
+  # on one page.
+  #
+  # @author Brendan MacDonell
+  class StateAction
+    attr_reader :title, :id, :partial
+
+    def initialize(event, action_view_prefix)
+      @title = event.to_s.titleize
+      @id = "action-#{event}"
+      @partial = "#{action_view_prefix}/#{event}"
+    end
+  end
+
+  # The ControllerMixin concern implements a controller-based helper
+  # that can automatically render those actions which can be performed by a
+  # user on a taskable. In order to use it, you must do the following:
+  #
+  # 1. Create a Pundit policy for the taskable, with one method named
+  #    <event>? for every event in the taskable's state machine. For
+  #    example, define submit? if there is a submit event.
+  #
+  # 2. Create a partial with the same name as every event defined in the
+  #    taskable's state machine. For example, create _submit.html.erb if
+  #    there is a submit event.
+  #
+  # Partials are looked up in the view directory with the same name as the
+  # controller by default. You can change this by providing the method
+  # action_view_prefix(event) in your controller, and returning the view
+  # prefix you wish to look up partials in.
+  #
+  # @author Brendan MacDonell
+  module ControllerMixin
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :render_state_actions
+    end
+
+    def action_view_prefix(event)
+      controller_name
+    end
+
+    def render_state_actions(taskable)
+      a_policy = policy(taskable)
+      events = taskable.aasm.events
+        .select { |event| a_policy.send("#{event}?") }
+
+      actions = events.map do |event|
+        StateAction.new(event, action_view_prefix(event))
+      end
+      actions.sort_by! {|action| action.title}
+
+      rendered = render_to_string partial: 'aasm_actionable/list',
+                                  locals: {actions: actions, taskable: taskable}
+      rendered.html_safe
+    end
+  end
+end

data/lib/aasm_actionable/engine.rb

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

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: aasm_actionable
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brendan MacDonell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-03 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: pundit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+description: Rails extension to render appropriate workflow actions
+email: brendan@macdonell.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- app/views/aasm_actionable/_list.html.erb
+- lib/aasm_actionable.rb
+- lib/aasm_actionable/controller_mixin.rb
+- lib/aasm_actionable/engine.rb
+homepage: http://rubygems.org/gems/aasm_actionable
+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 Actionable
+test_files: []
+has_rdoc: