acts_as_nps_rateable 0.0.4 → 0.0.5

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    NDE0YTQ5NWUwNjdkMjFmM2YyYzM3ZjdjYzU5MTk5OTQ0ODM5ODM4Mg==
-  data.tar.gz: !binary |-
-    Yjk5MmEyMjE1ODVmZDJmMDk3YTYxM2VmNTM3MTAxNzA5NzdkNTNlMA==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    OGI3YmVlNmNmM2I2Mzc1NDczMjJmYmYwMTUwMGRkM2E0ZjMxNTRkY2MxMGI5
-    NmI5YmYzN2NhYmQ2OGQwZmIzY2U3ODgxNGZkMjk0MjhiYTc3YmNmODkxYTcz
-    MTg0NDBhN2ExNzQ4ZGZjZjA3OWVkZmUxZjJkMDMyZmIyNDNkN2Y=
-  data.tar.gz: !binary |-
-    ZTU4YzNmY2M2ZmJjODY4NmNhYWUyYWUxNjUxOTM1OGFjMWI3OTFlOGZhYTY2
-    OGExY2I2ZTkyZDlmNTkwMDRkMmE4MjFjOTZiNDhkMWMwZWIyMWIzMzQ3N2Y2
-    NjljOGY3MTU5YzVjMmE5ZWE0MTU4YzBkYjkyYjU2ODUyYTM4MTE=
+SHA1:
+  metadata.gz: 6e58be26857db542d7dd276514b5788241047d96
+  data.tar.gz: 1e6fc6ba2fbdfa813d845211d70c893cf4b5bdd3
+SHA512:
+  metadata.gz: 6257642935cd4dc8173ebfa8575b6c1f3009a283b5abce8c86d5b094bbb0f9daf738af366fd88171ed5e324ea23ba925d4b953d729216a21f338beacbf3ad3ec
+  data.tar.gz: 1626017a39016b48797e6299bf3385dda58c400fa6e4831df7362237b3598bd73f5ddbb653442c59aec96198a173e8c9e789c9354b1ca5117afcffc6cf1119eb

data/.ruby-version

@@ -1 +1 @@
-1.9.3-p194
+ruby-2.2.2

data/Gemfile

@@ -2,3 +2,8 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in acts_as_nps_rateable.gemspec
 gemspec
+
+group :development do
+  gem 'yard'
+  gem 'activerecord'
+end

data/README.md

@@ -1,6 +1,10 @@
-# ActsAsNpsRateable
+# acts_as_nps_rateable
 
-TODO: Write a gem description
+acts_as_nps_rateable provides Net Promoter Score (NPS) ratings and analysis for your ActiveRecord-based models.  Net
+Promoter Score is a measurement of customer satisfaction; it is the ratio of the percentage of customers who would
+recommend your product/service to the percentage of customers who would not recommend it.
+
+NPS is documented in more detail at Wikipedia: http://en.wikipedia.org/wiki/Net_Promoter
 
 ## Installation
 
@@ -8,6 +12,10 @@ Add this line to your application's Gemfile:
 
     gem 'acts_as_nps_rateable'
 
+If you're adding this gem to a rails 3 application, you should change the line to be:
+
+    gem 'acts_as_nps_rateable', '=0.0.4'
+
 And then execute:
 
     $ bundle
@@ -16,9 +24,93 @@ Or install it yourself as:
 
     $ gem install acts_as_nps_rateable
 
+Once you've installed the gem, you'll need to install the migrations required by acts_as_nps_rateable into your project
+and run all pending migrations:
+
+    rails generate acts_as_nps_rateable:install
+    rake db:migrate
+
+Now you're ready to use acts_as_nps_rateable.
+
+## Upgrading
+
+If you're upgrading from a previous version of acts_as_nps_rateable, the major change here is that v0.0.5 is now only
+compatible with rails 4.2.  Making it rails 3 compatible shouldn't be a problem but I've moved on and don't have any
+rails 3 applications to add it to.
+
+I welcome a pull request that adds back rails 3 compatiblity.
+
 ## Usage
 
