jeffp-wizardly 0.1.8.4 → 0.1.8.5

data/README.rdoc

@@ -4,10 +4,6 @@
 
 == Resources
 
-Examples
-
-* http://github.com/jeffp/wizardly-examples
-
 Source
 
 * git://github.com/jeffp/wizardly.git
@@ -15,6 +11,10 @@ Source
 Install
 
 * sudo gem install jeffp-wizardly --source=http://http://gems.github.com
+
+Examples
+
+* http://github.com/jeffp/wizardly-examples
 	
 == Description
 
@@ -25,26 +25,52 @@ produces the scaffolding and controller of a multi-step wizard.
 Features include:
 * Model-based definition
 * Wizard controller macro
-* Wizard scaffolding generator
-* Default wizard buttons
-* Custom button creation
-* Page and button callbacks
+* Wizard scaffold generator
+* Simple wizard page helpers
+* Default and customizable wizard buttons
+* Page and wizard callbacks
+* High in Convention
+* Rich in Configuration
+
+== Example
+
+Create a working controller wizard for any model in 3 steps.  Here's how:
+
+Step 1: Define validation groups for your model.
+
+  class User < ActiveRecord::Base    
+    validation_group :step1, :fields=>[:first_name, :last_name]
+    validation_group :step2, :fields=>[:age, :gender]
+    ...
+  end
+
+Step 2: Tell your controller to act 'wizardly'.
+
+  class SignupController < ApplicationController
+    act_wizardly_for :user
+  end
+
+Step 3: Generate a 'wizardly' scaffold for your controller.
+
+  ./script/generate wizardly_scaffold signup
+
+You are ready to go: start your servers.
+
+General usage and configuration of wizardly follows.  See the examples at
+
+  http://github.com/jeffp/wizardly-examples
 
 == Setup
 
 Put the following in your application's config block in config/environment.rb
 
-  config.gem 'jeffp-wizardly', :lib=>'wizardly'
+  config.gem 'jeffp-wizardly'
 
 and run the install gems rake task on your application
 
   rake gems:install
 
-For any rails app, run the following to install wizardly rake tasks (optional)
-
-  ./script/generate wizardly_app
-
-== Recommendations
+=== Setup Recommendations
 
 Wizardly uses sessions.  It is recommended you use a session store other than the  
 default cookies store to eliminate the 4KB size restriction.  To use the active 
@@ -59,83 +85,103 @@ And set up the sessions table in the database
 
 Use the MemCached session store for higher performance requirements.
 
-== Example
-
-Create a working controller wizard for any model in 3 steps.  Here's how:
-
-Step 1: Define validation groups for your model.
+== Inspecting A Wizard Controller
 
-  class User < ActiveRecord::Base    
-    validation_group :step1, :fields=>[:first_name, :last_name]
-    validation_group :step2, :fields=>[:age, :gender]
-    ...
-  end
+This is optional, but for any rails app, you can install wizardly rake tasks
+by running 
 
-Step 2: Tell your controller to act 'wizardly'.
+  ./script/generate wizardly_app
 
-  class SignupController < ApplicationController
-    act_wizardly_for :user
-  end
+Once installed, you can run the config rake task to inspect a wizardly controller
 
-Step 3: Generate a 'wizardly' scaffold for your controller.
+  rake wizardly:config name=controller_name
 
-  ./script/generate wizardly_scaffold signup
+The controller_name you give it must have a +act_wizardly_for+ declaration for 
+an existing active record model and database table.  (Don't forget to migrate 
+your database)  The rake task will display the wizard's buttons, pages and fields
+along with other configuration information.
 
-You are ready to go.
+== The Basic Wizard
 
-General usage and configuration of wizardly follows.  See the examples at
+Wizardly creates a controller action for each validation group 
+in the model.  Likewise, the wizardly scaffold generates a view named for each 
+corresponding action.  
 
-  http://github.com/jeffp/wizardly-examples
+=== Action Instance Variables
 
