hat-trick 0.0.1

data/lib/hat_trick/step.rb

@@ -0,0 +1,35 @@
+require 'hat_trick/step_definition'
+
+module HatTrick
+  class Step
+    attr_reader :step_def, :wizard
+    attr_writer :skipped
+    attr_accessor :next_step
+
+    delegate :name, :fieldset, :buttons, :repeat_of, :to_sym, :to_s, :as_json,
+             :run_after_callback, :run_before_callback, :repeat?,
+             :run_include_data_callback, :include_data_key, :to => :step_def
+
+    def initialize(step_def, wizard)
+      @step_def = step_def
+      @wizard = wizard
+      @skipped = step_def.skipped?
+    end
+
+    def session
+      wizard.session
+    end
+
+    def skipped?
+      not visited? and @skipped
+    end
+
+    def visited?
+      session["hat-trick.steps_visited"].include? self.to_sym
+    end
+
+    def visited=(_visited)
+      session["hat-trick.steps_visited"] << self.to_sym
+    end
+  end
+end

data/lib/hat_trick/step_definition.rb

@@ -0,0 +1,104 @@
+module HatTrick
+  class StepDefinition
+    attr_reader :callbacks, :include_data_key
+    attr_accessor :name, :fieldset, :buttons, :repeat_of
+    attr_writer :skipped
+
+    def initialize(args={})
+      args.each_pair do |k,v|
+        setter = "#{k}="
+        if respond_to?(setter)
+          send(setter,v)
+        end
+      end
+      @callbacks = {}
+      @buttons = {}
+      @skipped = false
+    end
+
+    def initialize_copy(source)
+      @callbacks = source.callbacks.dup
+      @buttons = source.buttons.dup
+      @skipped = false
+      @repeat_of = source
+    end
+
+    def name=(name)
+      @name = name.to_sym
+    end
+
+    def fieldset=(fieldset)
+      @fieldset = fieldset.to_sym
+    end
+
+    def fieldset
+      @fieldset or name
+    end
+
+    def repeat?
+      !repeat_of.nil?
+    end
+
+    def skipped?
+      @skipped
+    end
+
+    def to_s
+      str = "<HatTrick::Step:0x%08x :#{name}" % (object_id * 2)
+      str += " fieldset: #{fieldset}" if fieldset != name
+      str += ">"
+      str
+    end
+
+    def to_sym
+      name.to_sym
+    end
+
+    def as_json(options = nil)
+      json = { :name => name, :fieldset => fieldset }
+      json[:repeatOf] = repeat_of.as_json if repeat?
+      json[:buttons] = buttons unless buttons.empty?
+      json
+    end
+
+    def before_callback=(blk)
+      callbacks[:before] = blk
+    end
+
+    def after_callback=(blk)
+      callbacks[:after] = blk
+    end
+
+    def include_data=(hash)
+      callbacks[:include_data] = hash.values.first
+      @include_data_key = hash.keys.first
+    end
+
+    def run_before_callback(context, wizard_dsl, model)
+      run_callback(:before, context, wizard_dsl, model)
+    end
+
+    def run_include_data_callback(context, wizard_dsl, model)
+      run_callback(:include_data, context, wizard_dsl, model)
+    end
+
+    def run_after_callback(context, wizard_dsl, model)
+      run_callback(:after, context, wizard_dsl, model)
+    end
+
+    protected
+
+    def run_callback(type, context, *args)
+      callback = callbacks[type.to_sym]
+      if callback && callback.is_a?(Proc)
+        if callback.arity > 1
+          context.instance_exec args[0], args[1], &callback
+        elsif callback.arity == 1
+          context.instance_exec args[0], &callback
+        else
+          context.instance_eval &callback
+        end
+      end
+    end
+  end
+end

data/lib/hat_trick/version.rb

@@ -0,0 +1,3 @@
+module HatTrick
+  VERSION = "0.0.1"
+end

data/lib/hat_trick/wizard.rb