-TODO: Write usage instructions here
+### Setting up the Models
+
+acts_as_nps_rateable relies on the concept of rateables and raters.
+
+A rateable is any model which can be given a rating from 0 to 10 (inclusive) and an optional review.  An example of a
+rateable might be a Restaurant model.  Set up a rateable by adding the following line to the model you wish to be a
+rateable:
+
+    acts_as_nps_rateable
+
+e.g.
+
+    class Restaurant < ActiveRecord::Base
+      acts_as_nps_rateable
+    end
+
+A rater is any model which can give a rateable that rating and is essentially the user to attribute that rating to.  An
+example of a rater will usually be a User model it's possible to have multiple raters in your system e.g. an Employee
+and a Manager, both of which can rate any rateable.  Set up a rater by adding the following line to the model you wish
+to be a rater:
+
+    acts_as_nps_rater
+
+e.g.
+
+    class User < ActiveRecord::Base
+      acts_as_nps_rater
+    end
+
+### Rating
+
+Let's assume we have the User and Restaurant models in the system with specific instances of each in our code as follows:
+
+    snob = User.find(31337)
+    rateotu = Restaurant.find(42)
+
+Our rater has the following methods available to her:
+
+    snob.rate(rateotu, 5)               # Rates the restaurant a 5 on a scale from 0 to 10 inclusive
+    snob.rate(rateotu, 3)               # Overwrites the restaurant's rating to a 3
+    snob.average_rating                 # Returns the average score of all the ratings snob has given
+    snob.rated?(rateotu)                # Returns true if snob has rated this restaurant before.  False otherwise.
+    snob.rating_for(rateotu)            # Returns the score snob gave this restaurant before.  This could be nil.
+
+    snob.review("It was OK", rateotu)   # Adds a review to an existing rating by snob for this restaurant.
+
+Our rateable has the following methods available:
+
+    rateotu.rate(9, snob)               # Adds a rating for the restaurant by a given rater
+    rateotu.rate(10, snob)              # Overwrites the rating given by snob with a better number
+    rateotu.average_rating              # Returns the average score of all the ratings this restaurant has received
+    rateotu.rated_by?(snob)             # Returns true if snob has rated this restaurant before.  False otherwise.
+    rateotu.rating_by(snob)             # Returns the score snob gave this restaurant before.  This could be nil.
+
+    # We will use this recent_ratings variable in some examples below.  It's meant to be all ratings that were recorded
+    # in the last month.
+    recent_ratings = rateotu.nps_ratings.where("created_at > ?", 1.month.ago)
+
+    rateotu.promoters                   # Returns a count of the number of all ratings considered promoters in the NPS sense
+    rateotu.promoters(recent_ratings)   # Returns a count of the number of recent ratings considered promoters
+    rateotu.passives                    # Returns a count of the number of all ratings considered passives in the NPS sense
+    rateotu.passives(recent_ratings)    # Returns a count of the number of recent ratings considered passives
+    rateotu.detractors                  # Returns a count of the number of all ratings considered detractors in the NPS sense
+    rateotu.detractors(recent_ratings)  # Returns a count of the number of recent ratings considered detractors
+    
+    rateotu.net_promoter_score          # Returns the Net Promoter Score based on all ratings for this restaurant
+    rateotu.net_promoter_score(recent_ratings)  # Returns the Net Promoter Score based on recent ratings only
+    
+    rateotu.review("It was Great!", snob)   # Adds a review to an existing rating by snob for this restaurant
 
 ## Contributing
 

data/acts_as_nps_rateable.gemspec

@@ -12,8 +12,8 @@ Gem::Specification.new do |gem|
   gem.summary       = %q{Net Promoter Score ratings and analysis for ActiveRecord models}
   gem.homepage      = 'https://github.com/sjaveed/acts_as_nps_rateable'
 
-  gem.add_dependency 'activerecord', '~> 3.0'
-  gem.add_dependency 'rails', '~> 3.0'
+  gem.add_dependency 'activerecord', '>= 4.2.0'
+  gem.add_dependency 'rails', '>= 4.2.0'
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

data/lib/acts_as_nps_rateable.rb

@@ -2,7 +2,8 @@ require File.join(File.dirname(__FILE__), "acts_as_nps_rateable/railtie")
 
 module ActsAsNpsRateable
   autoload :Hook, File.join(File.dirname(__FILE__), "acts_as_nps_rateable/hook")