-== Usage
+The actions automatically instantiate a few instance variables: @step, @wizard,
+@title and @{model_name}.  @step contains the symbol corresponding to 
+the action name and is used in the wizard view helpers.  @wizard references
+the wizard configuration object and is primarily used by the view helpers.  
+@title contains the string name of the action by default and is used in the scaffolding.  Finally and
+most importantly of all, the action instantiates an instance of the model.  For
+instance, if the model is :account_user for AccountUser class, the action instantiates
+an @account_user instance.
 
-=== Default Behavior and Scaffolding Configuration
+=== Flow
 
-The wizardly_scaffold generator produces an html view for each validation_group
-declared in the model.  The wizard progresses to each page in the same order of 
-the validation_group(s) in the model.  Buttons for navigating
-the wizard are included on each page.
+The page-to-page flow of the wizard is assumed to occur in the order that the
+validation groups were declared in the model.  A 'next' button progresses to the 
+next page in the order; a 'back' button progresses to the previous page in the order.
+The first page in the order will have no 'back' button.  The final page in the order
+will no 'next' button, but instead have a 'finish' button which completes the wizard
+by saving the model instance to the database.  Every page will have a 'cancel' button.
 
-You can view a wizardly controller's configuration by using the wizardly:config
-rake task.  First you'll need to install it if you already have not
+=== Automatic Page Progression Tracking
 
-  ./script/generate wizardly_app
+The default progression is linear, progressing from one page to the next in the defined
+order.  In the default case, the 'back' button simply jumps back to the previous page. 
+However, the developer can create more complex flows by jumping and skipping pages in 
+the action callback methods.  Wizardly tracks the forward progression
+through a wizard and back tracks accordingly for the 'back' button.  
 
-Then you can call the rake task for any controller configured with the 
-'act_wizardly_for' macro
+=== Wizard Entrance Guarding
 
-  rake wizardly:config name=signup
+Since there is an assumed order for the wizard, entering the wizard at a later page
+makes no sense.  Wizardly, however, guards entry to the wizard.  If the user has 
+never entered the wizard, then entry is always redirected to the first page.  If the
+user has partially completed the wizard and is allowed to re-enter the wizard to
+complete it, wizardly only allows entry at or before the page previously completed.
 
-Substitute the name of any wizardly controller for 'signup'.
+The guarding feature can be disabled for testing or other purposes.
 
+== Basic Usage
 
 === Completing and Canceling
 
 Once a user has entered a wizard, there are two ways they can leave, either by
-completing or canceling the wizard.
+completing or canceling the wizard.  The redirects for these two cases need to 
+be defined.  If neither are defined, then the HTTP_REFERER on first entry of the 
+wizard is used as the redirect for both cases. 
 
-The above example is pretty simple.  In fact, no redirects have been defined for
-completing or canceling the wizard in the above example so the wizardly controller
-uses the HTTP_REFERER for both cases.  What if there is no referer?  The controller
-raises a RedirectNotDefined error.  Let's remedy this problem with some options
-in the macro.
+The 3-step example given above is very simple.  In fact, no redirects have been defined for
+completing or canceling the wizard so the wizardly controller
+will use the HTTP_REFERER for both cases.  If there is no HTTP_REFERER, the controller
+raises a RedirectNotDefined error.  Let's remedy this problem by adding redirect options
+to the macro.
 
   class SignupController < ApplicationController
-    act_wizardly_for :user, :completed=>'/main/finished', 
+    act_wizardly_for :user, 
+      :completed=>'/main/finished', 
       :canceled=>{:controller=>:main, :action=>:canceled}
   end
 
 Now whether the user completes or cancels the wizard, the controller knows
-how to redirect.  Alternately, if you want to redirect to the same page 
-for both cases
+how to redirect.  If both canceling and completing the wizard redirect to the 
+same place, the following option takes care of both
 
   class SignupController < ApplicationController
     act_wizardly_for :user, :redirect=>'/main'
   end
 
-==== Options For act_wizardly_for
+These redirects are static, and may not suffice for all cases.  In the event
+that the redirect needs to be determined at run-time, the developer can use a 
+number of page callback macros to intercede in the wizard logic and redirect 
+as needed on canceling or completion.  See Callbacks below.
+
+==== Controller Options
 
