hat-trick 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in hat-trick.gemspec
+gemspec

data/README.md

@@ -0,0 +1,73 @@
+# Hat Trick
+> Combines jQuery FormWizard, validation_group, and gon for the perfect triple-play of Rails wizarding.
+
+## Install
+    gem install hat-trick
+
+### Rails 3.2
+(older versions not supported)
+
+Put this in your Gemfile:
+
+    gem 'hat-trick'
+    
+## Setup
+In your controller:
+
+    wizard do
+      step :first_step
+      step :second_step
+      step :third_step
+    end
+
+In your view:
+
+    <%= wizard_form_for @model do |f| %>
+      <fieldset id="first_step">...</fieldset>
+      <fieldset id="second_step">...</fieldset>
+      <fieldset id="third_step">...</fieldset>
+    <% end %>
+    
+The id's of the fieldsets in your form should match the step names you define in your controller.
+    
+## Controlling the wizard flow
+Sometimes you need to specify different paths through a wizard based on certain conditions. The way you do that with hat-trick is in the wizard DSL in the controller. Here are some examples:
+
+Jumping to a step based on logged in status:
+
+    wizard do
+      step :first_step do
+        # after_this_step defines a callback to run after the current step is completed by the user
+        after_this_step do
+          # code in this block will be exec'd in the context of your controller
+          if user_signed_in?
+            next_step :third_step
+          end
+        end
+      end
+      
+      step :second_step # wizard will go here after :first_step if user is not signed in
+      
+      step :third_step # wizard will go here after :first_step if user is signed in
+      
+Repeating a previous step (for example, to show address sanitization results to the user):
+  
+     wizard do
+       step :enter_address
+        
+       step :confirm_santized_address do
+         repeat_step :enter_address
+       end
+       
+Skipping a step under certain conditions:
+
+    wizard do
+      step :first_step
+      step :second_step do
+        # before_this_step defines a callback to run before the user sees this step
+        before_this_step do
+          # code in this block will be exec'd in the context of your controller
+          skip_this_step unless foo.present?
+        end
+      end
+    end

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec

data/app/assets/javascripts/hat-trick.js.coffee