-  autoload :InstanceMethods, File.join(File.dirname(__FILE__), "acts_as_nps_rateable/instance_methods")
+  autoload :Rateable, File.join(File.dirname(__FILE__), "acts_as_nps_rateable/rateable")
+  autoload :Rater, File.join(File.dirname(__FILE__), "acts_as_nps_rateable/rater")
 end
 
 require 'nps_rating'

data/lib/acts_as_nps_rateable/hook.rb

@@ -1,10 +1,16 @@
+# @private
 # This is the hook that implements the acts_as_nps_rateable method
 # and includes all acts_as_nps_rateable instance methods as needed
-
 module ActsAsNpsRateable::Hook
   def acts_as_nps_rateable
     has_many :nps_ratings, :as => :nps_rateable, class_name: 'ActsAsNpsRateable::NpsRating', :dependent => :destroy
 
-    include ActsAsNpsRateable::InstanceMethods
+    include ActsAsNpsRateable::Rateable
+  end
+
+  def acts_as_nps_rater
+    has_many :nps_ratings, :as => :rater, class_name: 'ActsAsNpsRateable::NpsRating', :dependent => :destroy
+
+    include ActsAsNpsRateable::Rater
   end
 end

data/lib/acts_as_nps_rateable/railtie.rb

@@ -1,4 +1,5 @@
 module ActsAsNpsRateable
+  # @private
   class Railtie < Rails::Railtie
     # Extend ActiveRecord::Base here and include ActsAsNpsRateable instance methods
     config.to_prepare do

data/lib/acts_as_nps_rateable/rateable.rb