-Here's a list of options you can use in the macro
+Here's a list of options for the +act_wizardly_for+ controller macro
 
   :completed => '/main/finished'
   :canceled => {:controller=>'main', :action=>'canceled'}
@@ -145,26 +191,26 @@ Here's a list of options you can use in the macro
   :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.  
+Setting the :skip option to +true+ tells the scaffold helpers to include 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. 
-
+Remaining options 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 
+The :form_data option controls how the form data is preserved when a user
+leaves or navigates to a page outside of the wizard before completing the wizard.  
+The default setting, :session, maintains 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 other 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.
+Upon returning to the wizard, the form is reset and the user starts fresh from the 
+first page.
 
 The form data is always cleared once the user has completed the wizard and the
-database record has been created.
+record has been committed.
 
 ==== Guarding Wizard Entry
 
@@ -182,7 +228,7 @@ contrary, if :form_data is set to :sandbox, entry is always guarded, and once th
 leaves the wizard, entry may only occur at the initial page (as the form data has
 been reset).
 
-==== Saving The Model
+==== Persisting 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 
@@ -205,110 +251,182 @@ can add :skip functionality to all pages by adding an option to the macro
   end
 
 You can create, customize and change buttons for any controller and any page. 
-See the Advanced Configuration section.
+See the Button Customization section.
 
 
 === Callbacks
 
-The wizard macro 'act_wizardly_for' creates controller actions for each page.  
-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.
+There are two kinds of callbacks -- general and action.  Action callbacks occur
+based on a controller action.  General callbacks occur based on a general wizard event.
+
+==== Action Callback Macros
+
+Action callback macros are available for injecting code and control into the wizard 
+logic for each page.  For instance, say our model
+declares the following validation group
+
+  validation_group :step4, :fields=>[:username, :password, :password_confirmation]
+
+In the case that there's a validation error, we'd like to clear the password fields before re-rendering 
+when one of the fields is invalid.  For this purpose, we can use the on_errors action callback macro.
 
   class SignupController < ApplicationController
     act_wizardly_for :user, :redirect=>'/main'
 
     on_errors(:step4) do
-      #clear the password field if errors
       @user[:password] = ''
       @user[:password_confirmation] = ''
     end
   end
 
-The above hook macro is only called if :step4 does not validate according to its
-validation_group.  
-
-Every page has a set of callback macros.  Here's the list.
+Here's the list of action callbacks macros that the developer can use for any action
 
-  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
+  on_cancel(:step)      # called when the :cancel button is pressed
+  on_next(:step)        # called when the :next button is pressed for a valid form (post only)
+  on_finish(:step)      # called when the :finish button is pressed for a valid form (post only)
 
-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.
-These are primarily used for scaffolding.  The @step holds the name of the current
-validation group, ie. :step1, step2, ... in our examples.
+  on_post(:step)        # called at the beginning of a POST request
+  on_get(:step)         # called before rendering a GET request
+  on_errors(:step)      # called before re-rendering the form after form invalidation (on a POST request)
 
-Notice the last five callbacks are related to the default wizard buttons.  Each
+The first five callbacks are related to the wizard buttons.  Each
 callback gives the developer a chance to intervene before the impending render or 
-redirect caused by a button click in the view.  
+redirect caused by a button click.
+
+Each callback macro consists of a list of actions or the symbol :all as the argument 
+and a block defining the code.  For example
+
+  on_post(:step1) do
+    ...
+  end
+  on_back(:step2, :step3, :step4) do
+    ...
+  end
+  on_get(:all) do
+    ...
+  end
+
+Passing a non-existing action name raises a CallbackError.
+
+The block in a callback is called in the controller context, thus giving it access to all
+controller variables and methods including the model instance, controller methods 
+like +redirect_to+, and controller variables like params, request, response and session.  
+The model instance variable is available for all action callback macros.
+
+==== The Wizard's Action Request Cycle
 