@@ -0,0 +1,176 @@
+require 'hat_trick/controller_hooks'
+require 'hat_trick/wizard_steps'
+
+module HatTrick
+  class Wizard
+    include WizardSteps
+
+    attr_accessor :controller, :model
+    attr_reader :current_step, :wizard_def, :wizard_dsl_context, :steps
+
+    def initialize(wizard_def)
+      @wizard_def = wizard_def
+      @wizard_dsl_context = DSL::WizardContext.new(@wizard_def)
+      @wizard_dsl_context.wizard = self
+      @steps = @wizard_def.steps.map { |s| HatTrick::Step.new(s, self) }
+    end
+
+    def controller=(new_controller)
+      @controller = new_controller
+    end
+
+    def current_step=(_step)
+      raise "Don't set current_step to nil" if _step.nil?
+      step = find_step(_step)
+      raise "#{step} is not a member of this wizard" unless step
+      @current_step = step
+    end
+
+    def session
+      controller.session unless controller.nil?
+    end
+
+    def model_created?
+      !(model.nil? || (model.respond_to?(:new_record?) && model.new_record?))
+    end
+
+    def current_form_url
+      model_created? ? update_url : create_url
+    end
+
+    def current_form_method
+      model_created? ? 'put' : 'post'
+    end
+
+    def create_url
+      controller.url_for(:controller => controller.controller_name,
+                         :action => 'create', :only_path => true)
+    end
+
+    def update_url
+      if model_created?
+        controller.url_for(:controller => controller.controller_name,
+                           :action => 'update', :id => model,
+                           :only_path => true)
+      else
+        nil
+      end
+    end
+
+    def next_step
+      step = find_next_step
+      while step.skipped? do
+        step = find_step_after(step)
+      end
+      step
+    end
+
+    def previously_visited_step
+      steps_before(current_step).select { |s| s.visited? }.last
+    end
+
+    def skip_step(_step)
+      step = find_step(_step)
+      step.skipped = true
+    end
+
+    def started?
+      !current_step.nil?
+    end
+
+    def start
+      session["hat-trick.steps_visited"] = []
+      self.current_step = first_step
+      run_before_callback
+    end
+
+    def finish
+      # Do something here
+      # Such as: Force the wizard to display the "done" page
+      Rails.logger.info "WIZARD FINISHED!"
+    end
+
+    def run_before_callback(step=current_step)
+      step.run_before_callback(controller, wizard_dsl_context, model)
+    end
+
+    def run_after_callback(step=current_step)
+      step.run_after_callback(controller, wizard_dsl_context, model)
+    end
+
+    def advance_step_with_debugger
+      require 'ruby-debug'
+      debugger
+      advance_step
+    end
+
+    def advance_step(next_step_name=nil)
+      # clean up current step
+      current_step.visited = true
+      run_after_callback
+
+      # see if there is a requested next step
+      requested_next_step = find_step(next_step_name) unless next_step_name.nil?
+
+      # finish if we're on the last step
+      if current_step == last_step && !requested_next_step
+        finish
+      else # we're not on the last step
+        if requested_next_step
+          Rails.logger.info "Force advancing to step: #{requested_next_step}"
+          self.current_step = requested_next_step
+          run_before_callback
+          # if the step was explicitly requested, we ignore #skipped?
+        else
+          Rails.logger.info "Advancing to step: #{next_step}"
+          self.current_step = next_step
+          run_before_callback
+          # Running the before callback may have marked current_step as skipped
+          while current_step.skipped?
+            self.current_step = next_step
+            run_before_callback
+          end
+        end
+      end
+    end
+
+    def include_data
+      return {} unless model
+      inc_data = current_step.run_include_data_callback(controller, wizard_dsl_context, model)
+      data_key = current_step.include_data_key
+      { data_key.to_s.camelize(:lower) => camelize_hash_keys(inc_data) }
+    end
+
+    def alias_action_methods
+      action_methods = controller.action_methods.reject do |m|
+        /^render/ =~ m.to_s ||
+        controller.respond_to?("#{m}_with_hat_trick", :include_private)
+      end
+      HatTrick::ControllerHooks.def_action_method_aliases(action_methods)
+      action_methods.each do |meth|
+        controller.class.send(:alias_method_chain, meth, :hat_trick)
+        controller.class.send(:private, "#{meth}_without_hat_trick")
+      end
+    end
+
+    private
+
+    def find_next_step
+      find_step(current_step.next_step) or find_step_after(current_step)
+    end
+
+    def find_step_after(step)
+      next_path_step = step_after step
+      next_path_step or find_next_active_step(step)
+    end
+
+    def camelize_hash_keys(_hash)
+      return nil if _hash.nil?
+      hash = {}
+      _hash.each do |k,v|
+        hash[k.to_s.camelize(:lower)] = v
+      end
+      hash
+    end
+  end
+end

