voteable_mongoid 0.4.0 → 0.4.1

data/README.rdoc

@@ -0,0 +1,85 @@
+= Votable Mongoid
+
+Votable Mongoid allows you to make your Mongoid::Document objects votable (up or down)
+
+For instance, in a q&a site, a user can vote up (or down) on a post or a comment.
+
+== Installation
+
+=== Rails 3.0.x
+
+To install the gem, add this to your Gemfile
+
+  gem 'votable_mongoid'
+
+After that, remember to run "bundle install"
+
+== Usage
+
+=== Making Post and Comment votable, User being the voter
+
+post.rb
+
+    class Post
+      include Mongoid::Document
+      include Mongoid::Voteable
+
+      # set points for each vote
+      vote_point self, :up => +1, :down => -1
+
+      references_many :comments
+    end
+
+comment.rb
+
+    require 'post'
+
+    class Comment
+      include Mongoid::Document
+      include Mongoid::Voteable
+
+      referenced_in :post
+
+      vote_point self, :up => +1, :down => -3
+
+      # each vote on a comment can affect votes count and point of the related post as well
+      vote_point Post, :up => +2, :down => -1
+    end
+
+user.rb
+
+    class User
+      include Mongoid::Document
+      include Mongoid::Voter
+    end
+
+=== Making a vote
+
+    @user.vote(@post, :up)
+    # is equivalent to
+    @post.vote(:voter_id => @user.id, :value => :up)
+
+    # this will affect @post.votes_count and @post.votes_point as well
+    @user.vote(@comment, :down)
+
+=== Getting votes count and points
+
+    puts @post.votes_point
+    puts @post.votes_count
+    puts @post.up_votes_count
+    puts @post.down_votes_count
+
+=== Getting the list of voted objects (votees) of a class
+
+    @user.votees(Post)
+
+=== Undo a vote
+
+    @user.unvote(@comment)
+
+== Contributors
+
+* Alex N. - Author, Maintainer
+* Stefan N. - Unvoting
+
+Copyright (c) 2010-2011 Alex Nguyen (http://alex.vinova.sg) and Vinova Pre Ltd (http://vinova.sg)

data/lib/mongoid/voteable.rb

@@ -2,6 +2,8 @@ module Mongoid
   module Voteable
     extend ActiveSupport::Concern
 
+    # How many points should be assigned for each up or down vote.
+    # This array should be manipulated using Votable.vote_point method
     VOTE_POINT = {}
 
     included do
@@ -18,7 +20,7 @@ module Mongoid
       scope :most_voted, order_by(:votes_count.desc)
       scope :best_voted, order_by(:votes_point.desc)
       
-      
+      # Set vote point for each up (down) vote on an object of this class
       def self.vote_point(klass = self, options = nil)
         VOTE_POINT[self.name] ||= {}
         VOTE_POINT[self.name][klass.name] ||= options
@@ -29,6 +31,13 @@ module Mongoid
       # from voting value, we can decide it should be new vote or revote with :up or :down
       # In this case, validation can be skip to maximize performance
 
+      # Make a vote on an object of this class
+      #
+      # @param [Hash] options a hash containings:
+      #   - :votee_id: the votee document id
+      #   - :voter_id: the voter document id
+      #   - :value: :up or :down
+      #   - :revote: change from vote up to vote down
       def self.vote(options)
         options.symbolize_keys!
         
@@ -102,7 +111,13 @@ module Mongoid
           })
         end
       end
-      
+
+      # Cancel a vote on an object of this class
+      #
+      # @param [Hash] options a hash containings:
+      #   - :votee_id: the votee document id
+      #   - :voter_id: the voter document id
+      #   - :value: voted :up or :down
       def self.unvote(options)
         options.symbolize_keys!
                 
@@ -146,7 +161,11 @@ module Mongoid
       end
     end
   
-
+    # Make a vote on this votee
+    #
+    # @param [Hash] options a hash containings:
+    #   - :voter_id: the voter document id
+    #   - :value: vote :up or vote :down
     def vote(options)
       VOTE_POINT[self.class.name].each do |class_name, value_point|
         next unless relation_metadata = relations[class_name.underscore]
@@ -159,8 +178,12 @@ module Mongoid
 
       self.class.vote(options)
     end
-    
-    def unvote(options)  
+
+    # Cancel a vote on this votee
+    #
+    # @param [Hash] options a hash containings:
+    #   - :voter_id: the voter document id
+    def unvote(options)
       VOTE_POINT[self.class.name].each do |class_name, value_point|
         next unless relation_metadata = relations[class_name.underscore]
         next unless foreign_key = relation_metadata.foreign_key
@@ -172,6 +195,9 @@ module Mongoid
       self.class.unvote(options)
     end
 
+    # Get a voted value on this votee
+    #
+    # @param [String, BSON::ObjectId] x the id of the voter who made the vote
     def vote_value(x)
       voter_id = case x
       when String