@@ -0,0 +1,156 @@
+##
+# acts_as_nps_rateable is a library that provides the following functionality:
+# * Net Promoter Score recording and analysis functionality.
+# * Storing comments in addition to a rating
+# * One response per comment from the entity being reviewed
+# * Upvoting or downvoting comments (as many times as someone wants)
+#
+# These are all the instance methods that <code>acts_as_nps_rateable</code> includes into a model
+module ActsAsNpsRateable::Rateable
+  ##
+  # Rate this rateable ensuring there's at most only one rating per rater per rateable
+  #
+  # @param [Integer] score
+  #   This is the actual rating this rateable is getting
+  # @param [ActsAsNpsRateable::Rater] rater
+  #   This is the rater who is rating this particular rateable.  Nothing happens if this is absent.
+  def rate(score, rater)
+    return unless rater.present?
+
+    ActiveRecord::Base.transaction do
+      ratings_by(rater).delete_all
+      nps_ratings.create(score: score.to_i, rater: rater)
+    end
+  end
+
+  ##
+  # Returns the average of all ratings for this rateable
+  #
+  # @return [Float] the average of all ratings for this rateable
+  #   This uses the database average aggregation
+  def average_rating
+    nps_ratings.average(:score)
+  end
+
+  ##
+  # Checks whether a rater has already rated this rateable
+  #
+  # @param [ActsAsNpsRateable::Rater] rater
+  #   The rater who might have rated this rateable before
+  #
+  # @return [Boolean] if a rater was specified
+  # @return nil if rater is nil
+  def rated_by?(rater)
+    return unless rater.present?
+
+    ratings_by(rater).any?
+  end
+
+  ##
+  # Get the rating given to this rateable by a rater
+  #
+  # @param [ActsAsNpsRateable::Rater] rater
+  #   The rater who might have rated this rateable before.
+  #
+  # @return [Boolean] if a rater was specified
+  # @return nil if rater is nil
+  def rating_by(rater)
+    return unless rater.present?
+
+    ratings_by(rater).first
+  end
+
+  ##
+  # Returns the number of ratings which are classified as promoters.  Promoters are any ratings where the score is
+  # greater than 8
+  #
+  # @param [ActiveRecord::Relation<ActsAsNpsRateable::NpsRating>] ratings
+  #   These are optional ratings - typically a subset of the whole - which you want to calculate the promoter count from
+  # @return [Integer] the number of promoter ratings among all the ratings for this rateable if ratings is nil
+  # @return [Integer] the number of promoter ratings among the given ratings if ratings is not nil
+  def promoters ratings = nil
+    if ratings.nil?
+      nps_ratings.promoters.size
+    else
+      ratings.promoters.size
+    end
+  end
+
+  ##
+  # Returns the number of ratings which are classified as passives.  Passives are any ratings where the score is
+  # either 7 or 8
+  #
+  # @param [ActiveRecord::Relation<ActsAsNpsRateable::NpsRating>] ratings
+  #   These are optional ratings - typically a subset of the whole - which you want to calculate the passive count from
+  # @return [Integer] the number of passive ratings among all the ratings for this rateable if ratings is nil
+  # @return [Integer] the number of passive ratings among the given ratings if ratings is not nil
+  def passives ratings = nil
+    if ratings.nil?
+      nps_ratings.passives.size
+    else
+      ratings.passives.size
+    end
+  end
+
+  ##
+  # Returns the number of ratings which are classified as detractors.  Passives are any ratings where the score is
+  # less than 7
+  #
+  # @param [ActiveRecord::Relation<ActsAsNpsRateable::NpsRating>] ratings
+  #   These are optional ratings - typically a subset of the whole - which you want to calculate the detractor count from
+  # @return [Integer] the number of detractor ratings among all the ratings for this rateable if ratings is nil
+  # @return [Integer] the number of detractor ratings among the given ratings if ratings is not nil
+  def detractors ratings = nil
+    if ratings.nil?
+      nps_ratings.detractors.size
+    else
+      ratings.detractors.size
+    end
+  end
+
+  ##
+  # Calculates the Net Promoter Score as defined at http://www.checkmarket.com/2011/06/net-promoter-score/
+  #
+  # @param [ActiveRecord::Relation<ActsAsNpsRateable::NpsRating>] ratings
+  #   These are optional ratings - typically a subset of the whole - which you want to calculate the Net Promoter Score
+  #   from
+  # @return [Integer] the Net Promoter Score based on all the ratings for this rateable if ratings is nil
+  # @return [Integer] the Net Promoter Score based on the given ratings if ratings is not nil
+  def net_promoter_score ratings = nil
+    total_ratings = ratings.nil? ? nps_ratings.size : ratings.size
+    return 0 if total_ratings.zero?
+
+    if ratings.nil?
+      (promoters - detractors) * 100 / total_ratings
+    else
+      (promoters(ratings) - detractors(ratings)) * 100 / total_ratings
+    end
+  end
+
+  ##
+  # Add an optional review to this rateable only if this rater has previously rated this rateable.
+  #
+  # @param [String] comment
+  #   The actual comment
+  # @param [ActsAsNpsRateable::Rater] rater
+  #   This is the rater who is rating this particular rateable.  Nothing happens if this is absent.
+  def review(comment, rater)
+    return unless rater.present?
+
+    ratings_by(rater).update_all(comments: comment)
+  end
+
+  private
+
+  ##
+  # A convenience method to DRY up the logic of fetching all ratings for this rateable by a given rater
+  #
+  # @param [ActsAsNpsRateable::Rater] rater
+  #   This is the rater for whom you want ratings retrieved
+  # @return [ActiveRecord::Relation<ActsAsNpsRateable::NpsRating>]
+  #   the list of ratings by the rater for this rateable
+  def ratings_by(rater)
+    nps_ratings.where(rater: rater)
+  end
+
+end

data/lib/acts_as_nps_rateable/rater.rb