data/lib/hat_trick/wizard_definition.rb

@@ -0,0 +1,22 @@
+require 'hat_trick/step'
+require 'hat_trick/wizard_steps'
+require 'hat_trick/wizard'
+
+module HatTrick
+  class WizardDefinition
+    include WizardSteps
+
+    def initialize
+      @steps = []
+    end
+
+    def get_wizard(controller)
+      controller.send(:ht_wizard) or (
+        wizard = HatTrick::Wizard.new(self)
+        wizard.controller = controller
+        wizard.alias_action_methods
+        wizard
+      )
+    end
+  end
+end

data/lib/hat_trick/wizard_steps.rb

@@ -0,0 +1,95 @@
+module HatTrick
+  module WizardSteps
+    include Enumerable
+    attr_reader :steps
+
+    delegate :each, :empty?, :first, :last, :to => :steps
+
+    alias_method :each_step, :each
+    alias_method :to_ary, :steps
+    alias_method :first_step, :first
+    alias_method :last_step, :last
+
+    def find_step(step)
+      return nil if step.nil?
+      if step.is_a?(HatTrick::Step) || step.is_a?(HatTrick::StepDefinition)
+        find { |s| s.equal? step }
+      else
+        find { |s| s.name == step.to_sym }
+      end
+    end
+
+    def step_after(_step)
+      steps_after(_step).first
+    end
+
+    def steps_after(_step)
+      step = find_step(_step)
+      return [] unless step
+      after_index = steps.index(step) + 1
+      steps[after_index .. -1]
+    end
+
+    def step_before(_step)
+      steps_before(_step).last
+    end
+
+    def steps_before(_step)
+      step = find_step(_step)
+      return [] unless step
+      before_index = steps.index(step) - 1
+      steps[0 .. before_index]
+    end
+
+    def add_step(step, args={})
+      if step.is_a?(HatTrick::Step) || step.is_a?(HatTrick::StepDefinition)
+        new_step = step
+      else
+        step_args = args.merge(:name => step)
+        new_step = HatTrick::StepDefinition.new(step_args)
+      end
+
+      steps << new_step
+
+      new_step
+    end
+
+    def delete_step(_step)
+      step = find_step(_step)
+      steps.delete(step)
+    end
+
+    def replace_step(_old_step, _new_step)
+      old_step = find_step(_old_step)
+      old_index = steps.index(old_step)
+      raise ArgumentError, "Couldn't find step #{_old_step}" unless old_step
+      new_step_in_wizard = find_step(_new_step)
+      if new_step_in_wizard
+        # new_step is already in the wizard
+        return move_step(new_step_in_wizard, old_index)
+      end
+
+      if _new_step.is_a?(HatTrick::Step) || _new_step.is_a?(HatTrick::StepDefinition)
+        new_step = _new_step
+      else
+        new_step = HatTrick::StepDefinition.new(:name => _new_step)
+      end
+
+      steps.delete_at(old_index)
+      steps.insert(old_index, new_step)
+      new_step
+    end
+
+    def move_step(step, index)
+      raise ArgumentError, "#{step} isn't in this wizard" unless steps.include?(step)
+      current_index = steps.index(step)
+      unless index < current_index
+        raise ArgumentError, "#{step} has index #{current_index}; must be >= #{index}"
+      end
+
+      while steps.index(step) > index
+        steps.delete_at(index)
+      end
+    end
+  end
+end

data/lib/hat_trick.rb

@@ -0,0 +1,2 @@
+$LOAD_PATH.unshift File.dirname(__FILE__)
+require 'hat-trick'

