progression 0.0.1 → 0.0.2

data/README.md

@@ -28,17 +28,48 @@ either coupled with ActiveRecord or ActionController in some way.
 
     user = User.new
     user.registration_progress.completed_steps # => []
-    user.registration_progress.percentage_complete # => 0.0
-    user.next_step.name # => :step_1
+    user.registration_progress.percentage_completed # => 0.0
+    user.registration_progress.next_step.name # => :step_1
 
     user.first_name = "Michael"
     user.last_name  = "Jordan"
     user.registration_progress.completed_steps # => [:step_1]
-    user.registration_progress.percentage_complete # => 50.0
-    user.next_step.name # => :step_2
+    user.registration_progress.percentage_completed # => 50.0
+    user.registration_progress.next_step.name # => :step_2
 
     ...
 
+## Custom Percentages
+
+progression provides support for defining your own percentages for
+each step rather than having them predefined as (1 / number_of_steps).
+
+    class User < Struct.new(:first_name, :last_name, :email, :phone)
+
+      include Progression
+
+      progression :registration do
+        step :important_step, :percentage => 50.0 do
+          first_name.present? && last_name.present?
+        end
+
+        step :step_2, :percentage => 25.0 do
+          email.present?
+        end
+
+        step :step_3, :percentage => 25.0 do
+          phone.present?
+        end
+      end
+    end
+
+    user = User.new
+    user.first_name = "Michael"
+    user.last_name  = "Jordan"
+    user.registration_progress.completed_steps # => [:important_step]
+    user.registration_progress.percentage_completed # => 50.0
+    user.registration_progress.next_step.name # => :step_2
+
 
 ## Utility classes
 
@@ -68,6 +99,16 @@ either coupled with ActiveRecord or ActionController in some way.
     progress.percentage_completed # => 100.0
     progress.next_step # => nil
 
+## Rails / ActiveRecord
+
+You can use progression as a gem or a plugin in your Rails application.  progression does not make any assumptions about the objects that you are interested in extending.
+
+Simply add an initializer:
+
+config/initializers/progression.rb
+
+    ActiveRecord::Base.send(:include, Progression)
+
 ## Note on Patches/Pull Requests
 
 * Fork the project.

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/lib/progression.rb

@@ -24,17 +24,24 @@ module Progression
 
     def initialize(&block)
       @steps = []
+      @percentage_values = {}
       instance_exec &block if block_given?
     end
 
     def progress_for(object)
-      Progress.new(object, steps)
+      Progress.new(object, self)
+    end
+
+    def percentage_value_for(step)
+      @percentage_values[step] || (1 / steps.size.to_f) * 100
     end
 
     private
 
-    def step(name, &block)
-      @steps << Step.new(name, &block)
+    def step(name, options = {}, &block)
+      step = Step.new(name, &block)
+      @steps << step
+      @percentage_values[step] = options[:percentage] if options[:percentage]
     end
 
   end
@@ -43,9 +50,10 @@ module Progression
 
     attr_reader :steps
 
-    def initialize(object, steps)
+    def initialize(object, progression)
       @object = object
-      @steps = steps
+      @progression = progression
+      @steps = progression.steps
     end
 
     def completed_steps
@@ -55,7 +63,9 @@ module Progression
     end
 
     def percentage_completed
-      (completed_steps.size / steps.size.to_f) * 100
+      completed_steps.inject(0) do |percentage_completed, step|
+        percentage_completed + @progression.percentage_value_for(step)
+      end
     end
 
     def next_step

data/progression.gemspec

@@ -0,0 +1,64 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{progression}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Michael Guterl"]
+  s.date = %q{2010-04-22}
+  s.description = %q{progression provides a set of simple utility classes and a DSL for
+measuring an objects progress through a progression of steps.  This is
+especially useful for defining and calculating profile completion
+status in a social application.
+
+There are a few existing solutions similar to progression, but they
+try to do too much.  The other options that I am familiar with are
+either coupled with ActiveRecord or ActionController in some way.
+}
+  s.email = %q{mguterl@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.md"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.md",
+     "Rakefile",
+     "VERSION",
+     "lib/progression.rb",
+     "progression.gemspec",
+     "rails/init.rb",
+     "spec/progression_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/mguterl/progression}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{progression provides a set of simple utility classes and a DSL for measuring an objects progress through a progression of steps}
+  s.test_files = [
+    "spec/progression_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+  end
+end
+

data/rails/init.rb

@@ -0,0 +1 @@
+require 'progression'

data/spec/progression_spec.rb

@@ -1,6 +1,6 @@
 require 'spec/spec_helper'
 
-class Profile < Struct.new(:first_name, :last_name)
+class Profile < Struct.new(:first_name, :last_name, :email)
 
   include Progression
 
@@ -16,6 +16,21 @@ class Profile < Struct.new(:first_name, :last_name)
 
   end
 
+  progression :registration do
+
+    step :step_1, :percentage => 25.0 do
+      !first_name.blank?
+    end
+
+    step :step_2, :percentage => 25.0 do
+      !last_name.blank?
+    end
+
+    step :step_3, :percentage => 50.0 do
+      !email.blank?
+    end
+  end
+
   # def self.profile_progression
   #   @progression ||= Progression::Progression.new do
   #     steps << Progression::Step.new(:step_1) { !first_name.blank? }
@@ -94,4 +109,49 @@ describe "Progression" do
 
   end
 
+  describe "explicit percentages" do
+
+    before do
+      @profile = Profile.new
+      @progression = @profile.registration_progress
+    end
+
+    it 'should return a list of steps' do
+      @progression.should have(3).steps
+    end
+
+    it 'should return a list of completed steps' do
+      @progression.should have(0).completed_steps
+    end
+
+    it 'should return the percentage completed' do
+      @progression.percentage_completed.should == 0.0
+    end
+
+    it 'should return the next step to be completed' do
+      @progression.next_step.name.should == :step_1
+    end
+
+    describe "after last step" do
+
+      before do
+        @profile.email = "foo@bar.com"
+      end
+
+      it 'should return a list of completed steps' do
+        @progression.should have(1).completed_steps
+      end
+
+      it 'should return the percentage completed' do
+        @progression.percentage_completed.should == 50.0
+      end
+
+      it 'should return the next step to be completed' do
+        @progression.next_step.name.should == :step_1
+      end
+
+    end
+
+  end
+
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Michael Guterl
@@ -57,6 +57,8 @@ files:
 - Rakefile
 - VERSION
 - lib/progression.rb
+- progression.gemspec
+- rails/init.rb
 - spec/progression_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb