jeffp-wizardly 0.1.6 → 0.1.7

data/README.rdoc

@@ -146,37 +146,37 @@ See the Advanced Configuration section.
 === Callbacks
 
 The wizard macro 'act_wizardly_for' creates controller actions for each page.  
-The process for each page is conventional, but hooks (or callbacks) are available
-for the developer to change the processing.  Here's an example.  Say our model
+The processing is standard for a wizard.  Hooks or callback macros are available
+for changing or interrupting the processing.  Here's an example.  Say our model
 declares a :step4 validation_group with :username, :password, and 
 :password_confirmation fields.  We'd like to handle this step specifically.
 
   class SignupController < ApplicationController
     act_wizardly_for :user, :redirect=>'/main'
 
-    def on_invalid_step4_form
+    on_errors(:step4) do
       #clear the password field if errors
       @user[:password] = ''
       @user[:password_confirmation] = ''
     end
   end
 
-The above callback is only called if :step4 does not validate according to its
+The above hook macro is only called if :step4 does not validate according to its
 validation_group.  
 
-Every page has a set of callbacks.  Here's the list for our :step1 page.
+Every page has a set of callback macros.  Here's the list.
 
-  def on_get_step1_form; end    
-  def on_post_step1_form; end
-  def on_invalid_step1_form; end 
-  def on_step1_form_next; end   
-  def on_step1_form_back; end
-  def on_step1_form_cancel; end
-  def on_step1_form_finish; end
-  def on_step1_form_skip; end
+  on_get(:step)         # called just after creating model instance and before rendering a GET request
+  on_post(:step)        # called just after creating the model instance for a POST request
+  on_errors(:step)      # called after on_post callback if the form is invalid according to validation group
+  on_next(:step)        # called on a valid form when :next button is pressed
+  on_back(:step)        # called when the :back button is pressed
+  on_cancel(:step)      # called when the :cancel button is pressed
+  on_finish(:step)      # called on a valid form when the :finish button is pressed
+  on_skip(:step)        # called when the skip button is pressed
 
-Each callback is defined for the controller object, thus giving it access to all
-controller variables and methods just as any other action method.  Each callback
+The block for each hook is called in the controller context, thus giving it access to all
+controller variables and methods just as any controller action method.  Each callback
 has access to the model through an instance variable using the model's name.  So
 for instance if our model is :user, the instance variable is '@user'.  Each 
 wizard page action also defines a @title, @description and @step instance variable.
@@ -190,6 +190,59 @@ redirect caused by a button click in the view.
 Important: Method names for button callbacks will change if you change the name
 of the button.  For general use, this is not an issue.  See the Advanced Configuration section.
 
+The order of callbacks for a GET request is as follows:
+
+  on_back
+  on_skip
+  on_cancel
+  ...on_'custom_button'...
+  on_get
+  render_wizard_form
+
+Of course, only one of the button callbacks (back, skip or cancel) may occur for any single request, and 
+any one of them may keep the on_get from being called if they render or redirect. 
+:next and :finish button callbacks only occur for POST requests.  The on_get callback
+occurs just before rendering, and may itself render or redirect.  The on_get callback
+is an opportunity to modify or check the model fields before rendering.
+
+The order of callbacks for a POST request is as follows:
+
+  on_post
+  on_back
+  on_skip
+  on_cancel
+  ...on_'custom_button'...
+  on_errors
+    render_wizard_form  # only if errors
+  on_next
+  on_finish
+  
+In contrast to the on_get callback, the on_post callback occurs first.  It is an 
+opportunity to modify the model instance values (the model instance has already been 
+created from the post parameters).  The on_post method does not permit any rendering
+or redirecting since the back, skip and cancel buttons have not been evaluated and 
+may require precedence over flow control.  on_errors is called only for an invalid
+form and the render callback (see below) is called only if there are errors.  Either
+on_next or on_finish are called if the form is valid.  on_next is the default if a 
+'Finish' button is not pressed.  on_next by default moves to the next page, while
+on_finish saves the model and redirects to the :completed redirect.
+
+The argument of the callback macro indicates for which pages the block should be 
+called.  You can indicate as many pages or :all as shown.
+
+  on_post(:step1) do
+    ...
+  end
+  on_back(:step2, :step3, :step4) do
+    ...
+  end
+  on_get(:all) do
+    ...
+  end
+
+Indicating a form that does not exist raises a CallbackError.
+
+
 === Rendering Callback
 
 For anyone needing to handle rendering in a special way, wizardly provides a render
@@ -198,7 +251,7 @@ call back for this.
   class SignupController < ApplicationController
     act_wizardly_for :user, :redirect=>'/main'
     