@@ -0,0 +1,233 @@
+#= require vendor_js
+
+class HatTrickWizard
+  constructor: (formElem, @wizard) ->
+    @form = $(formElem)
+    fieldsets = @form.find("fieldset")
+    fieldsets.addClass("step")
+    wizard_buttons = '<input type="reset" /><input type="submit" />'
+    fieldsets.find("div.buttons").html wizard_buttons
+    window.htData = {}
+    # prevent submitting the step that happens to be the last fieldset
+    this.addFakeLastStep()
+    this.enableFormwizard() # unless this.formwizardEnabled()
+    this.setCurrentStepField()
+    # TODO: Try this out instead of putting :start first
+    # this.showStep(@wizard.currentStep)
+    this.bindEvents()
+
+  buttons: {}
+
+  findStep: (stepId) ->
+    @form.find("fieldset##{stepId}")
+
+  createMethodField: (method) ->
+    """<input type="hidden" name="_method" value="#{method}" />"""
+
+  setAction: (url, method) ->
+    methodLower = method.toLowerCase()
+    console.log "Setting form action to #{methodLower} #{url}"
+    @form.attr("action", url)
+    @form.attr("method", "post")
+    methodField = @form.find('input[name="_method"]')
+    methodField.remove()
+    if methodLower isnt "post"
+      @form.prepend(this.createMethodField(method))
+
+  currentStepId: ->
+    @form.formwizard("state").currentStep
+
+  currentStep: ->
+    stepId = this.currentStepId()
+    this.findStep(stepId)
+
+  nextStepFieldHTML: """<input type="hidden" name="_ht_next_step" class="_ht_link" value="" />"""
+
+  fieldsets: ->
+    @form.find("fieldset")
+
+  ajaxEvents: (firstStep=false) ->
+    remoteAjax = {}
+    $fieldsets = this.fieldsets()
+    $fieldsets = $fieldsets.filter(":first") if firstStep
+    $fieldsets.each (index, element) =>
+      stepId = $(element).attr("id")
+      remoteAjax[stepId] = this.createAjaxEvent(stepId)
+    remoteAjax
+
+  createAjaxEvent: (step) ->
+    # console.log "Adding AJAX to step #{step}"
+    ajax =
+      url: @form.attr("action"),
+      dataType: "json",
+      beforeSubmit: (data) =>
+        console.log "Sending these data to the server: #{$.param(data)}"
+      success: (data) =>
+        console.log "Successful form POST; got #{$.param(data)}"
+        if data.wizardMetadata?
+          this.setAction(data.wizardMetadata.url, data.wizardMetadata.method)
+        # merge new data with window.htData
+        $.extend(window.htData, data)
+      error: (data) =>
+        appErrors = eval "(#{data.responseText})"
+        this.addErrorItem value[0] for key, value of appErrors.formModel
+    ajax
+
+  addErrorItem: (message) ->
+    $errorList = this.currentStep().find("ul.hat_trick_errors")
+    if $errorList.length > 0
+      $errorList.append("<li>#{message}</li>")
+      $errorList.show()
+
+  updateSteps: ->
+    @form.formwizard("update_steps")
+    @form.formwizard("option", remoteAjax: this.ajaxEvents())
+
+  goToStepId: (stepId) ->
+    console.log "Setting up goto #{stepId}"
+    this.setHTMeta("next_step", stepId)
+    @form.formwizard("next")
+
+  repeatStep: (step) ->
+    $sourceStep = this.findStep(step.repeatOf.fieldset)
+    console.log "Cloning repeated step #{step.repeatOf.fieldset}"
+    $clonedStep = $sourceStep.clone(true, true)
+    $clonedStep.css("display", "none")
+    $clonedStep.attr("id", step.name)
+    $sourceStep.after($clonedStep)
+    this.updateSteps()
+    @form.formwizard("show", step.name)
+
+  showStep: (step) ->
+    console.log "Showing step #{step.fieldset}"
+    @form.formwizard("show", step.fieldset)
+
+  formwizardEnabled: ->
+    @form.formwizard?
+
+  addFakeLastStep: ->
+    @form.append """<fieldset id="_ht_fake_last_step" style="display: none;" class="step"></fieldset>"""
+
+  enableFormwizard: ->
+    @form.formwizard
+      formPluginEnabled: true,
+      validationEnabled: true,
+      focusFirstInput: true,
+      historyEnabled: true,
+      disableUIStyles: true,
+      inDuration: 0,
+      linkClass: "_ht_link",
+      remoteAjax: this.ajaxEvents(true), # adds first Ajax event
+      formOptions:
+        success: (data) =>
+          console.log "Successful form POST"
+        beforeSubmit: (data) =>
+          console.log "Sending these data to the server: #{$.param(data)}"
+
+  htMetaHTML: (name) ->
+    """<input type="hidden" name="_ht_meta[#{name}]" id="_ht_#{name}" value="" />"""
+
+  setHTMeta: (key, value) ->
+    $meta = @form.find("input:hidden#_ht_#{key}")
+    if $meta.length is 0
+      $meta = @form.prepend(this.htMetaHTML(key)).find("#_ht_#{key}")
+    $meta.val(value)
+
+  clearHTMeta: (key) ->
+    @form.find("input:hidden#_ht_#{key}").remove()
+
+  setCurrentStepField: ->
+    stepId = this.currentStepId()
+    this.setHTMeta("step", stepId)
+    console.log "Current form step: #{stepId}"
+
+  clearNextStepField: ->
+    this.clearHTMeta("next_step")
+
+  fieldRegex: /^([^\[]+)\[([^\]]+)\]$/
+
+  setFieldValues: (formModel, selector, callback) ->
+    $currentStep = this.currentStep()
+    $currentStep.find(selector).each (index, element) =>
+      $element = $(element)
+      elementName = $element.attr("name")
+      if elementName? and elementName.search(@fieldRegex) isnt -1
+        [_, modelName, fieldName] = elementName.match(@fieldRegex)
+        if formModel[modelName]? and formModel[modelName][fieldName]?
+          fieldValue = formModel[modelName][fieldName]
+          callback($element, fieldValue) if fieldValue?
+
+  fillTextFields: (formModel) ->
+    this.setFieldValues formModel, "input:text", ($input, value) =>
+      $input.val(value)
+
+  setSelectFields: (formModel) ->
+    this.setFieldValues formModel, "select", ($select, value) =>
+      $select.find("option[value=\"#{value}\"]").attr("selected", "selected")
+
+  setCheckboxes: (formModel) ->
+    this.setFieldValues formModel, "input:checkbox", ($checkbox, value) =>
+      $checkbox.attr("checked", "checked") if value
+
+  setRadioButtons: (formModel) ->
+    this.setFieldValues formModel, "input:radio", ($radio, value) =>
+      $radio.find("[value=\"#{value}\"]").attr("checked", "checked")
+
+  setFormFields: (formModel) ->
+    this.fillTextFields(formModel)
+    this.setSelectFields(formModel)
+    this.setCheckboxes(formModel)
+    this.setRadioButtons(formModel)
+
+  createButton: (name, label) ->
+    """<input type="button" name="#{name}" value="#{label}" />"""
+
+  setButton: (name, label) ->
+    $buttonsDiv = this.currentStep().find("div.buttons")
+    switch name
+      when "next"
+        console.log "Setting submit button val to #{label}"
+        $buttonsDiv.find('input:submit').val(label)
+      when "back"
+        console.log "Setting reset button val to #{label}"
+        $buttonsDiv.find('input:reset').val(label)
+      else
+        buttonSelector = """input:button[name="#{name}"][value="#{label}"]"""
+        $existingButtons = $buttonsDiv.find(buttonSelector)
+        if $existingButtons.length == 0
+          console.log "Adding new #{name}:#{label} button"
+          $newButton = $buttonsDiv.append(this.createButton(name, label))
+          $newButton.click (event) =>
+            event.preventDefault()
+            this.goToStepId(name)
+
+  bindEvents: ->
+    @form.bind "step_shown", (event, data) =>
+      this.setCurrentStepField()
+      this.clearNextStepField()
+      this.setFormFields(htData.formModel)
+
+      buttons = this.buttons[this.currentStepId()]
+      if buttons?
+        this.setButton(name, label) for own name, label of buttons
+
+      if data.previousStep is data.firstStep
+        console.log "Adding additional Ajax events"
+        # adds additional Ajax events now that we have the update URL
+        @form.formwizard("option", remoteAjax: this.ajaxEvents())
+
+    @form.bind "after_remote_ajax", (event, data) =>
+      if htData.wizardMetadata?.currentStep.buttons?
+        stepId = htData.wizardMetadata.currentStep.fieldset
+        this.buttons[stepId] = htData.wizardMetadata.currentStep.buttons
+
+      if htData.wizardMetadata?.currentStep.repeatOf?
+        this.repeatStep(htData.wizardMetadata.currentStep)
+      else
+        this.showStep(htData.wizardMetadata.currentStep)
+
+$ ->
+  $form = $("form.wizard")
+  if htData? and !htWizard?
+    console.log "Creating new HatTrickWizard instance"
+    window.htWizard = new HatTrickWizard($form, htData.wizardMetadata)