-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 wizard page is first requested through a GET to an action.  In this GET request, 
+the wizard action creates the instance variables @step, @title and @wizard, and 
+builds the model instance variable @{model_name}.  Action callbacks may occur in the
+following order.
 
-The order of callbacks for a GET request is as follows:
+  #GET request callback order
 
-  on_back
-  on_skip
-  on_cancel
-  ...on_'custom_button'...
+  on_back, on_skip, on_cancel
   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:
+If the wizard detects that a back, skip or cancel button has been pressed, the 
+corresponding callback is called if implemented.  If the developer does nothing
+in the callbacks, default handlers will redirect accordingly and the on_get and 
+render_wizard_form callbacks will not be called (Note: render_wizard_form is a
+general callback and is included for completeness) Once rendered, the page is 
+presented to the user with a selection of fields and 
+wizard buttons for posting the form.  
+
+When the form data is returned by a POST request, the action creates the instance
+variables and builds the model instance using the form data.  The on_post callback
+is called at the beginning of the post, then the wizard checks for back, skip and 
+cancel buttons.  If neither of those buttons were pressed, it proceeds to validate
+the form, calling the on_errors callback if form validation fails, re-rendering and
+sending the page with errors.  If validation succeeds, the action determines whether
+the POST request signifies a 'next' or a 'finish' request and calls the corresponding
+callback if implemented.  The callback order for a POST request is as indicated below. 
+(The on_completed callback is a general callback called once the wizard is completed and 
+the model has been committed to the database)
+
+  #POST request callback order
 
   on_post
-  on_back
-  on_skip
-  on_cancel
-  ...on_'custom_button'...
+  on_back, on_skip, on_cancel
   on_errors
-    render_wizard_form  # only if 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_completed   # only if completed
 
-  on_post(:step1) do
-    ...
+==== Rendering with on_get and on_errors
+
+The on_get and on_errors callbacks are called just before rendering the form.  These
+callbacks are a good place to declare extra variables needed to render the form.
+
+  on_get(:step2) do
+    setup_step2_form
   end
-  on_back(:step2, :step3, :step4) do
-    ...
+
+  on_errors(:step2) do
+    setup_step2_form
   end
-  on_get(:all) do
-    ...
+ 
+  def setup_step2_form
+    @contact_options = [%w(phone 1), %w(email 2), %w(mail, 3)]
+  end
+
+If you have a variable that goes in every page, render_wizard_form is called
+for every page.
+
+==== Modifying form data with on_post
+
+The on_post callback is the first callback in the chain of a POST request and 
+is a good place to modify form input such as adding capitalization to a form.
+Modification should happen through the model instance variable and not the 
+controller's params variable.
+
+Redirecting and rendering are not allowed in the on_post callback.  Doing so will
+raise an error.
+
+==== Modifying Flow with on_next
+
+on_next is called when a form has posted validly and the wizard is ready to move 
+to the next page.  This is a good opportunity to modify form flow for more complex
+forms by redirecting and skipping pages.  See the STI Model example in 
+http://github.com/jeffp/wizardly-examples for an example of a wizard with two paths
+based on user input.
+
+  on_next(:step1) do
+    redirect_to(:action=>:step3) if @contributor.is_volunteer?
+  end
+  on_next(:step2) do
+    redirect_to(:action=>:step4)
   end
 
-Indicating a form that does not exist raises a CallbackError.
+In the above example, :step 3 is a page for a volunteer, and :step2 is a page for
+a non-volunteer.
+
+==== Completing the wizard with on_next
 
+Sometimes you may want to complete the wizard based on user input rather than a
+'finish' button.  You can call the +complete_wizard+ method. See the completing
+wizard programmatically example below.
 