@@ -0,0 +1,80 @@
+# These are all the instance methods that acts_as_nps_rater includes into an ActiveModel
+
+module ActsAsNpsRateable::Rater
+  ##
+  # As this rater, rate the specified rateable ensuring there's at most only one rating per rater per rateable
+  #
+  # @param [ActsAsNpsRateable::Rateable] rateable
+  #   This is the rateable which this rater is rating.  Nothing happens if this is absent.
+  # @param [Integer] score
+  #   This is the actual rating this rater is giving
+  def rate(rateable, score)
+    ActiveRecord::Base.transaction do
+      ratings_for(rateable).delete_all
+      nps_ratings.create(nps_rateable: rateable, score: score.to_i)
+    end
+  end
+
+  ##
+  # Returns the average of all ratings this rater has ever given
+  #
+  # @return [Float] the average of all ratings this rater has given
+  #   This uses the database average aggregation
+  def average_rating
+    nps_ratings.average(:score)
+  end
+
+  ##
+  # Checks whether this rater has already rated a rateable
+  #
+  # @param [ActsAsNpsRateable::Rateable] rateable
+  #   The rateable that this rater might have rated before
+  #
+  # @return [Boolean] if a rateable was specified
+  # @return nil if rater is nil
+  def rated?(rateable)
+    return unless rateable.present?
+
+    ratings_for(rateable).any?
+  end
+
+  ##
+  # Get the rating this rater has given to a rateable
+  #
+  # @param [ActsAsNpsRateable::Rateable] rateable
+  #   The rateable that this rater might have rated before.
+  #
+  # @return [Boolean] if a rateable was specified
+  # @return nil if rater is nil
+  def rating_for(rateable)
+    return unless rateable.present?
+
+    ratings_for(rateable).first
+  end
+
+  ##
+  # Add an optional review by this rater to a rateable only if this rater has previously rated that rateable
+  #
+  # @param [String] comment
+  #   The actual comment
+  # @param [ActsAsNpsRateable::Rateable] rateable
+  #   This is the rateable for which this rater is adding a review.  Nothing happens if this is absent.
+  def review(comment, rateable)
+    return unless rateable.present?
+
+    ratings_for(rateable).update_all(comments: comment)
+  end
+
+  private
+
+  ##
+  # A convenience method to DRY up the logic of fetching all ratings by this rater for a given rateable
+  #
+  # @param [ActsAsNpsRateable::Rateable] rateable
+  #   This is the rateable for which you want ratings retrieved
+  # @return [ActiveRecord::Relation<ActsAsNpsRateable::NpsRating>]
+  #   the list of ratings for the rateable by this rater
+  def ratings_for(rateable)
+    nps_ratings.where(nps_rateable: rateable)
+  end
+end

data/lib/acts_as_nps_rateable/version.rb

@@ -1,3 +1,3 @@
 module ActsAsNpsRateable
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/lib/generators/acts_as_nps_rateable/install_generator.rb

@@ -1,6 +1,7 @@
 require 'rails/generators/migration'
 
 module ActsAsNpsRateable
+  # @private
   class InstallGenerator < Rails::Generators::Base
     include Rails::Generators::Migration
 
@@ -10,13 +11,27 @@ module ActsAsNpsRateable
       Time.now.utc.strftime("%Y%m%d%H%M%S")
     end
 
-    def create_migration
-      migration_template '01-migration.rb', 'db/migrate/acts_as_nps_rateable_migration'
-      migration_template '02-migration.rb', 'db/migrate/acts_as_nps_rateable_migration_upgrade_0_0_2'
+    def create_nps_rateable_migrations
+      migration_mapping = {
+          '01-migration' => 'acts_as_nps_rateable_migration',
+          '02-migration' => 'acts_as_nps_rateable_migration_upgrade_0_0_2',
+          '03-migration' => 'acts_as_nps_rateable_migration_upgrade_0_0_5',
+          '04-migration' => 'acts_as_nps_rateable_migration_usefulness_upgrade'
+      }
+
+      migration_mapping.keys.sort.each do |src|
+        tgt = migration_mapping[src]
+
+        if self.class.migration_exists? 'db/migrate', tgt
+          puts "Not over-writing existing migration: #{tgt}"
+        else
+          migration_template "#{src}.rb", "db/migrate/#{tgt}.rb"
+          sleep 1
+        end
+      end
     end
 
     def install_models
-      #template 'nps_rating.rb', 'app/models/nps_rating.rb'
     end
   end
 end

data/lib/generators/acts_as_nps_rateable/templates/01-migration.rb

@@ -1,3 +1,4 @@
+# @private
 class ActsAsNpsRateableMigration < ActiveRecord::Migration
   def change
     create_table :nps_ratings do |t|

data/lib/generators/acts_as_nps_rateable/templates/02-migration.rb

@@ -1,4 +1,5 @@
-class ActsAsNpsRateableMigration < ActiveRecord::Migration
+# @private
+class ActsAsNpsRateableMigrationUpgrade002 < ActiveRecord::Migration
   def change
     add_column :nps_ratings, :comments, :text
   end

data/lib/generators/acts_as_nps_rateable/templates/03-migration.rb

