wicked-wizard-validations 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 25eca985f7b7e66f68b8165e46c744d34eed8fd1
+  data.tar.gz: 9bf3a9ca457016634db345eef04e03378289f2dc
+SHA512:
+  metadata.gz: e65f8a0903dfdaf3bad7001695f3551930ede69bd99298552fabe5c676b5e1744e42c95ae3141836c1bbdef6ecd3bea4398ff427d7ce5829430d4bd9b6773954
+  data.tar.gz: 3ea04955be321a0d66174f177da9054d244b7a5067324f83e0c66235623df4703836be688251015313c5b9325c3348c1761c06b4101eb498f615435cef48a6cc

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.idea

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in wicked-wizard-validations.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Error Ltd.
+
+MIT License
+
+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,247 @@
+# Wicked::Wizard::Validations - a validation mixin for Wicked
+This is a mixin for [the Wicked wizard gem](https://github.com/schneems/wicked) which makes it easier to conditionally validate your models based on where the user is in the wizard process.
+
+## Why would I want to use this?
+We often come up against a situation where you want to validate the data is entering into a wizard form, but only the fields they have seen already. Imagine this 3-step process:
+
+1. First name, last name, email
+2. Password, Password Confirmation
+3. Contact details
+
+If the user were at step 1, it would be useless having a basic model validation requiring password be completed: they haven't seen that field yet.
+ 
+So what we want to do is _conditionally validate_ the fields, based on the user's progress. We do this by creating a class method for each step you want to validate, with a hash to pass to the validator.
+
+__Note:__ this requires the step the user is on to be stored in the user model.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'wicked-wizard-validations'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install wicked-wizard-validations
+
+## Usage
+For the purposes of this demo, we'll assume you're validating a model called `User`. Of course, your model could be called anything, and there's no reason why you can't validate several models at one using a common set of steps.
+
+### Create your model
+Create an ActiveRecord model as normal. This gem looks for a string field called `current_step` (which is configurable - see below).
+
+### Define your wizard steps.
+The easiest place to define your wizard steps is in your model. This is a departure from the normal Wicked::Wizard way of doing it, which is in the controller
+
+```
+class User < ActiveRecord::Base
+    include Wicked::Wizard::Validations
+    
+    #This method defines the step names. You still need to call `step` in the controller.
+    def self.wizard_steps
+        [
+            "basic_details",
+            "password",
+            "contact_details"
+        ]
+    end
+```
+
+```
+class UsersController < ApplicationController
+    include Wicked::Wizard
+    # This is the 'normal' place to define Wicked::Wizard steps.
+    # We just call the steps we defined above in User.
+    steps(*User.wizard_steps)    
+end
+```
+
+### Add your validations for each step
+Ok, so now you have steps, and the controller knows about them. How do you add validations?
+
+You create _class_ methods on `User` which correspond to the name of the step, with `_validations` at the end. This method needs to return a hash of field names and keys, the latter of which which is passed straight to [Activerecord Validations](http://guides.rubyonrails.org/active_record_validations.html).
+
+```
+class User < ActiveRecord::Base
+    include Wicked::Wizard::Validations
+    
+    #This method defines the step names
+    def self.wizard_steps
+        [
+            "basic_details",
+            "password",
+            "contact_details"
+        ]
+    end
+    
+    
+    def self.basic_details_validations    # validations for the basic_details step.
+        {
+            first_name: {
+                presence: {
+                    message: "Don't be shy! We need your first name."
+                }
+            },
+            last_name: {
+                presence: true  #just the default ActiveRecord validation message
+            },
+            email: {
+                presence: true, on: :update #this validation only happens on update, not create.
+            }
+        }
+    end
+```
+
+### Set up validations
+The last stage is to set up the validations when the model is loaded. That's a one-liner in the model:
+
+```
+    class User < ActiveRecord::Base
+        include Wicked::Wizard::Validations
+        
+        # Setup the validations when this class is loaded
+        self.setup_validations!
+        
+        #other stuff in here
+    end
+    
+```
+
+And that's it! For a given step, defined validations will apply whenever a user is at or past that step.
+
+### Customising the `current_step` and `wizard_steps` methods.
+You might want to have a different attribute on your model to store the current step. That's easy:
+
+```
+    class User < ActiveRecord::Base
+        include Wicked::Wizard::Validations
+        
+        self.current_step_method = :my_current_step_attribute #the current step will be stored in this attribute.
+        
+        #other stuff in here
+    end
+```
+
+Likewise, the you might want to define a different method for the wizard steps:
+
+```
+    class User < ActiveRecord::Base
+        include Wicked::Wizard::Validations
+        
+        self.wizard_steps_method = :my_amazing_steps # User.my_amazing_steps needs to return an array of steps
+        
+        #other stuff in here
+    end
+```
+
+### Validating more than one model in a wizard
+You might have a relationship between models, and be collecting data for both in a wizard. That's pretty easy to support: you just have to remember to use the same list of wizard steps.
+
+Say, for example, that your user has an `address`, you could require a house name and postcode when they get to the `contact_details` step (or after it).
+
+```
+    class Address < ActiveRecord::Base
+        include Wicked::Wizard::Validations
+       
+        belongs_to :user
+        
+        #returns the current step for the associated user
+        def current_step
+            user.current_step 
+        end
+        
+        # returns the wizard steps for the User class
+        def wizard_steps
+            User.wizard_steps
+        end
+        
+        # Specify validations on Address which should apply when the user is on or past 
+        # the address_details step
+        def address_details_validations
+            house_name_or_number: {
+                presence: {
+                    message: "Please give us your house name or number"
+                }
+            },
+            postcode: {
+                format: {
+                    with: /^([A-PR-UWYZ0-9][A-HK-Y0-9][AEHMNPRTVXY0-9]?[ABEHMNPRVWXY0-9]? {1,2}[0-9][ABD-HJLN-UW-Z]{2}|GIR 0AA)$/
+                }
+            }
+        end
+    end
+     
+```
+
+### Utility instance methods
+There are a couple of instance methods on objects which have this mixin applied.
+
+```
+u = User.find(123)
+u.current_wizard_step # get the current step
+u.previous_wizard_steps #the steps before the one the user is on
+u.current_and_previous_wizard_steps #an array of steps the user has been through
+```
+
+### Redirecting to the right step on login
+Because we're storing the current step of the user, you get the ability to allow the user to jump back to the step they were on when they log in. Very useful for big multi-page forms where the user might need to come back later.
+
+In the controller you're using for your wizard, you need this in the `show` method:
+
+```
+    class UsersController < ApplicationController
+        include Wicked::Wizard
+        
+        # other stuff
+        
+        def show
+            @user = current_user
+            
+            # Redirect to the user's current step - useful for logging in a second time
+            if @user.current_wizard_step.present? && !@user.current_and_previous_wizard_steps.include?(step)
+                jump_to(@user.current_wizard_step)
+            end
+        end
+    end
+```
+
+#### Allowing users to go back in the process
+If you redirect the user to their previously-stored step, you've just stopped them from going back in the process. So to get around that, we need to update their current step when they change it.
+
+Note that this only allows the user to go to steps earlier than the one they're on.
+
+```
+    class UsersController < ApplicationController
+        include Wicked::Wizard
+        
+        # other stuff
+        
+        def show
+            @user = current_user
+            
+            # Redirect to the user's current step - useful for logging in a second time
+            if @user.current_wizard_step.present? && !@user.current_and_previous_wizard_steps.include?(step)
+                jump_to(@user.current_wizard_step)
+            end
+            
+            # if the step we're rendering is before the users last known current step, assume they've clicked their
+            # browser's back button, update their current_step and render that page of the wizard
+            if (User.wizard_steps.index(step) < User.wizard_steps.index(@user.current_wizard_step.to_sym))
+              @user.update_attribute(:current_step, step) # if your attribute is called something else, you'll need to amend this.
+            end
+        end
+    end
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/errorstudio/wicked-wizard-validations/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Squash your commits into logical changesets.
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/wicked/wizard/validations.rb

@@ -0,0 +1,109 @@
+require "wicked/wizard/validations/version"
+
+module Wicked
+  module Wizard
+    module Validations
+      extend ActiveSupport::Concern
+
+      included do
+        class << self
+          # Set up a class-level instance method to hold the name of a method to call
+          # to get the current_step for this model.
+          attr_accessor :current_step_method, :wizard_steps_method
+        end
+      end
+
+      #
+      #Class methods on the included model
+      #
+      module ClassMethods
+
+        # @return [Array] a list of wizard steps for the class. Calls the method specified in the class instance attribute
+        # `wizard_steps_method`; returns an empty [Array] otherwise.
+        def all_wizard_steps
+          meth = self.wizard_steps_method
+          if meth.present?
+            case meth.class.to_s
+              when "Symbol"
+                self.send(meth)
+              else
+                raise ArgumentError, "wizard_steps_method accepts only a symbol, which should be a class method name"
+            end
+          else
+            begin
+              wizard_steps #if no wizard_steps_method set, assume `wizard_steps`.
+            rescue
+              []
+            end
+          end
+
+        end
+
+        # get previous steps for a given step
+        # @param step [Symbol] the name of the step you're on now
+        # @return [Array] the steps prior to this one
+        def previous_wizard_steps(step)
+          #cast the incoming step to a symbol
+          step = step.to_sym if step.is_a?(String)
+          self.all_wizard_steps.slice(0,self.all_wizard_steps.index(step))
+        end
+
+        # This is where the meat of the work happens.
+        # We call this in the class, and it iterates through all the wizard steps, calling `[wizard_step_name]_validations`
+        # on the class. If it responds, it should return a hash which can be passed straight into a `validates()` call
+        def setup_validations!
+          # Iterate through each step in the validations hash, and call a class method called [step]_step_validations
+          # if it exists. For example, if step were called foo_details, the method would be called foo_details_validations
+          self.all_wizard_steps.each do |step|
+            validation_method_name = "#{step}_validations".to_sym
+            if self.respond_to?(validation_method_name)
+              #if the method responds, we're expecting a hash in the following format:
+              # {
+              #   field_name: {
+              #     presence: true
+              #   }
+              # }
+              self.send(validation_method_name).each do |field,validations|
+                # validate the field, using the validations hash, but merge in a lambda which checks whether the object
+                # is at the step yet, or not. If it's not, the validation isn't applied.
+                validates field, validations.merge({if: ->{ self.current_and_previous_wizard_steps.include?(step)}})
+              end
+            end
+          end
+        end
+      end
+
+      #
+      #instance methods on the model follow
+      #
+
+      # Get the current wizard step by calling the instance method specified
+      # in the class; fall back to calling `current_step` on the instance.
+      def current_wizard_step
+        meth = self.class.current_step_method
+        if meth.present?
+          case meth.class.to_s
+            when "Symbol"
+              self.send(meth)
+            else
+              raise ArgumentError, "current_step_method accepts a symbol, which should be the name of a callable instance method"
+          end
+        else
+          #assume the method is called current_step() and call that
+          current_step
+        end
+      end
+
+      # Call the `previous_wizard_steps` class method, passing in the current step for this instance
+      # @return [Array] an ordered list of wizard steps which happen before the current one
+      def previous_wizard_steps
+        self.class.previous_wizard_steps(current_wizard_step.to_sym)
+      end
+
+      # @return [Array] an ordered list of wizard steps, up to and including this one
+      def current_and_previous_wizard_steps
+        previous_wizard_steps.push(current_wizard_step.to_sym)
+      end
+    end
+  end
+end

data/lib/wicked/wizard/validations/version.rb

@@ -0,0 +1,7 @@
+module Wicked
+  module Wizard
+    module Validations
+      VERSION = "0.0.1"
+    end
+  end
+end

data/wicked-wizard-validations.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'wicked/wizard/validations/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "wicked-wizard-validations"
+  spec.version       = Wicked::Wizard::Validations::VERSION
+  spec.authors       = ["Ed Jones"]
+  spec.email         = ["ed@errorstudio.co.uk"]
+  spec.summary       = %q{A validation mixin for Wicked.}
+  spec.description   = %q{This gem allows you to conditionally validate your models, based on where in a multi-step process the user is.}
+  spec.homepage      = "https://github.com/errorstudio/wicked-wizard-validations"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+
+  spec.add_dependency 'wicked', '~> 1.2.1'
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: wicked-wizard-validations
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ed Jones
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-11-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: wicked
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+description: This gem allows you to conditionally validate your models, based on where
+  in a multi-step process the user is.
+email:
+- ed@errorstudio.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/wicked/wizard/validations.rb
+- lib/wicked/wizard/validations/version.rb
+- wicked-wizard-validations.gemspec
+homepage: https://github.com/errorstudio/wicked-wizard-validations
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A validation mixin for Wicked.
+test_files: []