-=== Rendering Callback
+==== Final modifications with on_finish
+
+on_finish callback is called when the user presses a 'finish' button and form
+validation is successful (for the validation_group).  on_finish is a good place
+to make any final modifications before the model instance is committed to the 
+database.
+
+Alternatively, if you want to stop the completion process, you can call the 
++do_not_complete+ method in the on_finish callback.  
+
+=== General Callback Macros
+
+There are two general callback macros: render_wizard_form and on_completed.  These
+are not tied to any action or set of actions.
+
+==== render_wizard_form
 
 For anyone needing to handle rendering in a special way, wizardly provides a render
 call back for this.
@@ -328,7 +446,22 @@ call back for this.
     end
   end
 
-=== Completing the Wizard Programmatically
+==== Dynamic redirecting with on_completed
+
+The on_completed callback is called once the model instance has been committed to 
+the database.  If you need any fields generated from committing the model, such 
+as an ID, to redirect on completion, the
+on_completed callback is the place to do this.
+
+  on_completed do
+    redirect_to post_path(@post)
+  end
+
+=== Helper methods
+
+Wizardly provides some helper methods which are useful in callbacks.
+
+==== Completing the Wizard Programmatically
 
 Perhaps you want to complete a wizard based off of a test instead of a button
 click.  You can do this in your callbacks by calling the +complete_wizard+ method.
@@ -344,6 +477,18 @@ You can change the redirect dynamically by passing it to the method.
 
   complete_wizard(some_model_path)
 
+==== Rerendering from a callback
+
+Sometimes it is useful to re-render the form and send the response to the user immediately.
+Wizardly provides a +render_and_return+ method for this purpose.  If a callback is
+triggered from a POST request, and the callback needs to re-render, this is the method.
+
+  on_back(:step2) do
+    if (something_mandatory_not_selected)
+      flash[:notice] = 'Please make a selection before going back'
+      render_and_return
+    end
+  end
 
 === Creating Scaffolds
 
@@ -368,9 +513,90 @@ You can create a scaffold using image_submit_tag by doing the following:
 
 Default button images are provided under the public/images/wizardly/ directory.
 
-== Advanced Configuration 
+== Button Customization 
+
+The buttons used by the wizard and the view helpers can be customized as follows.    
+
+=== Changing Names of Default Wizard Buttons
+
+The wizard supports five default button actions-- :next, :back, :cancel, :skip and
+:finish.  The default names for the buttons are the corresponding capitalized
+string -- 'Next', 'Back', 'Cancel', 'Skip' and 'Finish'.
+
+The default button names can be customized in the +act_wizardly_for+ code block
+
+  class UserSignupController < ApplicationController
+    act_wizardly_for :user, :redirect=>'/main/index' do
+      change_button(:back).name_to('Previous Page')
+      change_button(:finish).name_to('Save and Return')
+    end
+  end
+
+With the above code, the 'Back' button will now be named 'Previous Page' and the 'Finish'
+button is renamed to the longer name 'Save and Return'.  Notice that symbols are used
+to determine the default button, but the customized name is passed.  A new symbol
+representing the change is created for each change, hence, for our buttons above :back
+is now referred to as :previous_page and :finish is now referred to as :save_and_return.
+
+=== Action Callbacks for Customized Buttons
+
+Changing the name of a default button also changes the name of its callback macro.  
+For instance, the on_back() and on_finish() callback macros are replaced by the following
+for the above example
+
+  on_previous_page(:step3) do
+    ...
+  end
+  on_save_and_return(:step3) do
+    ...
+  end
+
+=== Creating New Buttons
+
+Completely new buttons can be added to the wizard by passing a button name to the +create_button+ method 
+in the +act_wizardly_for+ code block
+
+  act_wizardly_for :user, :redirect=>'/main/index' do
+    change_button(:back).name_to('Previous Page')
+    change_button(:finish).name_to('Save and Return')
+    ...
+    create_button('Help')
+  end
+
+This creates a new button names 'Help' represented by the :help symbol.  Actions for this
+button must be defined by the on_help() callback macros for each and every page.
+
+  on_help(:all) do
+    case @step
+    when :step1 then ...
+    when :step2 then ...
+    end
+  end
+
+=== Setting Buttons for a Wizard Page
+
+Any new button needs to be explicitly added to every page it will show up on.  Each
+pages button set can be set in the +act_wizardly_for+ code as follows
+
+  act_wizardly_for :user, :redirect=>'/main/index' do
+    change_button(:back).name_to('Previous Page')
+    change_button(:finish).name_to('Save and Return')
+    ...
+    create_button('Help')
+    ...
+    set_page(:step1).buttons_to :next, :cancel, :help
+    set_page(:step2).buttons_to :next, :previous_page, :cancel, :help
+    set_page(:step3).buttons_to :save_and_return, :previous_page, :cancel, :help
+  end
+  
+=== Viewing the Configuration
+
+Use the wizardly rake tools to view the configuration of any wizard changes you make.
+
+  ./script/generate wizardly_app  # if not already called for the project
+  rake wizardly:config name=controller_name
 