data/app/views/hat_trick/_wizard_meta.html.erb

@@ -0,0 +1 @@
+<%= include_gon(:namespace => 'htData', :camel_case => true) %>

data/hat-trick.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "hat_trick/version"
+
+Gem::Specification.new do |s|
+  s.name        = "hat-trick"
+  s.version     = HatTrick::VERSION
+  s.authors     = ["Wes Morgan"]
+  s.email       = ["cap10morgan@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Rails wizards done right}
+  s.description = %q{Combines jQuery FormWizard, validation_group, and gon for the perfect triple-play of Rails wizarding.}
+
+  s.rubyforge_project = "hat-trick"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "mocha"
+  s.add_development_dependency "debugger"
+
+  s.add_runtime_dependency "rails", "~> 3.1"
+  s.add_runtime_dependency "validation_group"
+  s.add_runtime_dependency "gon"
+end

data/lib/hat-trick.rb

@@ -0,0 +1,8 @@
+require "hat_trick/version"
+require "active_support"
+require "active_support/core_ext/module"
+require "hat_trick/rails_engine"
+require "hat_trick/dsl"
+require "gon"
+
+::ActionController::Base.send(:include, HatTrick::DSL)

data/lib/hat_trick/controller_hooks.rb

@@ -0,0 +1,118 @@
+require 'hat_trick/model_methods'
+
+module HatTrick
+  module ControllerHooks
+    extend ActiveSupport::Concern
+
+    included do
+      alias_method_chain :render, :hat_trick
+    end
+
+    def self.def_action_method_aliases(action_methods)
+      action_methods.each do |meth|
+        Rails.logger.info "Aliasing #{meth}"
+        module_eval <<-RUBY_EVAL
+          def #{meth}_with_hat_trick(*args)
+            Rails.logger.info "#{meth}_with_hat_trick called"
+            #{meth}_hook(*args) if respond_to?("#{meth}_hook", :include_private)
+            common_hook(*args)
+            #{meth}_without_hat_trick(*args)
+          end
+          private "#{meth}_with_hat_trick"
+        RUBY_EVAL
+      end
+      true
+    end
+
+    private
+
+    def params_model_name
+      params.each do |k,v|
+        return class_name(k) if v.is_a?(Hash) && is_model?(k)
+      end
+      nil
+    end
+
+    def is_model?(model_name)
+      begin
+        class_name(model_name).constantize
+      rescue NameError
+        return false
+      end
+      true
+    end
+
+    def class_name(hash_key)
+      hash_key.to_s.camelize
+    end
+
+    def model_class
+      model_name = params_model_name
+      return nil if model_name.nil?
+      begin
+        model_class = params_model_name.constantize
+      rescue NameError
+        Rails.logger.error "Could not find model class #{params_model_name.camelize}"
+        nil
+      else
+        model_class
+      end
+    end
+
+    def setup_validation_group_for(wizard_step)
+      klass = model_class
+      return if klass.nil?
+      step_name = wizard_step.name
+      validation_groups = ::ActiveRecord::Base.validation_group_classes[klass] || []
+      unless validation_groups.include?(step_name)
+        klass.validation_group(step_name, :fields => params.keys)
+      end
+      HatTrick::ModelMethods.set_current_validation_group_for(model_class, step_name)
+      unless klass.included_modules.include?(HatTrick::ModelMethods)
+        klass.send(:include, HatTrick::ModelMethods)
+      end
+    end
+
+    def create_hook(*args)
+      setup_validation_group_for(ht_wizard.current_step)
+    end
+
+    def update_hook(*args)
+      setup_validation_group_for(ht_wizard.current_step)
+    end
+
+    def common_hook(*args)
+      # nothing here for now
+    end
+
+    def render_with_hat_trick(*args)
+      if args.first.has_key?(:json)
+        model = args[0][:json]
+        ht_wizard.model = model
+      end
+
+      if params.has_key?('_ht_meta')
+        next_step = params['_ht_meta']['next_step']
+        ht_wizard.advance_step(next_step)
+      end
+
+      wizard_metadata = {
+        :url => ht_wizard.current_form_url,
+        :method => ht_wizard.current_form_method,
+        :currentStep => ht_wizard.current_step,
+      }
+
+      # this sets the wizard_metadata for the initial page load
+      gon.wizard_metadata = wizard_metadata
+
+      if ht_wizard.model && args[0].has_key?(:json)
+        # this sets the wizard metadata for subsequent AJAX requests
+        args[0][:json] = { :formModel => ht_wizard.model,
+                           :wizardMetadata => wizard_metadata }
+        args[0][:json].merge! ht_wizard.include_data
+      end
+
+      render_without_hat_trick(*args)
+    end
+  end
+end

data/lib/hat_trick/dsl.rb

@@ -0,0 +1,123 @@
+require 'hat_trick/wizard_definition'
+require 'hat_trick/controller_hooks'
+
+module HatTrick
+  module DSL
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def wizard(&block)
+        if block_given?
+          include HatTrick::DSL::ControllerInstanceMethods
+          include HatTrick::ControllerHooks
+
+          @wizard_def = HatTrick::WizardDefinition.new
+
+          @wizard_dsl = HatTrick::DSL::WizardContext.new(@wizard_def)
+          @wizard_dsl.instance_eval &block
+
+        else
+          raise ArgumentError, "wizard called without a block"
+        end
+      end
+    end
+
+    module ControllerInstanceMethods
+      extend ActiveSupport::Concern
+
+      included do
+        before_filter :setup_wizard
+      end
+
+      private
+
+      attr_reader :ht_wizard
+
+      def setup_wizard
+        wizard_def = self.class.instance_variable_get("@wizard_def")
+        @ht_wizard = wizard_def.get_wizard(self)
+
+        if params.has_key?('_ht_meta')
+          step_name = params['_ht_meta']['step']
+          @ht_wizard.current_step = step_name if step_name
+        end
+      end
+    end
+
+    class WizardContext
+      attr_reader :wizard_def
+      attr_accessor :wizard
+
+      delegate :model, :previously_visited_step, :to => :wizard
+
+      def initialize(wizard_def)
+        @wizard_def = wizard_def
+      end
+
+      def step(name, args={}, &block)
+        wizard_def.add_step(name, args)
+        instance_eval &block if block_given?
+      end
+
+      def next_step(name=nil)
+        if name.nil?
+          wizard.next_step
+        else
+          raise "next_step should only be called from an after block" if wizard.nil?
+          step = wizard.find_step(name)
+          wizard.current_step.next_step = step
+        end
+      end
+
+      def repeat_step(name)
+        repeated_step = wizard_def.find_step(name)
+        raise ArgumentError, "Couldn't find step named #{name}" unless repeated_step
+        new_step = repeated_step.dup
+        # use the repeated step's fieldset id
+        new_step.fieldset = repeated_step.fieldset
+        # but use the current step's name
+        new_step.name = wizard_def.last_step.name
+        if wizard
+          # TODO: Might turn all these into run-time methods; which would get
+          # rid of this wizard / wizard_def distinction
+        else
+          # replace the step we're in the middle of defining w/ new_step
+          wizard_def.replace_step(wizard_def.last_step, new_step)
+        end
+      end
+
+      def skip_this_step
+        if wizard
+          wizard.skip_step(wizard.current_step)
+        else
+          # skip_this_step in wizard definition context means the step
+          # can be explicitly jumped to, but won't be in the normal flow
+          wizard_def.last_step.skipped = true
+        end
+      end
+
+      def button_to(name, options=nil)
+        if wizard
+          raise "button_to not yet supported in before/after blocks"
+        end
+        label = options[:label] if options
+        label ||= name.to_s.humanize
+        step = wizard_def.last_step
+        step.buttons = step.buttons.merge(name => label)
+      end
+
+      def before(&block)
+        wizard_def.last_step.before_callback = block
+      end
+
+      def after(&block)
+        wizard_def.last_step.after_callback = block
+      end
+
+      def include_data(key, &block)
+        wizard_def.last_step.include_data = { key.to_sym => block }
+      end
+    end
+  end
+end
+

data/lib/hat_trick/form_helper.rb

@@ -0,0 +1,30 @@
+module HatTrick
+  module FormHelper
+    def wizard_form_for(record, *args, &proc)
+      options = args.extract_options!
+      options[:html] = { :class => 'wizard' }
+
+      wizard = controller.send(:ht_wizard)
+      wizard.start unless wizard.started?
+
+      # Do we still need these 2 lines?
+      wizard.model = record
+      controller.gon.form_model = record
+
+      options[:url] = wizard.current_form_url
+      options[:method] = wizard.current_form_method.to_sym
+
+      output = ActiveSupport::SafeBuffer.new
+      output.safe_concat(wizard_partial)
+
+      # now run the default FormBuilder & append to output
+      output << self.form_for(record, *(args << options), &proc)
+    end
+
+    private
+
+    def wizard_partial
+      controller.render_to_string(:partial => 'hat_trick/wizard_meta')
+    end
+  end
+end

data/lib/hat_trick/model_methods.rb

@@ -0,0 +1,24 @@
+module HatTrick
+  module ModelMethods
+    extend ActiveSupport::Concern
+    mattr_accessor :current_validation_group
+
+    included do
+      alias_method_chain :save, :hat_trick
+    end
+
+    def self.set_current_validation_group_for(klass, validation_group_name)
+      self.current_validation_group ||= {}
+      current_validation_group[klass.to_s.underscore] = validation_group_name
+    end
+
+    def self.current_validation_group_for(klass)
+      current_validation_group[klass.to_s.underscore]
+    end
+
+    def save_with_hat_trick(*args)
+      enable_validation_group HatTrick::ModelMethods.current_validation_group_for(self.class)
+      save_without_hat_trick(*args)
+    end
+  end
+end

data/lib/hat_trick/rails_engine.rb

@@ -0,0 +1,13 @@
+require 'hat_trick/form_helper'
+
+module HatTrick
+  class RailsEngine < ::Rails::Engine
+    # just defining this causes Rails to look for assets inside this gem
+
+    initializer 'hat-trick.form_helpers' do
+      ActiveSupport.on_load(:action_view) do
+        include HatTrick::FormHelper
+      end
+    end
+  end
+end