@@ -0,0 +1,11 @@
+# @private
+class ActsAsNpsRateableMigrationUpgrade005 < ActiveRecord::Migration
+  def change
+    remove_index :nps_ratings, column: [:nps_rateable_type, :nps_rateable_id, :user_id], unique: true, name: "acts_as_nps_rateable_unique_index"
+
+    rename_column :nps_ratings, :user_id, :rater_id
+    add_column :nps_ratings, :rater_type, :string, default: 'User'
+
+    add_index :nps_ratings, [:nps_rateable_type, :nps_rateable_id, :rater_type, :rater_id], unique: true, name: "acts_as_nps_rateable_unique_index"
+  end
+end

data/lib/generators/acts_as_nps_rateable/templates/04-migration.rb

@@ -0,0 +1,11 @@
+# @private
+class ActsAsNpsRateableMigrationUsefulnessUpgrade < ActiveRecord::Migration
+  def change
+    add_column :nps_ratings, :up_votes, :integer, default: 0, null: false
+    add_column :nps_ratings, :down_votes, :integer, default: 0, null: false
+    add_column :nps_ratings, :net_votes, :integer, default: 0, null: false
+
+    add_column :nps_ratings, :response, :text
+    add_column :nps_ratings, :responded_at, :timestamp
+  end
+end

data/lib/nps_rating.rb

@@ -1,30 +1,47 @@
+##
+# acts_as_nps_rateable is a library that provides the following functionality:
+# * Net Promoter Score recording and analysis functionality.
+# * Storing comments in addition to a rating
+# * One response per comment from the entity being reviewed
+# * Upvoting or downvoting comments (as many times as someone wants)
 module ActsAsNpsRateable
+  ##
+  # This is the actual model that stores a rating, a review (if any), its response (if any) and a count of upvotes and
+  # downvotes
   class NpsRating < ActiveRecord::Base
     self.table_name = 'nps_ratings'
 
     belongs_to :nps_rateable, polymorphic: true
-    belongs_to :user
+    belongs_to :rater, polymorphic: true
 
     validates_presence_of :score
     validates_numericality_of :score, only_integer: true
     validates_inclusion_of :score, in: (0..10).to_a, message: 'must be between 0 and 10'
 
-    validates_presence_of :nps_rateable_id
-    validates_presence_of :nps_rateable_type
+    validates_presence_of :nps_rateable
+    validates_presence_of :rater
+    validates_uniqueness_of :rater_id, scope: [:rater_type, :nps_rateable_type, :nps_rateable_id], message: 'has already rated'
 
-    validates_presence_of :user_id
-    validates_uniqueness_of :user_id, scope: [:nps_rateable_type, :nps_rateable_id], message: 'has already rated'
+    scope :promoters, lambda { where(score: [9, 10]) }
+    scope :passives, lambda { where(score: [7, 8]) }
+    scope :detractors, lambda { where(NpsRating.arel_table[:score].lteq(6)) }
 
-    before_save :remove_blank_comments
-
-    scope :promoters, where(score: [9, 10])
-    scope :passives, where(score: [7, 8])
-    scope :detractors, where('score <= 6')
-    scope :with_comments, where('comments IS NOT NULL')
+    scope :with_comments, lambda { where.not(comments: nil) }
 
+    ##
+    # Returns the Net Promoter Score for the given collection of ratings.
+    #
+    # @param [ActiveRecord::Relation<NpsRating>] relevant_ratings
+    #   This is essentially the result of an ActiveRecord query for nps_ratings
+    #
+    # @example
+    #   NpsRating.calculate_for(fancy_product.nps_ratings)
+    #
+    # @return [Float] The calculated Net Promoter Score.
+    #   This is 0 if <code>relevant_ratings.size</code> is 0
     def self.calculate_for relevant_ratings
       total_ratings = relevant_ratings.size
-      return 0 if total_ratings == 0
+      return 0 if total_ratings.zero?
 
       promoters = relevant_ratings.promoters.size
       detractors = relevant_ratings.detractors.size
@@ -32,10 +49,33 @@ module ActsAsNpsRateable
       ((promoters - detractors) * 100.0 / total_ratings).round
     end
 
-    private
+    ##
+    # @!attribute [w] comments
+    #   Ensures that any comments that are recorded are non-blank
+    def comments= comments
+      write_attribute(:comments, comments.present? ? comments : nil)
+    end
+
+    ##
+    # @!attribute [w] response
+    #   Ensures that when a non-blank response is recorded, the responded_at time is also updated to the current time
+    def response= response
+      if response.present?
+        write_attribute(:response, response)
+        write_attribute(:responded_at, Time.now)
+      end
+    end
+
+    ##
+    # Upvotes a rating atomically.  Duplicate votes are possible.
+    def upvote!
+      ActsAsNpsRateable::NpsRating.update_counters(id, up_votes: 1, net_votes: 1)
+    end
 
