wicked-focused 0.2.0

data/.rvmrc

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+ruby_string="ruby-1.9.3-p125"
+gemset_name="wicked"
+
+if rvm list strings | grep -q "${ruby_string}" ; then
+
+  rvm use "${ruby_string}@${gemset_name}" --create
+
+  # Complain if bundler isn't installed
+  if [[ -z "`gem which bundler 2>&1 | grep -v ERROR`" ]]; then
+    echo "You need bundler:"
+    echo ""
+    echo "    gem install bundler"
+    echo ""
+  fi
+else
+  echo "${ruby_string} was not found, please run 'rvm install ${ruby_string}' and then cd back into the project directory."
+fi

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.3

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.2.0 (08/06/2012)
+
+@kristianmandrup: Redesigned for use with Focused Controller. All tests pass :) 

data/Gemfile

@@ -0,0 +1,22 @@
+source "http://rubygems.org"
+
+gem "activesupport" , ">= 3.0.7"
+gem "rails"         , ">= 3.0.7"
+
+# with Action macros
+gem 'focused_controller', :git => 'git://github.com/kristianmandrup/focused_controller.git'
+
+
+group :development, :test do
+  gem 'rake'
+  gem 'jeweler',  "~> 1.8.4"
+  gem "rcov",     ">= 0"
+  gem "capybara", ">= 1.0.0"
+  gem "sqlite3"
+  gem "launchy"
+end
+
+
+# To use debugger (ruby-debug for Ruby 1.8.7+, ruby-debug19 for Ruby 1.9.2+)
+# gem 'ruby-debug'
+# gem 'ruby-debug19'

data/Gemfile.lock

