Skip to content


Subversion checkout URL

You can clone with
Download ZIP
tree: e8df825f32
Fetching contributors…

Cannot retrieve contributors at this time

261 lines (174 sloc) 8.586 kb


Build Status

Use wicked to make your Rails controllers into step-by-step wizards. To see Wicked in action check out the example Rails app or watch the screencast.


Many times I'm left wanting a RESTful way to display a step by step process that may or not be associated with a resource. Wicked gives the flexibility to do what I want while hiding all the really nasty stuff you shouldn't do in a controller to make this possible. At it's core Wicked is a RESTful(ish) state machine, but you don't need to know that, just use it.


Add this to your Gemfile

  gem 'wicked'

Then run bundle install and you're ready to start



We are going to build an 'after signup' wizard. First create a controller:

  rails g controller after_signup

Add Routes into config/routes.rb:

  resources :after_signup

Next include Wicked::Wizard in your controller

  class AfterSignupController < ApplicationController
    include Wicked::Wizard

    steps :confirm_password, :confirm_profile, :find_friends
    # ...

You can also use the old way of inheriting from Wicked::WizardController.

  class AfterSignupController < Wicked::WizardController

    steps :confirm_password, :confirm_profile, :find_friends
    # ...

The wizard is set to call steps in order in the show action, you can specify custom logic in your show using a case statement like below. To send someone to the first step in this wizard we can direct them to after_signup_path(:confirm_password).

  class AfterSignupController < ApplicationController
    include Wicked::Wizard

    steps :confirm_password, :confirm_profile, :find_friends

    def show
      @user = current_user
      case step
      when :find_friends
        @friends = @user.find_friends

Note: Wicked uses the :id parameter to control the flow of steps, if you need to have an id parameter, please use nested routes see building objects with wicked for an example. It will need to be prefixed, for example a Product's :id would be :product_id

Routing helpers

The routing helper which was loaned from Wizardry( allows for nicer routes

resource :after_signup do
# same as
wicked_resource :after_signup
# or
wicked_resources :products

will replace default *:id/edit* path with *:id/edit/:step* and update with *:id/:step*. is_wicked and wicked_resource also accepts a hash to further configure the behavior

  • :step_constraint => /first/second/ Set to true to generate a regexp which allows only the steps which are assigned in the controller or pass a regexp.
  • :step_optional => true The route will be *:id/edit(/:step)* but be carefull not to shadow other routes.
  • :step_parameter => :pets Defaults to :step can but can be changed set to :id for backwards compatibility with the old routes.
  • :show_step_action => :show the action used to display the steps, defaults to :edit but can be set back to :show. wicked_resource(s) or the parent resource from is_wicked can take:
  • :path_names => { :edit => 'amend' } Changes the route to *:id/amend/:step* can be set to nil for *:id/:step*. :update will be set to the same as :edit if not specified. Use update_wizard_path in the form url if update path is not the same as edit path.

You'll need to call render_wizard at the end of your action to get the correct views to show up.

By default the wizard will render a view with the same name as the step. So for our controller AfterSignupController with a view path of /views/after_signup/ if call the :confirm_password step, our wizard will render /views/after_signup/confirm_password.html.erb

Then in your view you can use the helpers to get to the next step.

   <%= link_to 'skip', next_wizard_path %>

You can manually specify which wizard action you want to link to by using the wizard_path helper.

   <%= link_to 'skip', wizard_path(:find_friends) %>

In addition to showing sequential views we can update elements in our controller.

  class AfterSignupController < ApplicationController
    include Wicked::Wizard

    steps :confirm_password, :confirm_profile, :find_friends

    def update
      @user = current_user
      case step
      when :confirm_password
      sign_in(@user, :bypass => true) # needed for devise
      render_wizard @user

We're passing render_wizard our @user object here. If you pass an object into render_wizard it will show the next step if the object saves or re-render the previous view if it does not save.

To get to this update action, you simply need to submit a form that PUT's to the same url

    <%= form_for @user, :url => wizard_path, :method => :put do |f| %>
      <%=  f.password_field :password  %>
      <%=  f.password_field :password_confirmation  %>

      <%= f.submit "Change Password" %>
    <% end %>

We explicitly tell the form to PUT above. If you forget this, you will get a warning about the create action not existing, or no route found for POST. Don't forget this.

In the controller if you find that you want to skip a step, you can do it simply by calling skip_step

  def show
    @user = current_user
    case step
    when :find_friends
      if @user.has_facebook_access_token?
        @friends = @user.find_friends

Now you've got a fully functioning AfterSignup controller! If you have questions or if you struggled with something, let me know on twitter, and i'll try to make it better or make the docs better.

Quick Reference

View/URL Helpers

  wizard_path                  # Grabs the current path in the wizard
  wizard_path(:specific_step)  # Url of the :specific_step
  next_wizard_path             # Url of the next step
  previous_wizard_path         # Url of the previous step

  # These only work while in a Wizard, and are not absolute paths
  # You can have multiple wizards in a project with multiple `wizard_path` calls

Controller Tidbits:

  steps  :first, :second       # Sets the order of steps
  step                         # Gets symbol of current step
  next_step                    # Gets symbol of next step
  skip_step                    # Tells render_wizard to skip to the next logical step
  render_wizard                # Renders the current step
  render_wizard(@user)         # Shows next_step if, otherwise renders current step


Don't forget to create your named views

      # ...

Finish Wizard Path

You can specify the url that your user goes to by over-riding the finish_wizard_path in your wizard controller.

  def finish_wizard_path

Testing with RSpec

  # Test find_friends block of show action
  get :show, :id => :find_friends

  # Test find_friends block of update action
  put :update, {'id' => 'find_friends', "user" => { "id" => }}


Please poke around the source code, if you see easier ways to get a Rails controller do do what I want, let me know.

If you have a question file an issue or, find me on the Twitters @schneems.

This project rocks and uses MIT-LICENSE.

Jump to Line
Something went wrong with that request. Please try again.