-    def remove_blank_comments
-      write_attribute(:comments, nil) if comments.blank?
+    ##
+    # Downvotes a rating atomically.  Duplicate votes are possible.
+    def downvote!
+      ActsAsNpsRateable::NpsRating.update_counters(id, down_votes: 1, net_votes: -1)
     end
   end
 end

metadata

@@ -1,43 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: acts_as_nps_rateable
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Shahbaz Javeed
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-08 00:00:00.000000000 Z
+date: 2015-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 4.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 4.2.0
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 4.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 4.2.0
 description: Rails gem that provides Net Promoter Score (NPS) ratings and analysis
   for ActiveRecord models.  It can be used as a regular 0 to 10 rating scale and you
   can just ignore the NPS analysis methods.
@@ -47,9 +47,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .ruby-gemset
-- .ruby-version
+- ".gitignore"
+- ".ruby-gemset"
+- ".ruby-version"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -57,12 +57,15 @@ files:
 - acts_as_nps_rateable.gemspec
 - lib/acts_as_nps_rateable.rb
 - lib/acts_as_nps_rateable/hook.rb
-- lib/acts_as_nps_rateable/instance_methods.rb
 - lib/acts_as_nps_rateable/railtie.rb
+- lib/acts_as_nps_rateable/rateable.rb
+- lib/acts_as_nps_rateable/rater.rb
 - lib/acts_as_nps_rateable/version.rb
 - lib/generators/acts_as_nps_rateable/install_generator.rb
 - lib/generators/acts_as_nps_rateable/templates/01-migration.rb
 - lib/generators/acts_as_nps_rateable/templates/02-migration.rb
+- lib/generators/acts_as_nps_rateable/templates/03-migration.rb
+- lib/generators/acts_as_nps_rateable/templates/04-migration.rb
 - lib/nps_rating.rb
 homepage: https://github.com/sjaveed/acts_as_nps_rateable
 licenses: []
@@ -73,18 +76,19 @@ 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.0.6
+rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
 summary: Net Promoter Score ratings and analysis for ActiveRecord models
 test_files: []
+has_rdoc: 

data/lib/acts_as_nps_rateable/instance_methods.rb

@@ -1,63 +0,0 @@
-# These are all the instance methods that acts_as_nps_rateable includes into an ActiveModel
-
-module ActsAsNpsRateable::InstanceMethods
-  # rate this rateable ensuring there's at most only one rating per user per rateable
-  def rate(score, user)
-    ActiveRecord::Base.transaction do
-      nps_ratings.where(user_id: user.id).delete_all if user.present?
-      nps_ratings.create(score: score.to_i, user_id: user.id)
-    end
-  end
-
-  # the average of all ratings for this rateable
-  def average_rating
-    nps_ratings.average(:score)
-  end
-
-  # a check to see if the specified user has already rated this rateable
-  def rated_by?(user)
-    return unless user.present?
-
-    nps_ratings.where(user_id: user.id).size > 0
-  end
-
-  #
-  # Net Promoter Score Calculations: http://www.checkmarket.com/2011/06/net-promoter-score/
-  #
-
-  def promoters ratings = nil
-    if ratings.nil?
-      nps_ratings.promoters.size
-    else
-      ratings.promoters.size
-    end
-  end
-
-  def passives ratings = nil
-    if ratings.nil?
-      nps_ratings.passives.size
-    else
-      ratings.passives.size
-    end
-  end
-
-  def detractors ratings = nil
-    if ratings.nil?
-      nps_ratings.detractors.size
-    else
-      ratings.detractors.size
-    end
-  end
-
-  def net_promoter_score ratings = nil
-    total_ratings = ratings.nil? ? nps_ratings.size : ratings.size
-    return 0 if total_ratings == 0
-
-    if ratings.nil?
-      (promoters - detractors) * 100 / total_ratings
-    else
-      (promoters(ratings) - detractors(ratings)) * 100 / total_ratings
-    end
-  end
-
-end