jeffp-wizardly 0.1.7 → 0.1.8

data/README.rdoc

@@ -117,17 +117,66 @@ for both cases
     act_wizardly_for :user, :redirect=>'/main'
   end
 
-==== Other options
+==== Options For act_wizardly_for
 
 Here's a list of options you can use in the macro
 
   :completed => '/main/finished'
   :canceled => {:controller=>'main', :action=>'canceled'}
   :skip => true
+  :guard => false
   :mask_fields => [:password, :password_confirmation] (by default)
+  :persist_model => {:once|:per_page}
+  :form_data => {:sandbox|:session}
 
 Setting the :skip option to +true+ tells the scaffold helpers to include or exclude a skip button on each page.  
 The :mask_fields options tells the scaffold generator which fields to generate as 'type=password' fields.
+:persist_model and :form_data are explained below. 
+
+
+==== Preserving Form Field Data
+
+The :form_data option controls how the form data is preserved between 
+page requests that call outside the wizard controller.  The default option setting,
+:session, keeps the form data until the wizard is complete regardless of 
+whether the user leaves the wizard and returns later.  The form
+data is preserved for the life of the session or until the user completes the wizard.
+
+The other option setting, :sandbox, clears the form data whenever 
+the user leaves the wizard before the wizard is complete.  This includes pressing
+a :cancel button, a hyperlink or plainly navigating somewhere else. 
+Upon returning to the wizard, the form is reset and the user starts fresh.
+
+The form data is always cleared once the user has completed the wizard and the
+database record has been created.
+
+==== Guarding Wizard Entry
+
+The :guard option controls how a user may enter the wizard.  If set to true, the
+default, the wizard is guarded from entry anywhere except the first page.  The wizard
+controller will automatically redirect to the first page.  When set to false, entry
+may occur at any point.  This may be useful for testing purposes and instances where
+the application needs to navigate away and return to the wizard.
+
+The guarding behavior works a little differently depending on the :form_data setting.
+When :form_data is set to :session (the default behavior), guarding only occurs
+for the initial entry.  Once a user has entered the form and started it, while
+form data is being kept, the application may thereafter enter anywhere.  On the 
+contrary, if :form_data is set to :sandbox, entry is always guarded, and once the user
+leaves the wizard, entry may only occur at the initial page (as the form data has
+been reset).
+
+==== Saving The Model
+
+The :persist_model option controls how the model is saved, either :once or :per_page.
+The default option :once, only saves the model when the wizard is completed, by the 
+user pressing a :finish button or :next button on the final page.  This method 
+prevents numerous incomplete models and possibly invalid models being saved to the
+database.
+
+The other option setting, :per_page, saves the model incrementally for each time 
+the form data validates as the user moves through the pages.  
+ 
 
 === Buttons
 
@@ -263,6 +312,24 @@ call back for this.
     end
   end
 
+=== Creating Scaffolds
+
+Wizard scaffolds can be created for any wizardly controller (one using the acts_wizardly_for
+macro).  
+
+  ./script/generate wizardly_scaffold controller_name --haml
+
+The wizardly_scaffold generator will create HTML view scaffolds by default.  Append a
+--haml option to create scaffolds in HAML.  
+
+Sometimes you have already edited views from a scaffold but want to regenerate the 
+scaffold because of changes to your model without overwriting the current views.  
+Use the --underscore option to create corresponding views with an underscore prefixing
+each page.  
+
+  ./script/generate wizardly_scaffold controller_name --underscore
+
+
 == Advanced Configuration 
 
 To be provided 

data/lib/wizardly/wizard/configuration.rb

@@ -8,14 +8,20 @@ module Wizardly
   module Wizard
     class Configuration
       attr_reader :pages, :completed_redirect, :canceled_redirect, :controller_name, :page_order
+      
+      #enum_attr :persistance, %w(sandbox session database)
 
       def initialize(controller_name, opts) #completed_redirect = nil, canceled_redirect = nil)
         @controller_name = controller_name
         @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_entry = 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]