-    def render_wizard_page
+    def render_wizard_form
       respond_to do |format|
         format.html
         format.xml { render_xml(@step) }

data/lib/wizardly/action_controller.rb

@@ -24,6 +24,7 @@ module Wizardly
         self.class_eval @wizard_config.print_page_action_methods
         self.class_eval @wizard_config.print_callbacks
         self.class_eval @wizard_config.print_helpers
+        self.class_eval @wizard_config.print_callback_macros
       end
     end
 

data/lib/wizardly/wizard/configuration.rb

@@ -14,7 +14,7 @@ module Wizardly
         @completed_redirect = opts[:redirect] || opts[:completed] || opts[:when_completed] #format_redirect(completed_redirect)
         @canceled_redirect = opts[:redirect] || opts[:canceled] || opts[:when_canceled]
         @allow_skipping = opts[:skip] || opts[:allow_skip] || opts[:allow_skipping] || false
-        @guard = opts.key?(:guard) ? opts[:guard] : true        
+        @guard_entry = opts.key?(:guard) ? opts[:guard] : true        
         @password_fields = opts[:mask_fields] || opts[:mask_passwords] || [:password, :password_confirmation]
         @page_order = []
         @pages = {}
@@ -25,7 +25,6 @@ module Wizardly
         end
       end
 
-      def guard?; @guard; end
       def model; @wizard_model_sym; end
       def model_instance_variable; "@#{@wizard_model_sym.to_s}"; end
       def model_class_name; @wizard_model_class_name; end

data/lib/wizardly/wizard/configuration/methods.rb

@@ -2,6 +2,40 @@ module Wizardly
   module Wizard
     class Configuration
       
+      def print_callback_macros
+        macros = [ 
+          %w(on_post on_post_%s_form),
+          %w(on_get on_get_%s_form),
+          %w(on_errors on_invalid_%s_form)
+        ]
+        self.buttons.each do |id, button|
+          macros << ['on_'+ id.to_s, 'on_%s_form_'+ id.to_s ]
+        end
+        mb = StringIO.new
+        macros.each do |macro|
+          mb << <<-MACRO
+  def self.#{macro.first}(*args, &block)
+    return if args.empty?
+    all_forms = #{page_order.inspect}
+    if args.include?(:all)
+      forms = all_forms
+    else
+      forms = args.map do |fa|
+        unless all_forms.include?(fa)
+          raise(ArgumentError, ":"+fa.to_s+" in callback #{macro.first} is not a form defined for the wizard", caller)
+        end
+        fa
+      end
+    end
+    forms.each do |form|
+      self.send(:define_method, sprintf("#{macro.last}", form.to_s), &block )
+    end
+  end
+MACRO
+        end
+        mb.string
+      end
+      
       def print_page_action_methods
         mb = StringIO.new
         self.pages.each do |id, p|
@@ -33,7 +67,7 @@ module Wizardly
       h = (flash[:wizard_model]||{}).merge(params[:#{self.model}] || {}) 
       @#{self.model} = #{self.model_class_name}.new(h)
       if request.post? && callback_performs_action?(:on_post_#{id}_form)
-        raise CallbackError, "render or redirect not allowed in :filter_params_#{id}_page callback", caller
+        raise CallbackError, "render or redirect not allowed in :on_post_#{id}_form callback", caller
       end
       button_id = check_action_for_button
       return if performed?
@@ -130,7 +164,7 @@ ENSURE
         next_id = self.button_for_function(:next).id
         finish_id = self.button_for_function(:finish).id
         first_page = self.page_order.first
-        guard_line = self.guard? ? '' : 'return #guard entry disabled'
+        guard_line = @guard_entry ? '' : 'return #guard entry disabled'
       <<-HELPERS
   protected
   def guard_entry

data/rails_generators/wizardly_controller/templates/controller.rb.erb

@@ -11,6 +11,8 @@ class <%= controller_class_name %> < ApplicationController
 
   <%= helper_methods %>
 
+  <%= callback_macro_methods %>
+
   private
   def methodize_button_name(value)
     value.to_s.strip.squeeze(' ').gsub(/ /, '_').downcase

data/rails_generators/wizardly_controller/wizardly_controller_generator.rb

@@ -43,6 +43,9 @@ class WizardlyControllerGenerator < Rails::Generator::Base
   def helper_methods
     @wizard_config.print_helpers
   end
+  def callback_macro_methods
+    @wizard_config.print_callback_macros
+  end
   
   protected
   # Override with your own usage banner.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: jeffp-wizardly
 version: !ruby/object:Gem::Version 
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors: 
 - Jeff Patmon
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-10 00:00:00 -07:00
+date: 2009-08-11 00:00:00 -07:00
 default_executable: 
 dependencies: []