action_flow 0.2.0

data/.gitignore

@@ -0,0 +1,5 @@
+*~
+pkg
+*.sw?
+.DS_Store
+coverage

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Justin Balthrop
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,78 @@
+= Flow
+
+Flow is a simple workflow engine mixin for controllers that makes generating simple
+or complex user flows as easy as it should be, rather than the painful process it usually is with MVC.
+Also, it makes your controllers incredibly skinny, by moving the flow logic out of the
+controller into a Flow::Context model.
+
+== Usage:
+
+Say you want to create a multi-page flow for new user signup. Assuming you keep the logic
+for creating users in your User model, where it belongs, this is all the code you would need:
+
+  class NewUserFlowContext < Flow::Context
+    state :start do
+      if params[:already_a_member]
+        transition(:login)
+      else
+        transition(:signup)
+      end
+    end
+
+    state :login
+
+    state :signup do
+      if User.name_taken?(params[:username])
+        flash[:error] = 'Username already taken. Please choose another.'
+        transition(:signup)
+      else
+        u = User.create(params)
+        data[:user_id] = u.id
+        transition(:confirm)
+      end
+    end 
+  end
+
+  class NewUserController
+    include Flow
+    flow :new_user
+  end
+
+Then you just create a template for each state in app/views/new_user. Flow also provides
+two helper functions to make template creation really easy:
+
+  <%= flow_link_to "I already have an account", :already_a_member => true %>
+  
+  <% flow_form_tag do -%>
+    <%= text_field_tag :name %>
+    <%= text_field_tag :email_address %>
+    <%= password_field_tag :password %>
+    <%= submit_tag %>
+  <% end %>
+
+These are just like link_to and form_tag, but they submit to the :next action, which is a
+special action for transitioning between states. They also add the parameters necessary
+to maintain context.
+
+== Internals:
+
+When you call the flow class macro in a controller, it creates an action for each state
+defined in the specified flow context. It also creates an action called :next
+for transitioning between states. The template helper functions (flow_link_to, and
+flow_form_tag) submit a POST to this action. All transition logic is performed within next
+and then the user is redirected using a GET to the correct state action. This means users
+can safely use their browser back button to return to previous steps and use the forward
+button if they change their mind.
+
+Flow::Context is an ActiveRecord model. This allows flows to be easily persisted between
+steps.
+
+== Install:
+
+  sudo gem install flow
+
+You also need to create a migration to make the flow_contexts table. See examples/sample_migration.rb
+
+== License:
+
+Copyright (c) 2009 Justin Balthrop, Geni.com; Published under The MIT License, see License.txt

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "action_flow"
+    s.summary = %Q{ A state-machine inspired mixin for controllers that makes creating flows and wizards dead simple. }
+    s.email = "code@justinbalthrop.com"
+    s.homepage = "http://github.com/ninjudd/action_flow"
+    s.description = "A state-machine inspired mixin for controllers that makes creating flows and wizards dead simple."
+    s.add_dependency('meta', '>= 0.1.1')
+    s.authors = ["Justin Balthrop"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'action_flow'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/**/*_test.rb']
+    t.verbose = true
+  end
+rescue LoadError
+end
+
+task :default => :test

data/VERSION.yml

@@ -0,0 +1,5 @@
+--- 
+:build: 
+:patch: 0
+:major: 0
+:minor: 2

data/examples/sample_migration.rb

@@ -0,0 +1,9 @@
+class CreateFlowContexts < ActiveRecord::Migration
+  def self.up
+    FlowContextMigration.up
+  end
+
+  def self.down
+    FlowContextMigration.down
+  end
+end

data/lib/action_flow.rb

@@ -0,0 +1,157 @@
+require 'meta'
+require 'active_record'
+require 'action_controller'
+
+module ActionFlow
+  def flow(name)
+    helper ActionFlow::Helper
+
+    flow = "#{name}_flow_context".camelize.constantize
+
+    define_method(:context) do
+      @context ||= flow.find_or_create(params.delete(:k))
+    end
+    private :context
+
+    flow.states.each do |state|
+      define_method(state) do
+        context.at_state(state)
+        context.data.each do |key, value|
+          instance_variable_set("@#{key}", value)
+        end
+      end
+    end
+
+    define_method(:next) do
+      context.at_state(params.delete(:state))
+      context.fire_transition(self)
+      redirect_to(:action => context.state, :k => context.key)
+    end
+  end
+
+  module Helper
+    def flow_link_to(name, options = {}, html_options = {})
+      options.merge!(flow_options)
+      html_options.merge!(:post => true)
+      link_to(name, options, html_options)
+    end
+
+    def flow_form_tag(options = {}, html_options = {}, *args, &block)
+      options.merge!(flow_options)
+      html_options.merge!(:method => :post)
+      form_tag(options, html_options, *args, &block)
+    end
+
+  private
+
+    def flow_options
+      {:controller => controller.controller_name, :action => :next, :state => controller.context.state, :k => controller.context.key}
+    end
+  end
+
+  class Context < ActiveRecord::Base
+    set_table_name 'flow_contexts'
+
+    def before_save
+      self.states     = Marshal.dump(states)
+      self.state_data = Marshal.dump(state_data)
+    end
+
+    def after_save
+      self.states     = Marshal.load(states)
+      self.state_data = Marshal.load(state_data)
+    end
+
+    def after_find
+      after_save
+    end
+
+    inheritable_class_attr :initial
+    initial :start
+
+    def self.find_or_create(key = nil)
+      context = find_by_key(key) if key
+      context || create(
+        :states     => [initial],
+        :state_data => {},
+        :key        => generate_key
+      )
+    end
+
+    def self.generate_key
+      sha = Digest::SHA1::new
+      now = Time.now
+      sha.update(now.to_s)
+      sha.update(String(now.usec))
+      sha.update(String(rand))
+      sha.update(String($$))
+      sha.update('go with the flow')
+      sha.hexdigest
+    end
+
+    def self.transitions
+      @transitions ||= {}
+    end
+
+    def self.transition(state)
+      ancestors.each do |klass|
+        return if klass == ActionFlow::Context
+        next unless klass.respond_to?(:transitions)
+        transition = klass.transitions[state]
+        return transition if transition
+      end
+    end
+
+    def self.states
+      transitions.keys
+    end
+
+    def self.state(state, &block)
+      transitions[state] = block
+    end
+
+    attr_reader :controller
+    delegate :params, :flash, :to => :controller
+
+    def at_state(state)
+      state = state.to_sym
+      if states.include?(state)
+        @state = state
+        states.slice!(states.index(state) + 1..-1)
+      else
+        raise InvalidState, "state #{state} not valid in this context"
+      end
+    end
+
+    def state
+      @state ||= states.last
+    end
+
+    def data
+      state_data[:state] ||= {}
+    end
+
+    def fire_transition(controller)
+      @controller = controller
+      begin
+        transition = self.class.transition(state)
+        transition.bind(self).call
+      rescue TransitionFired
+      end
+    end
+
+    def transition(state)
+      @state = state
+      self.states << state
+      self.save
+      raise TransitionFired
+    end
+
+    class InvalidState    < StandardError; end
+    class TransitionFired < Exception;     end
+  end
+end
+
+class ActionController::Base
+  extend ActionFlow
+end

data/lib/flow_context_migration.rb

@@ -0,0 +1,17 @@
+class FlowContextMigration < ActiveRecord::Migration
+  def self.up
+    create_table :flow_contexts do |t|
+      t.timestamps
+      t.string :key
+      t.string :type
+      t.binary :states
+      t.binary :state_data
+      t.text   :final_destination
+    end
+    add_index :flow_contexts, :key, :unique => true
+  end
+
+  def self.down
+    drop_table :flow_contexts
+  end
+end

data/test/action_flow/context_test.rb

@@ -0,0 +1,81 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+
+class ActionFlowContextTest < Test::Unit::TestCase
+  class ParentContext < ActionFlow::Context
+    state :start do
+      transition(:parent_one)
+    end
+
+    state :parent_one do
+      transition(:parent_two)
+    end
+
+    state :parent_two
+  end
+
+  class ChildContext < ParentContext
+    state :parent_two do
+      transition(:child_one)
+    end
+
+    state :child_one do
+      transition(:child_two)
+    end
+
+    state :child_two
+  end
+
+  def setup
+    FlowContextMigration.down rescue nil
+    FlowContextMigration.up
+  end
+
+  def test_find_or_create
+    count = ActionFlow::Context.count
+    ChildContext.find_or_create
+    assert count != ActionFlow::Context.count
+  end
+
+  def test_state_serializaton
+    ChildContext.find_or_create
+    assert_equal [:start], ChildContext.first.states
+  end
+
+  def test_state_data_serializaton
+    state_data = {:one=>1, :two=>2, (1..10)=>'1 to 10'}
+    ChildContext.find_or_create.update_attributes(:state_data=>state_data)
+    assert_equal state_data, ChildContext.first.state_data
+  end
+
+  def test_singleton_transition_for_valid_state
+    assert_equal Proc, ChildContext.transition(:parent_one).class
+  end
+
+  def test_singleton_transition_for_invalid_state
+    assert_equal nil, ChildContext.transition(:foo)
+  end
+
+  def test_singleton_states
+    assert_equal [:child_one, :child_two, :parent_two], ChildContext.states.sort_by {|ii| ii.to_s}
+  end
+
+  def test_at_state_pops_subsequent_states_off_list
+    ctx = ChildContext.find_or_create
+    ctx.states << :parent_one
+    ctx.at_state(:start)
+    assert_equal [:start], ctx.states
+  end
+
+  def test_state
+    ctx = ChildContext.find_or_create
+    ctx.states << :parent_one
+    assert_equal :parent_one, ctx.state
+  end
+
+  def test_fire_transition
+    ctx = ChildContext.find_or_create
+    ctx.fire_transition(nil)
+    ctx.reload
+    assert_equal [:start, :parent_one], ctx.states
+  end
+end

data/test/action_flow/helper_test.rb

@@ -0,0 +1,74 @@
+require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
+require 'action_view/test_case'
+require 'ostruct'
+
+module ActionFlow
+
+  class HelperTest < ActionView::TestCase
+    tests ActionFlow::Helper
+
+    class TestController < ActionController::Base
+      attr_accessor :url
+
+      def initialize(url)
+        self.request = ActionController::TestRequest.new
+        self.url = ActionController::UrlRewriter.new(request, url)
+      end
+
+      def context
+        @context ||= OpenStruct.new(:state=>'state', :key=>'key')
+      end
+
+    end
+
+    def setup
+      @controller = TestController.new({:controller=>'text', :action=>'show'})
+    end
+
+    def test_flow_link_to
+      text = 'text'
+      options = {:option=>'value'}
+      html_options = {:html_option=>'value'}
+      with_route do
+        result = flow_link_to(text, options, html_options)
+        assert_match 'href="/test/next', result, 'href missing'
+        assert_match 'k=key', result, 'flow key missng'
+        assert_match 'state=state', result, 'flow state missing'
+        assert_match 'option=value', result
+        assert_match 'html_option="value"', result
+        assert_match '>text</a>', result, 'text missing'
+      end
+    end
+
+    def test_flow_form_tag
+      options = {:option=>'value'}
+      html_options = {:html_option=>'value'}
+      with_route do
+        result = flow_form_tag(options, html_options)
+        assert_match 'action="/test/next', result, 'action missing'
+        assert_match 'k=key', result, 'flow key missng'
+        assert_match 'state=state', result, 'flow state missing'
+        assert_match 'option=value', result
+        assert_match 'html_option="value"', result
+        assert_match 'method="post"', result
+      end
+    end
+
+  private
+
+    def with_route
+      with_routing do |set|
+        set.draw do |map|
+          map.connect ':controller/:action/:id'
+        end
+        yield
+      end
+    end
+
+    def protect_against_forgery?
+      false
+    end
+
+  end # class HelperTest
+
+end # module ActionFlow

data/test/action_flow_test.rb

@@ -0,0 +1,38 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class DummyFlowContext < ActionFlow::Context
+  state :start do
+    transition :one
+  end
+
+  state :one do
+    transition :two
+  end
+
+  state :two
+end
+
+class DummyController < ActionController::Base
+  flow :dummy
+end
+
+class ActionFlowTest < Test::Unit::TestCase
+  def test_flow_class_macro_includes_flow_helper
+    assert_equal true, DummyController.master_helper_module.include?(ActionFlow::Helper)
+  end
+
+  def test_flow_class_macro_adds_context_method
+    assert_equal true, DummyController.private_instance_methods.include?('context')
+  end
+
+  def test_flow_class_macro_adds_state_methods
+    DummyFlowContext.states.each do |state|
+      assert_equal true, DummyController.instance_methods.include?(state.to_s)
+    end
+  end
+
+  def test_flow_class_macro_adds_next_method
+    assert_equal true, DummyController.instance_methods.include?('next')
+  end
+end
+

data/test/test_helper.rb

@@ -0,0 +1,22 @@
+require 'set'
+require 'test/unit'
+require 'rubygems'
+require 'mocha'
+require 'pp'
+
+$:.unshift File.dirname(__FILE__), File.dirname(__FILE__) + '/../lib'
+
+require 'action_flow'
+require 'flow_context_migration'
+require 'action_controller/test_process'
+
+ActiveRecord::Base.establish_connection(
+  :adapter  => "postgresql",
+  :host     => "localhost",
+  :username => "postgres",
+  :password => "",
+  :database => "test"
+)
+
+ActiveRecord::Migration.verbose = false
+ActiveRecord::Base.connection.client_min_messages = 'panic'

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: action_flow
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Justin Balthrop
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-23 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: meta
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.1
+    version: 
+description: A state-machine inspired mixin for controllers that makes creating flows and wizards dead simple.
+email: code@justinbalthrop.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION.yml
+- examples/sample_migration.rb
+- lib/action_flow.rb
+- lib/flow_context_migration.rb
+- test/action_flow/context_test.rb
+- test/action_flow/helper_test.rb
+- test/action_flow_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/ninjudd/action_flow
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A state-machine inspired mixin for controllers that makes creating flows and wizards dead simple.
+test_files: 
+- test/action_flow/context_test.rb
+- test/action_flow/helper_test.rb
+- test/action_flow_test.rb
+- test/test_helper.rb
+- examples/sample_migration.rb