+        @persist_model = opts[:persist_model] || :once
+        @form_data = opts[:form_data] || :session
+        raise(ArgumentError, ":persist_model option must be one of :once or :per_page", caller) unless [:once, :per_page].include?(@persist_model)
+        raise(ArgumentError, ":form_data option must be one of :sandbox or :session", caller) unless [:sandbox, :session].include?(@form_data)
         @page_order = []
         @pages = {}
         @buttons = nil
@@ -25,6 +31,8 @@ module Wizardly
         end
       end
 
+      def persist_model_per_page?; @persist_model == :per_page; end
+      def form_data_keep_in_session?; @form_data == :session; 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
@@ -37,6 +45,11 @@ module Wizardly
         index += 1 unless self.last_page?(name)
         @page_order[index]
       end
+      def previous_page(name)
+        index = @page_order.index(name)
+        index -= 1 unless self.first_page?(name)
+        @page_order[index]
+      end
       def button_for_function(name); @default_buttons[name]; end
       def buttons
         return @buttons if @buttons

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

@@ -49,9 +49,14 @@ MACRO
   def index
     redirect_to :action=>:#{self.page_order.first}
   end
+
         INDEX
         mb.string
       end
+      
+      def persist_key; 
+        @persist_key ||= "wizardly_#{controller_name.to_s.underscore}_#{model}".to_sym 
+      end      
     
       def print_page_action_method(id)
         page = @pages[id]
@@ -64,8 +69,8 @@ MACRO
       @wizard = wizard_config
       @title = '#{page.title}'
       @description = '#{page.description}'
