hat-trick 0.0.1 → 0.1.0

data/README.md

@@ -4,7 +4,7 @@
 ## Install
     gem install hat-trick
 
-### Rails 3.2
+### Rails 3.1+
 (older versions not supported)
 
 Put this in your Gemfile:
@@ -37,8 +37,8 @@ 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
+        # after defines a callback to run after the current step is completed by the user
+        after do
           # code in this block will be exec'd in the context of your controller
           if user_signed_in?
             next_step :third_step
@@ -64,8 +64,8 @@ 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
+        # before defines a callback to run before the user sees this step
+        before do
           # code in this block will be exec'd in the context of your controller
           skip_this_step unless foo.present?
         end

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

@@ -3,21 +3,58 @@
 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()
+    this.stepShownCallback() # because we just showed the first step (or the one in the URL)
+
+  formwizardEnabled: false
+
+  linkClass: "_ht_link"
 
   buttons: {}
 
+  stepsNeedUpdate: false
+
+  stepShownCallback: ->
+    if not @formwizardEnabled
+      this.addStepClass()
+      # prevent submitting the step that happens to be the last fieldset
+      # TODO: Figure out a better way to do this
+      this.addFakeLastStep()
+      this.addDefaultButtons()
+    this.updateStepFromMetadata()
+    if not @formwizardEnabled
+      this.setupButtonsForAllSteps()
+      this.enableFormwizard() # this clobbers our button customizations for the current step
+      this.setupButtonsForCurrentStep() # so we run this to reconfigure it
+      this.bindEvents()
+    else
+      this.setupButtonsForCurrentStep()
+      # this must be run here & after setupButtonsForCurrentStep() to support setContents()
+      if @stepsNeedUpdate
+        this.updateSteps()
+        @stepsNeedUpdate = false
+    this.setCurrentStepField()
+    this.clearNextStepField()
+    this.setFormFields(hatTrick.model)
+    this.createDummyModelField() unless this.currentStepHasModelFields()
+
+  addStepClass: ->
+    @form.find("fieldset").addClass("step")
+
+  addDefaultButtons: ($scope = @form.find("fieldset")) ->
+    hatTrick = this
+    $scope.each (index) ->
+      id = $(this).attr('id')
+      buttons =
+        next:
+          id: "#{id}_next_button"
+          label: "Next"
+      if index > 0 or hatTrick.formwizardEnabled
+        buttons['back'] =
+          id: "#{id}_back_button"
+          label: "Back"
+  
+      hatTrick.buttons[id] = buttons
+  
   findStep: (stepId) ->
     @form.find("fieldset##{stepId}")
 
@@ -26,9 +63,10 @@ class HatTrickWizard
 
   setAction: (url, method) ->
     methodLower = method.toLowerCase()
-    console.log "Setting form action to #{methodLower} #{url}"
+    # log "Setting form action to #{methodLower} #{url}"
     @form.attr("action", url)
     @form.attr("method", "post")
+    @form.formwizard("option", remoteAjax: this.ajaxEvents())
     methodField = @form.find('input[name="_method"]')
     methodField.remove()
     if methodLower isnt "post"
@@ -41,40 +79,50 @@ class HatTrickWizard
     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) ->
+  ajaxEvents: ->
     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
+      url: @form.attr("action")
+      dataType: "json"
+      # beforeSubmit: (data) =>
+      #   log "Sending these data to the server: #{JSON.stringify data}"
+      success: (serverData) =>
+        this.handleServerData serverData
+        # log "Successful form POST; got #{JSON.stringify(serverData)}"
+      error: (event, status, errorThrown) =>
+        log "Error response: #{event.status} #{status} - #{errorThrown} - #{event.responseText}"
+        try
+          appErrors = eval "(#{event.responseText})"
+        catch err
+          appErrors =
+            model:
+              unknown: [
+                "There was an error communicating with the server. TurboVote staff have been notified."
+              ]
+        this.clearErrors()
+        this.addErrorItem value[0] for key, value of appErrors.model
     ajax
 
+  getErrorListElement: ->
+    this.currentStep().find("ul.hat_trick_errors")
+
+  clearErrors: ->
+    $errorList = this.getErrorListElement()
+    $errorList.hide()
+    $errorList.empty()
+
   addErrorItem: (message) ->
-    $errorList = this.currentStep().find("ul.hat_trick_errors")
+    $errorList = this.getErrorListElement()
     if $errorList.length > 0
       $errorList.append("<li>#{message}</li>")
       $errorList.show()