data/spec/lib/hat_trick/step_spec.rb

@@ -0,0 +1,9 @@
+require 'spec_helper'
+
+describe HatTrick::Step do
+  subject { HatTrick::Step.new(name: "test_step") }
+
+  let(:wizard_def) { HatTrick::WizardDefinition.new }
+
+  it { should be_a(HatTrick::Step) }
+end

data/spec/lib/hat_trick/wizard_definition_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+describe HatTrick::WizardDefinition do
+  subject { HatTrick::WizardDefinition.new }
+
+  it { should be_empty }
+
+  describe "#add_step" do
+    it "should accept a symbol for the step name" do
+      step = subject.add_step(:step1)
+      step.name.should == :step1
+    end
+
+    it "should add a step to the wizard def" do
+      subject.add_step(:step1)
+      subject.should have(1).step
+    end
+
+    it "should update the last_step attr" do
+      step = subject.add_step(:step1)
+      subject.last_step.should == step
+    end
+  end
+
+  describe "#delete_step" do
+    it "should remove the step from the wizard def" do
+      step = subject.add_step(:goner)
+      subject.delete_step(step)
+      subject.steps.should_not include(step)
+    end
+
+    it "should update the the links between surrounding steps" do
+    end
+  end
+
+  describe "#replace_step" do
+  end
+
+end

data/spec/lib/hat_trick/wizard_spec.rb

@@ -0,0 +1,64 @@
+require 'spec_helper'
+
+describe HatTrick::Wizard do
+  subject {
+    wiz_def = HatTrick::WizardDefinition.new
+    wiz_def.add_step(:step1)
+    wiz_def.add_step(:step2)
+    wiz_def.add_step(:step3)
+    wiz_def.add_step(:step4)
+    wiz_def.add_step(:step5)
+
+    HatTrick::Wizard.new(wiz_def)
+  }
+
+  before :each do
+    subject.start
+  end
+
+  describe "advancing steps" do
+    it "should go from step1 to step2" do
+      subject.current_step.to_sym.should == :step1
+      subject.advance_step
+      subject.current_step.to_sym.should == :step2
+    end
+  end
+
+  describe "skipping steps" do
+    it "should skip step2 when requested" do
+      subject.skip_step :step2
+      subject.advance_step
+      subject.current_step.to_sym.should == :step3
+    end
+
+    it "should skip steps 2 & 3 when requested" do
+      subject.skip_step :step2
+      subject.skip_step :step3
+      subject.advance_step
+      subject.current_step.to_sym.should == :step4
+    end
+  end
+
+  describe "repeating steps" do
+    it "should repeat step 2 when requested" do
+    end
+  end
+
+  describe "setting explicit next steps" do
+    it "should advance to the requested next step when one is set" do
+      subject.steps.first.next_step = :step4
+      subject.advance_step
+      subject.current_step.to_sym.should == :step4
+    end
+  end
+
+  describe "#previously_visited_step" do
+    it "should return the most recently visited step" do
+      subject.steps[0].visited = true
+      subject.steps[1].visited = true
+      subject.steps[3].visited = true
+      subject.current_step = :step5
+      subject.previously_visited_step.to_sym.should == :step4
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,33 @@
+ENV["RAILS_ENV"] ||= 'test'
+require 'bundler/setup'
+require 'logger'
+
+module Rails
+  def self.root
+    Pathname.new(File.expand_path('../..', __FILE__))
+  end
+
+  def self.logger
+    @logger ||= ::Logger.new(STDOUT).tap { |l| l.level = ::Logger::ERROR }
+  end
+
+  class Engine
+    def self.initializer(*args, &block); end
+  end
+end
+
+module ActionController
+  class Base
+  end
+end
+
+require File.expand_path('../../lib/hat-trick', __FILE__)
+require 'rspec/autorun'
+
+# Requires supporting ruby files with custom matchers and macros, etc,
+# in spec/support/ and its subdirectories.
+Dir[Rails.root.join("spec/support/**/*.rb")].each {|f| require f}
+
+RSpec.configure do |config|
+  config.mock_with :mocha
+end