@@ -186,15 +212,14 @@ module Mongoid
       return :down if down_voter_ids.try(:include?, voter_id)
     end
 
-
+    # Get the number of up votes
     def up_votes_count
       up_voter_ids.length
     end
     
-
+    # Get the number of down votes
     def down_votes_count
       down_voter_ids.length
     end
-    
   end
 end

data/lib/mongoid/voter.rb

@@ -2,12 +2,18 @@ module Mongoid
   module Voter
     extend ActiveSupport::Concern
 
-
+    # Get list of voted votees
+    #
+    # @param [Class] klass the votee class, e.g. `Post` or `Comment`
+    # @return [Array, nil] an array of votable objects voted by this voter
     def votees(klass)
       klass.any_of({ :up_voter_ids => _id }, { :down_voter_ids => _id })
     end
 
-
+    # Check to see if this voter voted on the votee or not
+    #
+    # @param [Hash, Object] options the hash containing the votee, or the votee itself
+    # @return [true, false] true if voted, false otherwise
     def voted?(options)
       unless options.is_a?(Hash)
         votee_class = options.class
@@ -25,11 +31,18 @@ module Mongoid
       
       votees(votee_class).where(:_id => votee_id).count == 1
     end
-    
+
+    # Cancel the vote on a votee
+    #
+    # @param [Object] votee the votee to be unvoted
     def unvote(votee)
       votee.unvote(:voter_id => _id)
     end
 
+    # Get the voted value on a votee
+    #
+    # @param (see #voted?)
+    # @return [Symbol, nil] :up or :down or nil if not voted
     def vote_value(options)
       votee = unless options.is_a?(Hash)
         options
@@ -41,7 +54,10 @@ module Mongoid
       votee.vote_value(_id)
     end
     
-  
+    # Vote on a votee
+    #
+    # @param (see #voted?)
+    # @param [:up, :down] vote_value vote up or vote down
     def vote(options, vote_value = nil)
       options.symbolize_keys!
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: voteable_mongoid
 version: !ruby/object:Gem::Version 
-  hash: 15
+  hash: 13
   prerelease: 
   segments: 
   - 0
   - 4
-  - 0
-  version: 0.4.0
+  - 1
+  version: 0.4.1
 platform: ruby
 authors: 
 - Alex Nguyen
@@ -88,121 +88,9 @@ dependencies:
   prerelease: false
   type: :development
   requirement: *id005
-- !ruby/object:Gem::Dependency 
-  name: bson_ext
-  version_requirements: &id006 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
-  type: :development
-  requirement: *id006
-- !ruby/object:Gem::Dependency 
-  name: rspec
-  version_requirements: &id007 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
-  type: :development
-  requirement: *id007
-- !ruby/object:Gem::Dependency 
-  name: bson_ext
-  version_requirements: &id008 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
-  type: :development
-  requirement: *id008
-- !ruby/object:Gem::Dependency 
-  name: rspec
-  version_requirements: &id009 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
-  type: :development
-  requirement: *id009
-- !ruby/object:Gem::Dependency 
-  name: bson_ext
-  version_requirements: &id010 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
-  type: :development
-  requirement: *id010
-- !ruby/object:Gem::Dependency 
-  name: rspec
-  version_requirements: &id011 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
-  type: :development
-  requirement: *id011
-- !ruby/object:Gem::Dependency 
-  name: bson_ext
-  version_requirements: &id012 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
-  type: :development
-  requirement: *id012
-- !ruby/object:Gem::Dependency 
-  name: rspec
-  version_requirements: &id013 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  prerelease: false
-  type: :development
-  requirement: *id013
 - !ruby/object:Gem::Dependency 
   name: mongoid
-  version_requirements: &id014 !ruby/object:Gem::Requirement 
+  version_requirements: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -216,10 +104,10 @@ dependencies:
         version: 2.0.0.rc
   prerelease: false
   type: :runtime
-  requirement: *id014
+  requirement: *id006
 - !ruby/object:Gem::Dependency 
   name: bson_ext
-  version_requirements: &id015 !ruby/object:Gem::Requirement 
+  version_requirements: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -230,10 +118,10 @@ dependencies:
         version: "0"
   prerelease: false
   type: :development
-  requirement: *id015
+  requirement: *id007
 - !ruby/object:Gem::Dependency 
   name: rspec
-  version_requirements: &id016 !ruby/object:Gem::Requirement 
+  version_requirements: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -244,7 +132,7 @@ dependencies:
         version: "0"
   prerelease: false
   type: :development
-  requirement: *id016
+  requirement: *id008
 description: Add Up / Down Voting for Mongoid
 email: alex@vinova.sg
 executables: []
@@ -252,11 +140,13 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
+- README.rdoc
 - TODO
 files: 
 - lib/mongoid/voteable.rb
 - lib/mongoid/voter.rb
 - lib/voteable_mongoid.rb
+- README.rdoc
 - TODO
 has_rdoc: true
 homepage: http://github.com/vinova/voteable_mongoid