@@ -84,26 +132,30 @@ class HatTrickWizard
     @form.formwizard("option", remoteAjax: this.ajaxEvents())
 
   goToStepId: (stepId) ->
-    console.log "Setting up goto #{stepId}"
-    this.setHTMeta("next_step", stepId)
+    this.setLinkField(stepId)
     @form.formwizard("next")
 
+  # TODO: Try linking to the same step rather than cloning it.
+  # I'm becoming more and more convinced that that won't work, however. And this isn't as bad as it used to be.
   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?
+    if $("fieldset##{step.name}").length is 0
+      $sourceStep = this.findStep(step.repeatOf.fieldset)
+      $clonedStep = $sourceStep.clone(true, true)
+      $clonedStep.css("display", "none")
+      $clonedStep.attr("id", step.name)
+      $sourceStep.after($clonedStep)
+      this.updateSteps()
+    this.setLinkField step.name
+
+  removeLinkField: ->
+    this.currentStep().find("input.#{@linkClass}").remove()
+
+  setLinkField: (stepId) ->
+    inputId = "_ht_link_to_#{stepId}"
+    this.setHiddenInput "_ht_step_link", stepId, inputId, @linkClass, this.currentStep()
+
+  LinkFieldSet: ->
+    this.currentStep().find("input[name='_ht_step_link']").length > 0
 
   addFakeLastStep: ->
     @form.append """<fieldset id="_ht_fake_last_step" style="display: none;" class="step"></fieldset>"""
@@ -111,27 +163,28 @@ class HatTrickWizard
   enableFormwizard: ->
     @form.formwizard
       formPluginEnabled: true,
-      validationEnabled: true,
+      validationEnabled: false,
       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)}"
+      linkClass: ".#{@linkClass}",
+      remoteAjax: this.ajaxEvents(),
+      firstStep: hatTrick.metadata.currentStep.name
+    this.formwizardEnabled = true
 