-To be provided 
+See the section 'Inspecting a Wizard Controller' above.
 
 == Testing
 

data/lib/wizardly/wizard/button.rb

@@ -9,18 +9,29 @@ module Wizardly
 
       def initialize(id, name=nil)
         @id = id
-        @name = name || sym_to_string(id)
+        @name = name || symbol_to_button_name(id)
+        @user_defined = false
       end
+      
+      def user_defined?; @user_defined; end
 
-      def to(name)
+      #used in the dsl
+      def name_to(name)
         if name.is_a?(String)
           @name = name.strip.squeeze(' ')
-          @id = string_to_sym(name)
+          @id = button_name_to_symbol(name)
         elsif name.is_a?(Symbol)
           @id = name
-          @name = sym_to_string(name)
+          @name = symbol_to_button_name(name)
         end
       end
-    end  
+    end
+
+    class UserDefinedButton < Button
+      def initialize(id, name=nil)
+        super
+        @user_defined = true
+      end
+    end
   end
 end

data/lib/wizardly/wizard/configuration.rb

@@ -7,6 +7,7 @@ require 'wizardly/wizard/configuration/methods'
 module Wizardly
   module Wizard
     class Configuration
+      include TextHelpers
       attr_reader :pages, :completed_redirect, :canceled_redirect, :controller_path, :controller_class_name, :controller_name, :page_order
       
       #enum_attr :persistance, %w(sandbox session database)
@@ -28,10 +29,7 @@ module Wizardly
         @page_order = []
         @pages = {}
         @buttons = nil
-        @default_buttons = {}
-        [:next, :back, :skip, :cancel, :finish].each do |default|
-          @default_buttons[default] = Button.new(default)
-        end
+        @default_buttons = Hash[*[:next, :back, :cancel, :finish, :skip].collect {|default| [default, Button.new(default)] }.flatten]
       end
 
       def guard?; @guard_entry; end
@@ -105,7 +103,7 @@ module Wizardly
               end
               PageField.new(f, type)
             end
-            page = Page.new(p, fields)
+            page = Page.new(self, p, fields)
 
             # default button settings based on order, can be altered by
             # set_page(@id).buttons_to []
@@ -128,14 +126,15 @@ module Wizardly
       def _when_completed_redirect_to(redir); @completed_redirect = redir; end
       def _when_canceled_redirect_to(redir); @canceled_redirect = redir; end
       def _change_button(name)
-        @buttons = nil
+        raise(WizardConfigurationError, "Button :#{name} in _change_button() call does not exist", caller) unless @default_buttons.key?(name)
+        @buttons = nil 
         @default_buttons[name]
       end
       def _create_button(name)
-        id = string_to_sym(name)
-        raise(WizardlyConfigurationError, "Button '#{name}' cannot be created. It already exists.", caller) if @default_buttons.key?(id)
+        id = button_name_to_symbol(name)
+        raise(WizardConfigurationError, "Button '#{name}' with id :#{id} cannot be created. The ID already exists.", caller) if @default_buttons.key?(id)
         @buttons=nil
-        @default_buttons[id] = Button.new(id, name)
+        @default_buttons[id] = UserDefinedButton.new(id, name)
       end
       def _set_page(name); @pages[name]; end
       def _mask_passwords(passwords)
