stepper 0.0.1 → 0.0.3

data/README.rdoc

@@ -1,9 +1,9 @@
 = Stepper
 
-Stepper is multistep form (wizard) solution for Rails 3.
+Stepper is multistep form (wizard) solution for Rails 3.1.
 Stepper allows you to split up your large form into series of pages that users can navigate through to complete the form and save it state.
 == Installation
-You can use it with Rails 3:
+You can use it with Rails 3.1:
 
   gem install stepper
 == Getting Started
@@ -15,16 +15,21 @@ Create migration for model:
 
 Setup names of steps that you want to have:
 
-  has_steps :steps => %w{name city kind}
+  class Company < ActiveRecord::Base
+    has_steps :steps => %w{ description kind address }
+  end
 
-Setup validation for each step if necessary, method should have name like <tt>validation_#{step_name}</tt>:
+Setup validation for each step if necessary, method should have name like <tt>validate_#{step_name}</tt>:
 
-  def validate_name
+  def validate_description
     self.validates_presence_of :name
+    self.validates_presence_of :desc
   end
 
-  def validate_city
+  def validate_address
     self.validates_presence_of :city
+    self.validates_presence_of :country
+    self.validates_presence_of :address
   end
 
   def validate_kind
@@ -56,17 +61,39 @@ Add stepper helper method into the form in view that rendered by new action:
 
   <%= f.label :name %>
   <%= f.text_field :name %>
+  <%= f.label :desc %>
+  <%= f.text_field :desc %>
 
 +city_step.html.erb+
 
   <%= f.label :city %>
   <%= f.text_field :city %>
+  <%= f.label :country %>
+  <%= f.text_field :country %>
+  <%= f.label :city %>
+  <%= f.text_field :city %>
 
 +kind_step.html.erb+
 
   <%= f.label :kind %>
   <%= f.text_field :kind %>
 
++stepper+ helper creates buttons "Next", "Previous", "Save" and "Finish" as well. You can change button names just add to your locales:
+
+  en:
+    stepper:
+      next_step: 'Next step'
+      previous_step: 'Previous step'
+      save: 'Finish later'
+      finish: 'Finish'
+
++next_step+ button validates, saves current step and renders next step of form;
++previous_step+ saves current step and renders previous step of form;
++save+ save current step and redirects to index page;
++finish+ is showed only for last step instead of +next_step+ button and it validates, saves last step and redirects to show.
+
+If you want to have other partial for buttons than add partial to: +app/views/stepper/_fields.html.erb+
+
 == Contributing to stepper
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.3

data/lib/stepper.rb

@@ -1,3 +1 @@
-require 'rails'
-
 require 'stepper/railtie'

data/lib/stepper/controllers/controller_additions.rb

@@ -6,6 +6,21 @@ module Stepper
     end
 
     module ClassMethods
+      # Sets up +create+, +update+, +new+ actions for controller and before filter for load resource.
+      # If you use cancan or load resource in other way it will get loaded resource.
+      #
+      # First parameters can be name of resource, for example:
+      #
+      #   class CompaniesController < ApplicationController
+      #     has_steps :my_company
+      #   end
+      # It will load or build resource in +@my_company+ variable
+      #
+      # First argument it isn't required:
+      #   class CompaniesController < ApplicationController
+      #     has_steps
+      #   end
+      # In this case resource will be loaded or built into +@company+ variable
       def has_steps(*args)
         include InstanceMethods
         stepper_resource_class.add_before_filter(self, *args)
@@ -19,6 +34,8 @@ module Stepper
 
     module InstanceMethods
 
+      # controller +create+ action
+      # it supports only html responce format for now
       def create
         respond_to do |format|
           if @_stepper_resource_instance.save
@@ -30,8 +47,9 @@ module Stepper
         end
       end
 
+      # controller +update+ action
+      # it supports only html responce format for now
       def update
-
         @_stepper_resource_instance.previous_step!.previous_step! if params[:commit] == t('stepper.previous_step').html_safe
 
         @_stepper_resource_instance.previous_step! if params[:commit] == t('stepper.save').html_safe
@@ -46,25 +64,33 @@ module Stepper
         end
       end
 
+      # controller +new+ action
+      # it supports only html responce format for now
       def new
+        redirect_to :action => :show, :id => @_stepper_resource_instance.id if @_stepper_resource_instance.last_step?
       end
 
       protected
-
+        # redirects to controller actions depends of commit value
+        #   save -> index
+        #   previous_step -> new
+        #   next_step -> new
+        #   finish -> show
         def redirect_steps
           if params[:commit] == t('stepper.save').html_safe