-  htMetaHTML: (name) ->
-    """<input type="hidden" name="_ht_meta[#{name}]" id="_ht_#{name}" value="" />"""
+  setHiddenInput: (name, value, id, classes = "", scope = @form) ->
+    $scope = $(scope)
+    $input = $scope.find("""input##{id}[name="#{name}"]""")
+    if $input.length is 0
+      $input = $(this.hiddenInputHTML(name, id, classes)).prependTo $scope
+    $input.val value
+
+  hiddenInputHTML: (name, id, classes = "") ->
+    """<input type="hidden" id="#{id}" name="#{name}" class="#{classes}" 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)
+    this.setHiddenInput "_ht_meta[#{key}]", value, "_ht_#{key}"
 
   clearHTMeta: (key) ->
     @form.find("input:hidden#_ht_#{key}").remove()
@@ -139,95 +192,176 @@ class HatTrickWizard
   setCurrentStepField: ->
     stepId = this.currentStepId()
     this.setHTMeta("step", stepId)
-    console.log "Current form step: #{stepId}"
 
+  # TODO: See if we still need this "next_step" ht_meta field.
   clearNextStepField: ->
     this.clearHTMeta("next_step")
+    this.removeLinkField()
 
   fieldRegex: /^([^\[]+)\[([^\]]+)\]$/
 
-  setFieldValues: (formModel, selector, callback) ->
+  setFieldValues: (model, 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]
+        if model['__name__'] is modelName and model[fieldName]?
+          fieldValue = model[fieldName]
           callback($element, fieldValue) if fieldValue?
 
-  fillTextFields: (formModel) ->
-    this.setFieldValues formModel, "input:text", ($input, value) =>
+  fillTextFields: (model) ->
+    this.setFieldValues model, "input:text", ($input, value) =>
       $input.val(value)
 
-  setSelectFields: (formModel) ->
-    this.setFieldValues formModel, "select", ($select, value) =>
+  setSelectFields: (model) ->
+    this.setFieldValues model, "select", ($select, value) =>
       $select.find("option[value=\"#{value}\"]").attr("selected", "selected")
 
-  setCheckboxes: (formModel) ->
-    this.setFieldValues formModel, "input:checkbox", ($checkbox, value) =>
+  setCheckboxes: (model) ->
+    this.setFieldValues model, "input:checkbox", ($checkbox, value) =>
       $checkbox.attr("checked", "checked") if value
 
-  setRadioButtons: (formModel) ->
-    this.setFieldValues formModel, "input:radio", ($radio, value) =>
+  setRadioButtons: (model) ->
+    this.setFieldValues model, "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")
+  setFormFields: (model) ->
+    # log "Setting form fields based on: #{JSON.stringify(model)}"
+    this.fillTextFields(model)
+    this.setSelectFields(model)
+    this.setCheckboxes(model)
+    this.setRadioButtons(model)
+
+  createButton: (name, button) ->
+    $button = $("""<input type="button" class="wizard_button" name="#{name}" value="#{button.label}" />""")
+    if button.id?
+      $button.attr("id", button.id)
+    else
+      $button.attr("id", "#{this.currentStepId()}_#{name}_#{button.label}")
+    $button.click =>
+      clickCallbackData =
+        currentStep: this.currentStepId()
+        button: $button.attr "id"
+      @form.trigger "other_button_click", clickCallbackData
+    $button
+
+  setButton: (stepId, name, button) ->
+    # log "Setting button for #{stepId} named #{name} to #{JSON.stringify(button)}"
+    $buttonsDiv = $("fieldset##{stepId}").find("div.buttons")
     switch name
       when "next"
-        console.log "Setting submit button val to #{label}"
-        $buttonsDiv.find('input:submit').val(label)
+        # log "Setting #{stepId} submit button val to #{button.label}"
+        $button = $buttonsDiv.find('input:submit')
+        unless $button.length > 0
+          $button = $('<input class="wizard_button wizard_next" type="submit" />').appendTo $buttonsDiv
+        $button.val(button.label)
+        $button.attr("id", button.id) if button.id?
       when "back"
-        console.log "Setting reset button val to #{label}"
-        $buttonsDiv.find('input:reset').val(label)
+        # log "Setting reset button val to #{button.label}"
+        $button = $buttonsDiv.find('input:reset').val(button.label)
+        unless $button.length > 0
+          $button = $('<input class="wizard_button wizard_back" type="reset" />').appendTo $buttonsDiv
+        $button.val(button.label)
+        $button.attr("id", button.id) if button.id?
       else
-        buttonSelector = """input:button[name="#{name}"][value="#{label}"]"""
+        buttonSelector = """input:button[name="#{name}"][value="#{button.label}"]"""
         $existingButtons = $buttonsDiv.find(buttonSelector)
-        if $existingButtons.length == 0
-          console.log "Adding new #{name}:#{label} button"
-          $newButton = $buttonsDiv.append(this.createButton(name, label))
+        if $existingButtons.length is 0
+          # log "Adding new #{name}:#{button.label} button"
+          $newButton = $(this.createButton(name, button)).appendTo($buttonsDiv)
           $newButton.click (event) =>
             event.preventDefault()
             this.goToStepId(name)
 
+  setupButtonsForAllSteps: ->
+    this.setupButtonsForStep $(fieldset).attr('id') for fieldset in $('fieldset')
+
+  setupButtonsForCurrentStep: ->
+    this.setupButtonsForStep this.currentStepId()
+
+  setupButtonsForStep: (stepId) ->
+    buttons = this.buttons[stepId]
+    if buttons?
+      this.setButton(stepId, name, button) for name, button of buttons
+
+  setContents: (stepPartials) ->
+    for stepName, partial of stepPartials
+      do (stepName, partial) =>
+        stepId = underscoreString stepName
+        $partial = $(partial)
+        fieldsetContents = $partial.find('fieldset').html()
+        $step = $("fieldset##{stepId}")
+        $step.html fieldsetContents
+        this.addDefaultButtons($step)
+        @stepsNeedUpdate = true
+
+  handleServerData: (data) ->
+    if data.metadata?
+      this.setAction(data.metadata.url, data.metadata.method)
+    $.extend(window.hatTrick, data) # merge new data with hatTrick
+    this.updateStepFromMetadata()
+
+  updateStepContents: ->
+    this.setContents(hatTrick.data.hatTrickStepContents)
+
+  setButtonMetadataForCurrentStep: ->
+    if hatTrick.metadata?.currentStep?
+      currentStep = hatTrick.metadata.currentStep
+      if currentStep.buttons?
+        stepId = currentStep.fieldset
+        this.buttons[stepId] = currentStep.buttons
+
+  modelName: ->
+    hatTrick.model['__name__']
+
+  createDummyModelField: ->
+    this.setHiddenInput "#{this.modelName()}[_dummy]", "1"
+
+  currentStepHasModelFields: ->
+    this.currentStep().find("input[name^='#{this.modelName()}[']").length > 0
+
+  updateStepFromMetadata: ->
+    if hatTrick.metadata?.currentStep?
+      this.updateStepContents() if hatTrick.data.hatTrickStepContents?
+      this.setButtonMetadataForCurrentStep()
+      this.createDummyModelField() unless this.currentStepHasModelFields()
+
+      currentStep = hatTrick.metadata.currentStep
+      if currentStep.repeatOf?
+        this.repeatStep(currentStep)
+      else
+        this.setLinkField(currentStep.fieldset) unless this.LinkFieldSet()
+
   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)
+      this.stepShownCallback()
 
 $ ->
-  $form = $("form.wizard")
-  if htData? and !htWizard?
-    console.log "Creating new HatTrickWizard instance"
-    window.htWizard = new HatTrickWizard($form, htData.wizardMetadata)
+  if $("form.wizard").length > 0
+    $form = $("form.wizard")
+    window.hatTrick = {} unless window.hatTrick?
+    unless window.hatTrick.wizard?
+      # log "Creating new HatTrickWizard instance"
+      window.hatTrick.wizard = new HatTrickWizard($form, hatTrick.metadata)
+
+camelizeString = (string) ->
+  re = /_([^_]*)/g
+  while matches = re.exec(string)
+    result = string.slice(0, matches.index) unless result?
+    result += "#{matches[1][0].toUpperCase()}#{matches[1].slice(1)}"
+  result = string unless result?
+  result
+
+underscoreString = (string) ->
+  re = /([A-Z]+)([a-z\d]+)/g
+  while matches = re.exec(string)
+    result = string.slice(0, matches.index) unless result?
+    result += "_#{matches[1].toLowerCase()}#{matches[2]}"
+  result = string unless result?
+  result
+
+log = (msg) ->
+  if window['console']?
+    console.log msg

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

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

data/hat-trick.gemspec

@@ -7,9 +7,9 @@ Gem::Specification.new do |s|
   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.homepage    = "https://github.com/turbovote/hat-trick"
+  s.summary     = %q{A simple DSL for creating client-side multi-step forms in Rails.}
+  s.description = %q{Hat-Trick brings together jQuery, validation_group, and Ajax to make multi-step forms awesome. It tries to insulate you from this complexity by providing a simple yet powerful DSL for defining the steps of your form and their behavior.}
 
   s.rubyforge_project = "hat-trick"
 

data/lib/hat-trick.rb

@@ -1,7 +1,7 @@
 require "hat_trick/version"
 require "active_support"
 require "active_support/core_ext/module"
-require "hat_trick/rails_engine"
+require "hat_trick/engine"
 require "hat_trick/dsl"
 require "gon"
 

data/lib/hat_trick/config.rb

@@ -0,0 +1,17 @@
+module HatTrick
+  class Config
+    attr_reader :wizard_def
+
+    def initialize(wizard_def)
+      @wizard_def = wizard_def
+    end
+
+    def create_url=(url)
+      wizard_def.configured_create_url = url
+    end
+
+    def update_url=(url)
+      wizard_def.configured_update_url = url
+    end
+  end
+end

data/lib/hat_trick/controller_helpers.rb

@@ -0,0 +1,64 @@
+module HatTrick
+  module ControllerHelpers
+
+    private
+
+    def model_key
+      params.each do |k,v|
+        return k if v.is_a?(Hash) && is_model?(k)
+      end
+      nil
+    end
+
+    def params_model_name
+      class_name model_key unless model_key.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
+      return ht_wizard.model.class if ht_wizard.model
+
+      # if that didn't work, try to grab it from the params hash
+      model_name = params_model_name
+      return nil if model_name.nil?
+
+      begin
+        model_klass = params_model_name.constantize
+      rescue NameError
+        Rails.logger.error "Could not find model class #{params_model_name.camelize}"
+        nil
+      else
+        model_klass
+      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)
+        validation_fields = params.keys # TODO: Try it without these (so only the model keys below)
+        model = model_key
+        if model
+          validation_fields += params[model].keys
+        end
+        validation_fields = validation_fields.map(&:to_sym)
+        klass.validation_group(step_name, :fields => validation_fields)
+      end
+      HatTrick::ModelMethods.set_current_validation_group_for(model_class, step_name)
+    end
+  end
+end