@@ -177,10 +176,11 @@ module Wizardly
         self.buttons.each do |k, b|
           bs = StringIO.new
           bs << "  #{b.name} (:#{b.id}) "
-          if (dk = @default_buttons.index(b))
-            bs << "-- used for internal <#{dk}> functionality"
+          if (b.user_defined?)
+            bs << "-- user defined button and function"
           else
-            bs << "-- custom defined button and function"
+            dk = @default_buttons.index(b)
+            bs << "-- used for internal <#{dk}> functionality"
           end
           io.puts bs.string
         end

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

@@ -4,17 +4,23 @@ module Wizardly
       
       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)
+          %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 ]
+          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)
+    self._define_action_callback_macro('#{macro.first}', '#{macro.last}', *args, &block)
+  end
+MACRO
+        end
+        mb << <<-DEFMAC
+  def self._define_action_callback_macro(macro_first, macro_last, *args, &block)
     return if args.empty?
     all_forms = #{page_order.inspect}
     if args.include?(:all)
@@ -22,28 +28,27 @@ module Wizardly
     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)
+          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 )
+      self.send(:define_method, sprintf(macro_last, form.to_s), &block )
+      hide_action macro_last.to_sym
     end
   end
 
-MACRO
-        end
+DEFMAC
         
-        global_macros = [
-          %w(on_completed after_wizard_save)
-        ]
-        global_macros.each do |macro|
-          mb << <<-GLOBAL
+        [
+          %w(on_completed _after_wizard_save)
+        ].each do |macro|
+          mb << <<-EVENTS
   def self.#{macro.first}(&block)
     self.send(:define_method, :#{macro.last}, &block )
   end
-GLOBAL
+EVENTS
         end
         mb.string
       end
@@ -91,20 +96,20 @@ GLOBAL
       @description = '#{page.description}'
       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
+      if request.post? && callback_performs_action?(:_on_post_#{id}_form)
+        raise CallbackError, "render or redirect not allowed in :on_post(:#{id}) callback", caller
       end
       button_id = check_action_for_button
       return if performed?
       if request.get?
-        return if callback_performs_action?(:on_get_#{id}_form)
+        return if callback_performs_action?(:_on_get_#{id}_form)
         render_wizard_form
         return
       end
 
       # @#{self.model}.enable_validation_group :#{id}
       unless @#{self.model}.valid?(:#{id})
-        return if callback_performs_action?(:on_invalid_#{id}_form)
+        return if callback_performs_action?(:_on_invalid_#{id}_form)
         render_wizard_form
         return
       end
@@ -113,29 +118,29 @@ GLOBAL
         ONE
         if self.last_page?(id)
           mb << <<-TWO
-      callback_performs_action?(:on_#{id}_form_#{finish_button})
+      callback_performs_action?(:_on_#{id}_form_#{finish_button})
       complete_wizard unless @do_not_complete
         TWO
         elsif self.first_page?(id)
           mb << <<-THREE
       if button_id == :#{finish_button}
-        callback_performs_action?(:on_#{id}_form_#{finish_button})
+        callback_performs_action?(:_on_#{id}_form_#{finish_button})
         complete_wizard unless @do_not_complete
         return
       end
       #{model_persist_line}
-      return if callback_performs_action?(:on_#{id}_form_#{next_button})
+      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}
-        callback_performs_action?(:on_#{id}_form_#{finish_button})
+        callback_performs_action?(:_on_#{id}_form_#{finish_button})
         complete_wizard unless @do_not_complete
         return
       end
       #{model_persist_line}
-      return if callback_performs_action?(:on_#{id}_form_#{next_button})
+      return if callback_performs_action?(:_on_#{id}_form_#{next_button})
       redirect_to :action=>:#{self.next_page(id)}
         FOUR
         end
@@ -157,6 +162,7 @@ ENSURE
       <<-CALLBACKS 
   protected
   def _on_wizard_#{finish}
+    return if @wizard_completed_flag
     @#{self.model}.save_without_validation! if @#{self.model}.changed?
     @wizard_completed_flag = true
     reset_wizard_form_data
@@ -259,10 +265,19 @@ SESSION
 SANDBOX
         end
         mb << <<-HELPERS
+  def render_and_return
+    return if callback_performs_action?('_on_get_'+@step.to_s+'_form')
+    render_wizard_form
+    render unless self.performed?
+  end
+
   def complete_wizard(redirect = nil)
-    @#{self.model}.save_without_validation!
-    callback_performs_action?(:after_wizard_save)
+    unless @wizard_completed_flag
+      @#{self.model}.save_without_validation!
+      callback_performs_action?(:_after_wizard_save)
+    end
     redirect_to redirect if (redirect && !self.performed?)
+    return if @wizard_completed_flag
     _on_wizard_#{finish_button}
     redirect_to #{Utils.formatted_redirect(self.completed_redirect)} unless self.performed?
   end
@@ -291,7 +306,7 @@ SANDBOX
   def progression
     session[:#{self.progression_key}]||[]
   end
-  hide_action :progression, :progression=
+  hide_action :progression, :progression=, :initial_referer, :initial_referer=
 
   def wizard_form_data=(hash)
     if wizard_config.form_data_keep_in_session?
@@ -336,14 +351,16 @@ SANDBOX
     #check if params[:commit] has returned a button from submit_tag
     unless (params[:commit] == nil)
       button_name = underscore_button_name(params[:commit])
-      unless [:#{next_id}, :#{finish_id}].include?(button_id = button_name.to_sym)
-        action_method_name = "on_" + params[:action].to_s + "_form_" + button_name
+      unless [:#{next_id}, :#{finish_id}].include?(button_id = button_name.to_sym) 
+        action_method_name = "_on_" + params[:action].to_s + "_form_" + button_name
         callback_performs_action?(action_method_name)
-        method_name = "_on_wizard_" + button_name
-        if (self.method(method_name))
-          self.__send__(method_name)
-        else
-          raise MissingCallbackError, "Callback method either '" + action_method_name + "' or '" + method_name + "' not defined", caller
+        unless ((btn_obj = self.wizard_config.buttons[button_id]) == nil || btn_obj.user_defined?)
+          method_name = "_on_wizard_" + button_name
+          if (self.method(method_name))
+            self.__send__(method_name)
+          else
+            raise MissingCallbackError, "Callback method either '" + action_method_name + "' or '" + method_name + "' not defined", caller
+          end
         end
       end
     end

data/lib/wizardly/wizard/page.rb

@@ -8,19 +8,23 @@ module Wizardly
       attr_reader :id, :title, :description
       attr_accessor :buttons, :fields
 
-      def initialize(id, fields)
+      def initialize(config, id, fields)
         @buttons = []
-        @title = sym_to_string(id)
+        @title = symbol_to_button_name(id)
         @id = id
         @description = ''
         @fields = fields 
+        @config = config
       end
 
       def name; id.to_s; end
 
       def buttons_to(*args)
-        # #must analyze buttons
-        @buttons = args
+        buttons = @config.buttons
+        @buttons = args.map do |button_id|
+          raise(WizardConfigurationError, ":#{button_id} not defined as a button id in :button_to() call", caller) unless buttons.key?(button_id)
+          buttons[button_id]
+        end
       end
       def title_to(name)
         @title = name.strip.squeeze(' ')

data/lib/wizardly/wizard/text_helpers.rb

@@ -2,10 +2,13 @@ module Wizardly
   module Wizard
     module TextHelpers
       private
-      def string_to_sym(str)
-        str.downcase.strip.squeeze(' ').gsub(/ /, '_').to_sym
+      def underscore_button_name(name)
+        name.to_s.strip.squeeze(' ').gsub(/ /, '_').downcase
       end
-      def sym_to_string(sym)
+      def button_name_to_symbol(str)
+        underscore_button_name(str).to_sym
+      end
+      def symbol_to_button_name(sym)
         sym.to_s.gsub(/_/, ' ').squeeze(' ').titleize
       end
     end

metadata

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