-            redirect_to url_for(sanitized_params.merge(:action => "index"))
+            redirect_to :action => "index"
           elsif params[:commit] == t('stepper.previous_step').html_safe and params[:action] == "update"
-            redirect_to url_for(sanitized_params.merge(:action => "new", :id => @_stepper_resource_instance.id))
+            redirect_to :action => "new", :id => @_stepper_resource_instance.id
           elsif params[:commit] == t('stepper.next_step').html_safe
-            redirect_to url_for(sanitized_params.merge(:action => "new", :id => @_stepper_resource_instance.id)), :notice => "Step #{@_stepper_resource_instance.stepper_current_step.humanize} was successfully created."
+            redirect_to({:action => "new", :id => @_stepper_resource_instance.id}, :notice => "Step #{@_stepper_resource_instance.stepper_current_step.humanize} was successfully created.")
           elsif params[:commit] == t('stepper.finish').html_safe
-            redirect_to url_for(sanitized_params.merge(:action => "show", :id => @_stepper_resource_instance.id))
+            redirect_to :action => "show", :id => @_stepper_resource_instance.id
           else
             raise Stepper::StepperException.new("Unknown commit: #{params[:commit]}")
           end
         end
 
+        # removes from params resource name, commit and id
         def sanitized_params
           params.except(@_stepper_name, :commit, :id)
         end

data/lib/stepper/controllers/controller_resource.rb

@@ -1,6 +1,14 @@
 module Stepper
   class ControllerResource
-
+    # Sets up before filter in +controller_class+ for +create+, +update+ and +new+ actions.
+    # First argument can be name of resource.
+    # For example we have +CompaniesController+ and want to load or build resource to +@my_company+ variable:
+    #   add_before_filter CompanyController, :my_company
+    #
+    # First argument it isn't required:
+    #   add_before_filter CompanyController
+    # In this case resource will be loaded or built into +@company+ variable
+    #
     def self.add_before_filter(controller_class, *args)
       resource_name = args.first
       controller_class.send(:before_filter, :only => [:create, :update, :new]) do |controller|

data/lib/stepper/helper/action_view_additions.rb

@@ -1,6 +1,23 @@
 module Stepper
   module ActionViewAdditions
     module InstanceMethods
+      # Render partial from app/views/stepper/_fields
+      # Adds buttons "Next", "Previous", "Save" and "Finish" to form and adds hidden field with current step name.
+      #
+      # Add to locales for changing step names:
+      #   en:
+      #     stepper:
+      #       next_step: 'Next step'
+      #       previous_step: 'Previous step'
+      #       save: 'Finish later'
+      #       finish: 'Finish'
+      #
+      # +next_step+ button validates, saves current step and renders next step of form;
+      # +previous_step+ saves current step and renders previous step of form;
+      # +save+ save current step and redirects to index page;
+      # +finish+ is showed only for last step instead of +next_step+ button and it validates, saves last step and redirects to show.
+      #
+      # If you want to have other partial for buttons than add partial to: +app/views/stepper/_fields.html.erb+
       def stepper(form)
         resource = self.instance_variable_get :@_stepper_resource_instance
         current_step_column = resource.class._stepper_current_step_column

data/lib/stepper/models/active_record_additions.rb

@@ -1,4 +1,6 @@
 module Stepper
+
+  # This module is automatically included into all models.
   module ActiveRecordAdditions
 
     def self.included(base)
@@ -7,11 +9,32 @@ module Stepper
     end
 
     module ClassMethods
+      # Sets up methods and define steps.
+      # For example, you have model +Company+ and you want to fill it fields in few steps description, kind and address:
+      #   class Company < ActiveRecord::Base
+      #     has_steps :steps => %w{ description kind address }
+      #   end
+      #
+      # Model should have current step column, by default it name is +current_step+.
+      # It should be added by migration:
+      #   add_column :companies, :current_step, :string
+      #   add_index  :companies, :current_step
+      #
+      # The column name can be set up with option +current_step_column+.
+      #
+      # Options:
+      # [:+steps+]
+      #   It is required option. Define steps for multistep form.
+      #
+      # [:+current_step_column+]
+      #   Define what field use for save current step of form. Default +current_step+
+      #
+
       def has_steps(options = {})
         #check options
         raise Stepper::StepperException.new("Options for has_steps must be in a hash.") unless options.is_a? Hash
         options.each do |key, value|
-          unless [:current_step_column, :steps].include? key
+          unless [:current_step_column, :steps, :inherit].include? key
             raise Stepper::StepperException.new("Unknown option for has_steps: #{key.inspect} => #{value.inspect}.")
           end
         end
@@ -23,60 +46,82 @@ module Stepper
         self._stepper_current_step_column = options[:current_step_column] || :current_step
 
         class_attribute :_stepper_steps