-      h = (flash[:wizard_model]||{}).merge(params[:#{self.model}] || {}) 
-      @#{self.model} = #{self.model_class_name}.new(h)
+      h = (self.wizard_form_data||{}).merge(params[:#{self.model}] || {}) 
+      @#{self.model} = build_wizard_model(h)
       if request.post? && callback_performs_action?(:on_post_#{id}_form)
         raise CallbackError, "render or redirect not allowed in :on_post_#{id}_form callback", caller
       end
@@ -87,31 +92,33 @@ MACRO
         ONE
         if self.last_page?(id)
           mb << <<-TWO
-      return if callback_performs_action?(:on_#{id}_form_#{finish_button})
+      callback_performs_action?(:on_#{id}_form_#{finish_button})
       _on_wizard_#{finish_button}
       redirect_to #{Utils.formatted_redirect(self.completed_redirect)} unless self.performed?
         TWO
         elsif self.first_page?(id)
           mb << <<-THREE
       if button_id == :#{finish_button}
-        return if callback_performs_action?(:on_#{id}_form_#{finish_button})
+        callback_performs_action?(:on_#{id}_form_#{finish_button})
         _on_wizard_#{finish_button} if button_id == :#{finish_button}
         redirect_to #{Utils.formatted_redirect(self.completed_redirect)} unless self.performed?
         return
       end
-      session[:progression] = [:#{id}]
+      save_wizard_model! if wizard_config.persist_model_per_page?
+      # session[:progression] = [:#{id}]
       return if callback_performs_action?(:on_#{id}_form_#{next_button})
       redirect_to :action=>:#{self.next_page(id)}
         THREE
         else
           mb << <<-FOUR
       if button_id == :#{finish_button}
-        return if callback_performs_action?(:on_#{id}_form_#{finish_button})
+        callback_performs_action?(:on_#{id}_form_#{finish_button})
         _on_wizard_#{finish_button} if button_id == :#{finish_button}
         redirect_to #{Utils.formatted_redirect(self.completed_redirect)} unless self.performed?
         return
       end
-      session[:progression].push(:#{id})
+      save_wizard_model! if wizard_config.persist_model_per_page?
+      # session[:progression].push(:#{id})
       return if callback_performs_action?(:on_#{id}_form_#{next_button})
       redirect_to :action=>:#{self.next_page(id)}
         FOUR
@@ -119,7 +126,7 @@ MACRO
         
         mb << <<-ENSURE
     ensure
-      flash[:wizard_model] = h.merge(@#{self.model}.attributes)    
+      self.wizard_form_data = h.merge(@#{self.model}.attributes) if (@#{self.model} && !@completed)
     end
   end        
 ENSURE
@@ -135,6 +142,8 @@ ENSURE
   protected
   def _on_wizard_#{finish}
     @#{self.model}.save_without_validation!
+    @completed = true
+    reset_wizard_form_data
     _wizard_final_redirect_to(:completed)
   end
   def _on_wizard_#{skip}
@@ -142,13 +151,13 @@ ENSURE
   end
   def _on_wizard_#{back}
     # TODO: fix progression management
-    redirect_to(:action=>((session[:progression]||[]).pop || :#{self.page_order.first})) unless self.performed?
+    # redirect_to(:action=>((session[:progression]||[]).pop || :#{self.page_order.first})) unless self.performed?
+    redirect_to(:action=>wizard_config.previous_page(@step)) unless self.performed?
   end
   def _on_wizard_#{cancel}
     _wizard_final_redirect_to(:canceled)
   end
   def _wizard_final_redirect_to(which_redirect) 
-    flash.discard(:wizard_model)
     initial_referer = reset_wizard_session_vars
     unless self.performed?
       redir = (which_redirect == :completed ? wizard_config.completed_redirect : wizard_config.canceled_redirect) || initial_referer
@@ -175,12 +184,53 @@ ENSURE
     else
       session[:initial_referer] = nil
     end
-    flash.discard(:wizard_model)
+    if wizard_config.form_data_keep_in_session?
+      return if self.wizard_form_data  # if it has an id we've started a wizard
+    else
+      reset_wizard_form_data 
+    end
     #{guard_line}
     redirect_to :action=>:#{first_page} unless (params[:action] || '') == '#{first_page}'
-  end   
+  end
   hide_action :guard_entry
 
+  def save_wizard_model!
+    @#{self.model}.save_without_validation!
+    if wizard_config.form_data_keep_in_session?
+      h = self.wizard_form_data
+      h['id'] = @#{self.model}.id
+      self.wizard_form_data= h
+    end
+  end
+  def build_wizard_model(params)
+    if (wizard_config.persist_model_per_page? && (model_id = params['id']))
+      _model = #{self.model_class_name}.find(model_id)
+      _model.attributes = params
+      _model
+    else
+      #{self.model_class_name}.new(params)
+    end
+  end
+  hide_action :build_wizard_model, :save_wizard_model!
+
+  def wizard_form_data=(hash)
+    if wizard_config.form_data_keep_in_session?
+      session[:#{self.persist_key}] = hash
+    else
+      if hash
+        flash[:#{self.persist_key}] = hash
+      else
+        flash.discard(:#{self.persist_key})
+      end
+    end
+  end
+
+  def reset_wizard_form_data; self.wizard_form_data = nil; end
+  def wizard_form_data
+    wizard_config.form_data_keep_in_session? ? session[:#{self.persist_key}] : flash[:#{self.persist_key}]
+  end
+  hide_action :wizard_form_data, :wizard_form_data=, :reset_wizard_form_data
+
   def render_wizard_form
   end
   hide_action :render_wizard_form

data/rails_generators/wizardly_scaffold/wizardly_scaffold_generator.rb

@@ -16,6 +16,7 @@ class WizardlyScaffoldGenerator < Rails::Generator::Base
   def add_options!(opt)
     opt.on('--haml', 'Generate scaffold for haml wizard') { |v| options[:output] = :haml }
     opt.on('--ajax', 'Generate scaffold for ajax wizard') { |v| options[:output] = :ajax }
+    opt.on('--underscore', 'Append an underscore to front of each file') { |v| options[:underscore] = true }
   end
   
   
@@ -62,10 +63,11 @@ class WizardlyScaffoldGenerator < Rails::Generator::Base
       #m.directory(File.join('test/functional', controller_class_path))
       #m.directory(File.join('public/stylesheets', class_path))
 
+      underscore = options[:underscore] ? '_' : ''
       pages.each do |id, page|
         m.template(
           "form.#{view_file_ext.first}",
-          File.join('app/views', controller_class_path, controller_name, "#{id}.#{view_file_ext.last}"),
+          File.join('app/views', controller_class_path, controller_name, "#{underscore}#{id}.#{view_file_ext.last}"),
           :assigns=>{:id=>id, :page=>page}
         )
       end

metadata

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