wizardly creates a multi-step wizard for any ActiveRecord model in three steps.
Source
-
git://github.com/jeffp/wizardly.git
Install
-
sudo gem install wizardly –source=http://gemcutter.org
Examples
Thanks for feedback from Roland Schulz, Steve Hoeksema, Morgan Christiansson, Jonathan Clarke, Nate Delage
wizardly builds on Alex Kira’s validation_group plugin code to DRY up the Rails MVC implementation of a wizard. In three easy steps, wizardly produces the scaffolding and controller of a multi-step wizard.
Features include:
-
Model-based Wizard Definition
-
Wizard Controller Macros
-
Wizard Scaffold Generators
-
Sizard Form Helpers
-
Configurable Buttons
-
Callbacks
-
Paperclip Support
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
Put the following in your application’s config block in config/environment.rb
config.gem 'wizardly'
The temporarily (or permanently depending on github’s reinstatement of gems) resides at gemcutter.org. Make sure you have added gemcutter.org to your gem sources
and run the install gems rake task on your application
rake gems:install
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 record store, add this line to your environment.rb
config.action_controller.session_store = :active_record_store
And set up the sessions table in the database
rake db:sessions:create rake db:migrate
Use the MemCached session store for higher performance requirements.
This is optional, but for any rails app, you can install wizardly rake tasks by running
./script/generate wizardly_app
Once installed, you can run the config rake task to inspect a wizardly controller
rake wizardly:config name=controller_name
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.
Wizardly creates a controller action for each validation group in the model. Likewise, the wizardly scaffold generates a view named for each corresponding action.
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.
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.
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.
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.
The guarding feature can be disabled for testing or other purposes.
Once a user has entered a wizard, there are two ways they can leave, either by 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 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', :canceled=>{:controller=>:main, :action=>:canceled} end
Now whether the user completes or cancels the wizard, the controller knows 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
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.
Here’s a list of options for the act_wizardly_for controller macro
:completed => '/main/finished'
:canceled => {:controller=>'main', :action=>'canceled'}
:skip => true
:cancel => false
:guard => false
:mask_fields => [:password, :password_confirmation] (by default)
:persist_model => {:per_page|:once}
:form_data => {:session|:sandbox}
Setting the :skip option to true tells the scaffold helpers to include a skip button on each page. The :cancel option set to false removes the ‘cancel’ button from the wizard views. The :mask_fields options tells the scaffold generator which fields to generate as ‘type=password’ fields. Remaining options are explained below.
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 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 from the first page.
The form data is always cleared once the user has completed the wizard and the record has been committed.
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).
The :persist_model option controls how the model is saved, either :once or :per_page. The default setting :per_page, saves the model incrementally for each page that validates according to its validation group. This setting may result in invalid and incomplete records in the database.
This problem can be remedied by using the :once setting, in which case, form data is kept in the session until the wizard is complete and then saved out to the database.
The :once option does not work in all cases, particularly for any attribute that can not be marshalled and dumped in the session. In particular, this will not work for forms with file uploads like any forms using Paperclip. When using Paperclip, use the :per_page setting.
The wizardly controller defines five default button functions: next, back, skip, cancel, and finish. All but :skip are used in the scaffolding by default. You can add :skip functionality to all pages by adding an option to the macro
class SignupController < ApplicationController act_wizardly_for :user, :redirect=>'/main', :skip=>true end
You can create, customize and change buttons for any controller and any page. See the Button Customization section.
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 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 @user[:password] = '' @user[:password_confirmation] = '' end end
Here’s the list of action callbacks macros that the developer can use for any action
on_back(:step) # called when the :back 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) 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)
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.
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 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.
#GET request callback order on_back, on_skip, on_cancel on_get render_wizard_form
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_errors render_wizard_form # only if errors on_next on_finish on_completed # only if completed
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_errors(:step2) do setup_step2_form end 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.
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.
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 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
In the above example, :step 3 is a page for a volunteer, and :step2 is a page for a non-volunteer.
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.
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.
There are two general callback macros: render_wizard_form and on_completed. These are not tied to any action or set of actions.
For anyone needing to handle rendering in a special way, wizardly provides a render call back for this.
class SignupController < ApplicationController
act_wizardly_for :user, :redirect=>'/main'
def render_wizard_form
respond_to do |format|
format.html
format.xml { render_xml(@step) }
end
end
def render_xml(step)
...
end
end
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
Wizardly provides some helper methods which are useful in callbacks.
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.
on_next(:step4) do if (test_radio_button) complete_wizard end end
Complete wizard will save the model and redirect to the :completed redirect setting. You can change the redirect dynamically by passing it to the method.
complete_wizard(some_model_path)
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
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
You can create a scaffold using image_submit_tag by doing the following:
./script/generate wizardly_scaffold controller_name --image_submit
Default button images are provided under the public/images/wizardly/ directory.
The buttons used by the wizard and the view helpers can be customized as follows.
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.
Changing the name of a default button does not change the name of its callback macro. For instance, the renamed :back and :finish buttons above (to ‘Previous Page’ and ‘Save and Return’, respectively) still use the on_back() and on_finish() callback macros despite the name change.
Perhaps though you want to change the symbol used to represent the button for consistancy across your MVC. You can use the :id option when renaming to do so.
class UserSignupController < ApplicationController act_wizardly_for :user, :redirect=>'/main/index' do change_button(:back).name_to('Previous Page', :id=>:previous_page) change_button(:finish).name_to('Save and Return', :id=>save_and_return) end end
Coding the above causes the :back button’s ID to be replaced with :previous_page and so forth for the :finish button. Thereafter, each button is referred to with the new ID. For instance, the corresponding callback macros would be
on_previous_page(:step3) do ... end on_save_and_return(:step3) do ... end
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
Sometimes you may want to use the default ID given to the button. You can specify the ID with the :id option. This is particularly useful for international languages.
create_button('Helfen', :id=>:help)
Now the help button will be called ‘Helfen’ in German and will be represented by :help in the code.
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
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
See the section ‘Inspecting a Wizard Controller’ above.
Testing uses RSpec and Webrat. Make sure you have the gems installed. Then to test the development code run the following:
rake spec:all
-
validation_group is currently integrated (plugin not required)
-
ActiveRecord
-
ActionController