-        self._stepper_steps= options[:steps]
 
+        self._stepper_steps = []
+        self._stepper_steps = self.try(:superclass).try(:_stepper_steps) if options[:inherit]
+        self._stepper_steps += options[:steps]
         include InstanceMethods
       end
     end
 
     module InstanceMethods
 
+      # returns name of current step column
       def stepper_current_step_column
         self.class._stepper_current_step_column
       end
 
+      # returns defined steps array
       def stepper_steps
         self.class._stepper_steps
       end
 
+      alias_method(:steps, :stepper_steps) unless self.respond_to? :steps
+
+      # returns index of current step in steps array
       def stepper_current_step_index
         stepper_steps.index(stepper_current_step)
       end
 
-      alias_method(:steps, :stepper_steps) unless self.respond_to? :steps
-
+      # returns name of current step
       def stepper_current_step
-        self.send(self.class._stepper_current_step_column)
+        self.send(self.stepper_current_step_column)
       end
 
+      alias_method :current_step, :stepper_current_step unless self.respond_to? :current_step
+
+      # sets up name of current step
+      # TODO: reject names that doesn't exists in steps array
       def stepper_current_step=(step)
-        self.send("#{self.class._stepper_current_step_column}=", step)
+        self.send("#{self.stepper_current_step_column}=", step)
       end
 
+      alias_method :current_step=, :stepper_current_step= unless self.respond_to? :current_step=
+
+      # Use to check current step or given step is last step
+      #   last_step?("address")
+      # TODO: reject names that doesn't exists in steps array
       def last_step?(step = stepper_current_step)
         step == self.stepper_steps.last
       end
 
+      # Use to check current step or given step is first step
+      #   first_step?("address")
+      # TODO: reject names that doesn't exists in steps array
       def first_step?(step = stepper_current_step)
         (step == stepper_steps.first) or stepper_current_step.blank? && step.blank?
       end
 
+      # returns previous step of current step
       def previous_step
         return nil if (first_step? or stepper_current_step.blank?)
         stepper_steps[stepper_steps.index(stepper_current_step) - 1]
       end
 
+      # set previous step as current step
       def previous_step!
         self.stepper_current_step = self.previous_step
         self
       end
 
+      # returns next step of current step
       def next_step
         return stepper_steps.first if self.stepper_current_step.blank?
         return nil if self.last_step?
         stepper_steps[stepper_steps.index(stepper_current_step) + 1]
       end
 
+      # set next step as current step
       def next_step!
         self.stepper_current_step = self.next_step
         self
@@ -84,6 +129,24 @@ module Stepper
 
       protected
 
+        # Executes validation methods for current step and all previous steps if its exists.
+        # You can set up what fields should be validated in methods for steps. For example:
+        #
+        # def validate_description
+        #   self.validates_presence_of :name
+        #   self.validates_presence_of :desc
+        # end
+        #
+        # def validate_address
+        #   self.validates_presence_of :city
+        #   self.validates_presence_of :country
+        #   self.validates_presence_of :address
+        # end
+        #
+        # def validate_kind
+        #   self.validates_presence_of :kind
+        # end
+
         def current_step_validation
           return if stepper_current_step.blank?
           for i in 0..stepper_current_step_index do