@@ -0,0 +1,122 @@
+GIT
+  remote: git://github.com/kristianmandrup/focused_controller.git
+  revision: 729d753a62abf4eadcfd76123f643973392bec3a
+  specs:
+    focused_controller (0.1.0)
+      actionpack (~> 3.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract (1.0.0)
+    actionmailer (3.0.11)
+      actionpack (= 3.0.11)
+      mail (~> 2.2.19)
+    actionpack (3.0.11)
+      activemodel (= 3.0.11)
+      activesupport (= 3.0.11)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.5.0)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.14)
+      rack-test (~> 0.5.7)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.11)
+      activesupport (= 3.0.11)
+      builder (~> 2.1.2)
+      i18n (~> 0.5.0)
+    activerecord (3.0.11)
+      activemodel (= 3.0.11)
+      activesupport (= 3.0.11)
+      arel (~> 2.0.10)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.11)
+      activemodel (= 3.0.11)
+      activesupport (= 3.0.11)
+    activesupport (3.0.11)
+    addressable (2.2.7)
+    arel (2.0.10)
+    builder (2.1.2)
+    capybara (1.1.2)
+      mime-types (>= 1.16)
+      nokogiri (>= 1.3.3)
+      rack (>= 1.0.0)
+      rack-test (>= 0.5.4)
+      selenium-webdriver (~> 2.0)
+      xpath (~> 0.1.4)
+    childprocess (0.2.4)
+      ffi (~> 1.0.6)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    ffi (1.0.11)
+    git (1.2.5)
+    i18n (0.5.0)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.4)
+    launchy (2.0.5)
+      addressable (~> 2.2.6)
+    mail (2.2.19)
+      activesupport (>= 2.3.6)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.17.2)
+    multi_json (1.0.4)
+    nokogiri (1.5.0)
+    polyglot (0.3.3)
+    rack (1.2.5)
+    rack-mount (0.6.14)
+      rack (>= 1.0.0)
+    rack-test (0.5.7)
+      rack (>= 1.0)
+    rails (3.0.11)
+      actionmailer (= 3.0.11)
+      actionpack (= 3.0.11)
+      activerecord (= 3.0.11)
+      activeresource (= 3.0.11)
+      activesupport (= 3.0.11)
+      bundler (~> 1.0)
+      railties (= 3.0.11)
+    railties (3.0.11)
+      actionpack (= 3.0.11)
+      activesupport (= 3.0.11)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (~> 0.14.4)
+    rake (0.9.2.2)
+    rcov (0.9.11)
+    rdoc (3.12)
+      json (~> 1.4)
+    rubyzip (0.9.5)
+    selenium-webdriver (2.15.0)
+      childprocess (>= 0.2.1)
+      ffi (~> 1.0.9)
+      multi_json (~> 1.0.4)
+      rubyzip
+    sqlite3 (1.3.5)
+    thor (0.14.6)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.33)
+    xpath (0.1.4)
+      nokogiri (~> 1.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (>= 3.0.7)
+  capybara (>= 1.0.0)
+  focused_controller!
+  jeweler (~> 1.8.4)
+  launchy
+  rails (>= 3.0.7)
+  rake
+  rcov
+  sqlite3

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2011 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,253 @@
+# Wicked Focused
+
+This gem is [wicked](https://github.com/schneems/wicked) tweaked for use with [focused controller](https://github.com/jonleighton/focused_controller).
+
+[![Build Status](https://secure.travis-ci.org/schneems/wicked.png)](http://travis-ci.org/schneems/wicked)
+
+Use wicked to make your Rails controllers into step-by-step wizards. To see Wicked in action check out the example [Rails app](https://github.com/schneems/wicked_example) or [watch the screencast](http://schneems.com/post/18437886598/wizard-ify-your-rails-controllers-with-wicked).
+
+## Why
+
+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.
+
+## Install
+
+Add this to your Gemfile
+
+```ruby
+  gem 'wicked-focused'
+```
+
+Then run `bundle install` and you're ready to start
+
+## Quicklinks
+
+* Build an object step-by-step using [Partial Validation of Active Record Objects](https://github.com/schneems/wicked/wiki/Partial-Validation-of-Active-Record-Objects)
+* [Show Current Wizard Progress to User](https://github.com/schneems/wicked/wiki/Show-Current-Wizard-Progress-to-User)
+* [Example App](https://github.com/schneems/wicked_example)
+* [Screencast](http://schneems.com/post/18437886598/wizard-ify-your-rails-controllers-with-wicked)
+* [Watch Railscasts episode: #346 Wizard Forms with Wicked](http://railscasts.com/episodes/346-wizard-forms-with-wicked)
+
+## How
+
+We are going to build an 'after signup' wizard. First create a controller:
+
+```
+  rails g controller after_signup
+```
+
+Add Routes into `config/routes.rb`:
+
+```ruby
+  resources :after_signup
+```
+
+Next include `Wicked::Wizard` in your controller
+
+```ruby
+
+  class AfterSignupController
+    # base Wizard Action class of Controller must be called 'Action'
+    # and must include of Wizard::Action
+    class Action < FocusedAction
+      include Wizard::Action
+
+      steps :confirm_password, :confirm_profile, :find_friends    
+    end
+
+    # creates Focused Action :index 
+    include Wicked::Wizard 
+
+```
+
+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)`.
+
+```ruby
+class AfterSignupController
+  class Action < FocusedAction
+    include Wizard::Action
+
+    steps :confirm_password, :confirm_profile, :find_friends    
+  end
+  include Wicked::Wizard 
+
+  class Show < Action
+    def run
+      wizard_redirect and return if super()
+      @user = current_user
+      case step
+      when :find_friends
+        @friends = @user.find_friends
+      end
+      render_wizard
+    end
+  end
+end
+```
+
+**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 [Partial Validation of Active Record Objects](https://github.com/schneems/wicked/wiki/Partial-Validation-of-Active-Record-Objects) for an example. It will need to be prefixed, for example a Product's `:id` would be `:product_id`
+
+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.
+
+```ruby
+   <%= link_to 'skip', next_wizard_path %>
+```
+
+You can manually specify which wizard action you want to link to by using the wizard_path helper.
+
+```ruby
+   <%= link_to 'skip', wizard_path(:find_friends) %>
+```
+
+In addition to showing sequential views we can update elements in our controller.
+Note: Here we demonstrate the use of wicked macros.
+
+```ruby
+class AfterSignupController
+  use_wicked_macros
+  
+  wicked_base_action do
+    steps :confirm_password, :confirm_profile, :find_friends
+  end    
+
+  wizard_action :update do
+    wizard do
+      @user = current_user
+      case step
+      when :confirm_password
+        @user.update_attributes(params[:user])
+      end
+      sign_in(@user, :bypass => true) # needed for devise
+      render_wizard @user
+    end
+  end
+end
+```
+
+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
+
+```ruby
+
+    <%= 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`
+
+```ruby
+
+  wizard_action :show do
+    wizard do
+      @user = current_user
+      case step
+      when :find_friends
+        if @user.has_facebook_access_token?
+          @friends = @user.find_friends
+        else
+          skip_step
+        end
+      end
+      render_wizard
+    end
+  end
+
+```
+
+Now you've got a fully functioning AfterSignup controller! If you have questions or if you struggled with something, let me know on [twitter](http://twitter.com/schneems), and i'll try to make it better or make the docs better.
+
+## Quick Reference
+
+*Macros*
+
+`use_wicked_macros` enables use of the Wicked macros. Otherwise you must explicitly create equivalent classes and methods.
+
+`wicked_base_action name, &block`
+
+Created the Focused Controller action base class, from which any Wizard Action class will inherit from.
+
+`wizard_action name, &block` 
+
+Creates a Focused Controller action class inheriting from the base action class of the controller. The block contains the class definition. 
+
+`wizard`
+
+Creates a `#run` method as "required" by a Focused Controller action class. The run method generated calls super which calls `setup_wizard` and also auto-handles redirects.
+
+*View/URL Helpers*
+
+```ruby
+
+  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:*
+
+```ruby
+  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 @user.save, otherwise renders current step
+```
+
+Finally:
+
+Don't forget to create your named views
+
+```
+  app/
+   views/
+    controller_name/
+      first.html.erb
+      second.html.erb
+      # ...
+```
+
+# Finish Wizard Path
+
+You can specify the url that your user goes to by over-riding the `finish_wizard_path` in your wizard controller action.
+
+
+```
+  def finish_wizard_path
+    user_path(current_user)
+  end
+```
+
+### Testing with RSpec
+
+```ruby
+  # 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" => @user.id.to_s }}
+```
+
+## About
+
+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](http://twitter.com/schneems).
+
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,50 @@
+# encoding: UTF-8
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development, :test)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+require 'rdoc/task'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :default => :test
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Wicked Focused'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name        = "wicked-focused"
+  gem.homepage    = "http://github.com/schneems/wicked"
+  gem.license     = "MIT"
+  gem.summary     = %Q{Use Wicked to turn your Focused Controller into a wizard}
+  gem.description = %Q{Rails engine for producing Focused Controller based wizards}
+  gem.email       = "kmandrup@gmail.com"
+  gem.authors     = ["kristianmandrup", "schneems"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/wicked/action.rb

@@ -0,0 +1,64 @@
+module Wicked
+  module Action
+    extend ActiveSupport::Concern
+
+    # Include the modules!!
+    include Wicked::Controller::Concerns::Path
+    include Wicked::Controller::Concerns::RenderRedirect
+    include Wicked::Controller::Concerns::Steps
+
+    included do
+      # Give our Views helper methods!
+      helper_method :wizard_path,     :next_wizard_path, :previous_wizard_path,
+                    :step,            :wizard_steps,     :current_step?,
+                    :past_step?,      :future_step?,     :previous_step?,
+                    :next_step?
+    end
+
+    # any subclass (Action class) should call super!
+    def run
+      setup_wizard      
+    end
+
+    module ClassMethods
+      def wizard &block
+        define_method :run do
+          wizard_redirect and return if super()
+          instance_eval &block
+        end
+      end
+    end
+
+    protected
+
+    def setup_wizard
+      @redirect_path = wizard_path(steps.first) if first_step? && !on_first_step?
+      @redirect_path = wizard_path(steps.last)  if last_step? && !on_last_step?
+
+      @step          = params[:id].try(:to_sym) || steps.first
+      @previous_step = previous_step(@step)
+      @next_step     = next_step(@step)   
+      @redirect_path
+    end
+
+    def wizard_redirect
+      redirect_to @redirect_path if @redirect_path
+    end
+
+    def on_first_step?
+      step == steps.first
+    end
+
+    def on_last_step?
+      step == steps.first
+    end
+
+    def first_step?
+      params[:id].try(:to_sym) == :wizard_first
+    end
+
+    def last_step?
+      params[:id].try(:to_sym) == :wizard_last
+    end
+  end
+end

data/lib/wicked/controller/concerns/path.rb

@@ -0,0 +1,29 @@
+module Wicked::Controller::Concerns::Path
+  extend ActiveSupport::Concern
+
+  def next_wizard_path(options = {})
+    wizard_path(@next_step, options)
+  end
+
+  def previous_wizard_path(options = {})
+    wizard_path(@previous_step, options)
+  end
+
+  def wicked_controller
+    self.class.name.sub(/::\w+$/, '')
+  end
+
+  def wicked_controller_name
+    wicked_controller.sub(/Controller$/, '').gsub('::', '_').underscore
+  end
+
+  def wicked_action
+    params[:action]
+  end
+
+  def wizard_path(goto_step = nil, options = {})
+    id = goto_step || params[:id]
+    path_method = "#{wicked_controller_name}_path"
+    send path_method, id, options
+  end
+end

data/lib/wicked/controller/concerns/render_redirect.rb

@@ -0,0 +1,49 @@
+module Wicked::Controller::Concerns::RenderRedirect
+  extend ActiveSupport::Concern
+
+
+  def render_wizard(resource = nil, options = {})
+    process_resource!(resource)
+    if @skip_to
+      redirect_to wizard_path(@skip_to), options
+    else
+      render_step @step, options
+    end
+  end
+
+  def process_resource!(resource)
+    if resource
+      if resource.save
+        @skip_to ||= @next_step
+      else
+        @skip_to = nil
+      end
+    end
+  end
+
+  def render_step(the_step, options = {})
+    if the_step.nil? || the_step == :finish
+      redirect_to_finish_wizard options
+    else
+      render the_step, options
+    end
+  end
+
+  def redirect_to_next(next_step)
+    if next_step.nil?
+      redirect_to_finish_wizard
+    else
+      redirect_to wizard_path(next_step)
+    end
+  end
+
+  # TODO redirect to resource if one is passed to render_wizard
+  def finish_wizard_path
+    '/'
+  end
+
+  def redirect_to_finish_wizard(options = nil)
+    redirect_to finish_wizard_path, options
+  end
+
+end