StairMaster

StairMaster is designed to make building wizard, or step styled navigation in your Rails applicaiton dead simple.

Installation

Add this line to your application's Gemfile:

gem 'stair_master'

And then execute:

$ bundle install

Usage

StairMaster attempts to maintain RESTful concepts in the wizard implementation. Each step has it's own controller that should inherit from a "base" controller which will define the rules governing the workflow.

Workflow Maps

A workflow map will tell StairMaster what steps are available, define any rules that may govern that availability as well as define the order to which the steps will be presented to the user.

Workflow maps must inherit from StairMaster::WorkflowMap which provides some simple methods for for defining your steps and order.

There are two methods that we will use to define our map.

add_step(controller_name, label, named_route, *conditions)

Use this method to add steps to your workflow map.

Method Parameters

controller_name :symbol

This is the name of the controller for the step. Should be a symbol.

label :string

This is the label to be used for the step. Can be accessed by the view, and will also be used in the rendering of the breadcrumbs hash.

named_route :symbol

The named route for the path of this step.

conditions :hash

Define the conditions that are to be used when resolving which steps will be available, and/or should be skipped based on the current context. Available conditions are:

• skip_if/unless

Note we recommend placing your maps in app/maps however you can place them where ever you would like.

# app/maps/my_process_map.rb
#
class MyProcessMap < StairMaster::WorkflowMap
    # We must override the define_map! method with our mapping rules
    add_step :home, "First Step", :first_step_path, skip_if: :method_name
    ...

    set_order :home, ...
end

Controllers

When setting up your controllers, we would recommend setting up a base controller which you can use to define which map to use and any methods that will be called by your conditionals to determine your workflow at runtime.

Base Controller

# app/controllers/my_process/base_controller.rb
#
class MyProcess::BaseController < ApplicationController
    # Include the stair master controller concern
    include StairMaster::Controller

    # Tell stair master what map to use
    stair_master_map_class MyProcessMap
end

Step Controller

# app/controllers/my_process/home_controller.rb
#
class MyProcess::HomeController < MyProcess::BaseController
    def show
    end

    def update
    end
end

Our step controller has two actions: show and update. You can absolutely add other actions to this controller at your descretion, however StairMaster is going to need only these two. We will use the show view to present the user with the step, and the update action to process any data the user submits.

Helper Methods

StepMaster is going to make available serveral different herlper methods that we can use from our view to help the user navigate from step to step using the business logic you have defined in the WorkflowMap.

Step Traversal

current_step

next_step

previous_step

Each of these helpers will give you access to your current, next and previous step. When accessing the step you're going to have a few methods available to you.

label

You can access the step label to retrieve the label text that you assigned to the step in your WorkflowMap.

url_for(resources=[], options={})

You can render the named_route you identified for the step by calling this method. It will accept any of the same parameters you would normally pass into a named route in your code.

Ordering

available_steps

Testing

on_first_step?

on_last_step?

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request