data/stepper.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{stepper}
-  s.version = "0.0.1"
+  s.version = "0.0.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = [%q{Anton Versal}]
-  s.date = %q{2011-09-30}
+  s.date = %q{2011-10-05}
   s.description = %q{Stepper is multistep form (wizard) solution for Rails 3. Stepper allows you to split up your large form into series of pages that users can navigate through to complete the form and save it state.}
   s.email = %q{ant.ver@gmail.com}
   s.extra_rdoc_files = [
@@ -44,6 +44,7 @@ Gem::Specification.new do |s|
     "test/models/assigns_test.rb",
     "test/models/instance_test.rb",
     "test/models/models_test.rb",
+    "test/models/sti_test.rb",
     "test/models/validation_test.rb",
     "test/rails_app/Rakefile",
     "test/rails_app/app/controllers/application_controller.rb",
@@ -51,6 +52,7 @@ Gem::Specification.new do |s|
     "test/rails_app/app/helpers/application_helper.rb",
     "test/rails_app/app/mailers/.gitkeep",
     "test/rails_app/app/models/.gitkeep",
+    "test/rails_app/app/models/big_company.rb",
     "test/rails_app/app/models/company.rb",
     "test/rails_app/app/models/users.rb",
     "test/rails_app/app/views/companies/_step1_step.html.erb",

data/test/controllers/controller_test.rb

@@ -14,7 +14,8 @@ class CompaniesControllerTest < ActionController::TestCase
 
   test "should assign resource if params[:id] exists" do
     @controller.expects(:render)
-    Company.expects(:find).with('1').returns(mock_company)
+
+    Company.expects(:find).with('1').returns(mock_company(:last_step? => false))
     get :new, :id => 1
     assert_response :success
     assert_equal assigns(:company), mock_company
@@ -22,11 +23,18 @@ class CompaniesControllerTest < ActionController::TestCase
 
   test "should get existing assigns" do
     @controller.expects(:render)
-    @controller.instance_variable_set(:@company, mock_company)
+    @controller.instance_variable_set(:@company, mock_company(:last_step? => false))
     get :new, :id => 1
     assert_equal assigns(:company), mock_company
   end
 
+  test "new action should redirect to show if company on at the last step" do
+    @controller.instance_variable_set(:@company, mock_company(:last_step? => true, :id => "1"))
+    get :new, :id => 1
+    assert_response :redirect
+    assert_redirected_to "http://test.host/companies/1"
+  end
+
   protected
     def mock_company(stubs={})
       @mock_company ||= mock(stubs)

data/test/models/sti_test.rb

@@ -0,0 +1,11 @@
+require 'helper'
+class StiModelTest < ActiveSupport::TestCase
+  setup do
+    @big_company = BigCompany.new
+  end
+
+  test "should get steps from parent class" do
+    assert_equal  @big_company.stepper_steps, ["step1", "step2", "step3", "step4", "step5", "step6"]
+  end
+
+end

data/test/rails_app/app/models/big_company.rb

@@ -0,0 +1,4 @@
+class BigCompany < Company
+  has_steps :current_step_column => :my_step, :steps => ["step4", "step5", "step6"], :inherit => true
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stepper
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-30 00:00:00.000000000Z
+date: 2011-10-05 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70136783476040 !ruby/object:Gem::Requirement
+  requirement: &70264337129840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 3.1.0
   type: :runtime
   prerelease: false
-  version_requirements: *70136783476040
+  version_requirements: *70264337129840
 - !ruby/object:Gem::Dependency
   name: ruby-debug19
-  requirement: &70136783475560 !ruby/object:Gem::Requirement
+  requirement: &70264337129360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70136783475560
+  version_requirements: *70264337129360
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70136783475020 !ruby/object:Gem::Requirement
+  requirement: &70264337128880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70136783475020
+  version_requirements: *70264337128880
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &70136783474420 !ruby/object:Gem::Requirement
+  requirement: &70264337128400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70136783474420
+  version_requirements: *70264337128400
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70136783473820 !ruby/object:Gem::Requirement
+  requirement: &70264337127920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *70136783473820
+  version_requirements: *70264337127920
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70136783473220 !ruby/object:Gem::Requirement
+  requirement: &70264337127440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,10 +76,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *70136783473220
+  version_requirements: *70264337127440
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &70136783472620 !ruby/object:Gem::Requirement
+  requirement: &70264337126940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70136783472620
+  version_requirements: *70264337126940
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &70136783472020 !ruby/object:Gem::Requirement
+  requirement: &70264337126460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70136783472020
+  version_requirements: *70264337126460
 - !ruby/object:Gem::Dependency
   name: capybara
-  requirement: &70136783471420 !ruby/object:Gem::Requirement
+  requirement: &70264337125980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70136783471420
+  version_requirements: *70264337125980
 - !ruby/object:Gem::Dependency
   name: launchy
-  requirement: &70136783470820 !ruby/object:Gem::Requirement
+  requirement: &70264337125500 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,7 +120,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70136783470820
+  version_requirements: *70264337125500
 description: Stepper is multistep form (wizard) solution for Rails 3. Stepper allows
   you to split up your large form into series of pages that users can navigate through
   to complete the form and save it state.
@@ -158,6 +158,7 @@ files:
 - test/models/assigns_test.rb
 - test/models/instance_test.rb
 - test/models/models_test.rb
+- test/models/sti_test.rb
 - test/models/validation_test.rb
 - test/rails_app/Rakefile
 - test/rails_app/app/controllers/application_controller.rb
@@ -165,6 +166,7 @@ files:
 - test/rails_app/app/helpers/application_helper.rb
 - test/rails_app/app/mailers/.gitkeep
 - test/rails_app/app/models/.gitkeep
+- test/rails_app/app/models/big_company.rb
 - test/rails_app/app/models/company.rb
 - test/rails_app/app/models/users.rb
 - test/rails_app/app/views/companies/_step1_step.html.erb
@@ -216,7 +218,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2910134889132030582
+      hash: -2262266912899899848
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: