acts_as_votable 0.0.5 → 0.1.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    acts_as_votable (0.0.4)
+    acts_as_votable (0.0.5)
       rails (>= 3.0.0)
 
 GEM

data/README.markdown

@@ -0,0 +1,200 @@
+### Major Updates
+
+Version 0.1.0 introduces new and refactored function calls that improve the
+natural language syntax of this gem.  Certain calls that were compatible with
+version 0.0.5 will now be broken.  Remember to specify a the version in your
+Gemfile to prevent functionality breakdowns between versions.
+
+In version 0.1.0 functions like ``@post.votes`` return an array of all of the vote
+records for @post.  In order to count the number of votes simply use
+``@post.votes.size`` now.
+
+- - -
+
+# Acts As Votable (aka Acts As Likeable)
+
+Acts As Votable is a Ruby Gem specifically written for Rails/ActiveRecord models.
+The main goals of this gem are:
+
+- Allow any model to be voted on, like/dislike, upvote/downvote, etc.
+- Allow any model to vote.  In other words, votes do not have to come from a user,
+  they can come from any model (such as a Group or Team).
+- Provide an easy to write natural language syntax.
+
+## Installation
+
+### Rails 3
+
+Just add the following to your Gemfile.
+
+    gem 'acts_as_votable'
+
+And follow that up with a ``bundle install``.
+
+### Database Migrations
+
+Acts As Votable uses a votes table to store all voting information.  To
+generate and run the migration just use.
+
+    rails generate acts_as_votable:migration
+    rake db:migrate
+
+You will get a performance increase by adding in cached columns to your model's
+tables.  You will have to do this manually through your own migrations.  See the
+caching section of this document for more information.
+
+## Usage
+
+### Votable Models
+
+    class Post < ActiveRecord::Base
+      acts_as_votable
+    end
+
+    @post = Post.new(:name => 'my post!')
+    @post.save
+
+    @post.liked_by @user
+    @post.votes.size # => 1
+
+### Like/Dislike Yes/No Up/Down
+
+Here are some voting examples.  All of these calls are valid and acceptable.  The
+more natural calls are the first few examples.
+
+    @post.liked_by @user1
+    @post.downvote_from @user2
+    @post.vote :voter => @user3
+    @post.vote :voter => @user4, :vote => 'bad'
+    @post.vote :voter => @user5, :vote => 'like'
+
+
+By default all votes are positive, so @user3 has cast a 'good' vote for @post.
+
+@user1, @user3, and @user5 all voted in favor of @post.
+
+@user2 and @user4 on the other had has voted against @post.
+
+
+Just about any word works for casting a vote in favor or against post.  Up/Down,
+Like/Dislike, Positive/Negative... the list goes on-and-on.  Boolean flags ``true`` and
+``false`` are also applicable.
+
+Revisiting the previous example of code.
+
+    # positive votes
+    @post.liked_by @user1
+    @post.vote :voter => @user3
+    @post.vote :voter => @user5, :vote => 'like'
+
+    # negative votes
+    @post.downvote_from @user2
+    @post.vote :voter => @user2, :vote => 'bad'
+    
+    # tally them up!
+    @post.votes.size # => 5
+    @post.likes.size # => 3
+    @post.upvotes.size # => 3
+    @post.dislikes.size # => 2
+    @post.downvotes.size # => 2
+
+### The Voter
+
+You can have your voters ``acts_as_voter`` to provide some reserve functionality.
+
+    class User < ActiveRecord::Base
+      acts_as_voter
+    end
+
+    @user.likes @article
+
+    @article.votes.size # => 1
+    @article.likes.size # => 1
+    @article.downvotes.size # => 0
+
+To check if a voter has voted on a model, you can use ``voted_for?``.  You can
+check how the voter voted by using ``voted_as_when_voted_for``.
+
+    @user.likes @comment1
+    @user.up_votes @comment2
+    # user has not voted on @comment3
+
+    @user.voted_for? @comment1 # => true
+    @user.voted_for? @comment2 # => true
+    @user.voted_for? @comment3 # => false
+
+    @user.voted_as_when_voted_for @comment1 # => true, he liked it
+    @user.voted_as_when_voted_for @comment2 # => false, he didnt like it
+    @user.voted_as_when_voted_for @comment3 # => nil, he has yet to vote
+
+### Registered Votes
+
+Voters can only vote once per model.  In this example the 2nd vote does not count
+because @user has already voted for @shoe.
+
+    @user.likes @shoe
+    @user.upvotes @shoe
+
+    @shoe.votes # => 1
+    @shoe.likes # => 1
+
+To check if a vote counted, or registered, use vote_registered? on your model
+directly after voting.  For example:
+
+    @hat.liked_by @user
+    @hat.vote_registered? # => true
+
+    @hat.liked_by => @user
+    @hat.vote_registered? # => false, because @user has already voted this way
+
+    @hat.disliked_by @user
+    @hat.vote_registered? # => true, because user changed their vote
+
+    @hat.votes.size # => 1
+    @hat.positives.size # => 0
+    @hat.negatives.size # => 1
+
+## Caching
+
+To speed up perform you can add cache columns to your votable model's table.  These
+columns will automatically be updated after each vote.  For example, if we wanted
+to speed up @post we would use the following migration:
+
+    class AddCachedVotesToPosts < ActiveRecord::Migration
+      def self.up
+        add_column :posts, :cached_votes_total, :integer, :default => 0
+        add_column :posts, :cached_votes_up, :integer, :default => 0
+        add_column :posts, :cached_votes_down, :integer, :default => 0
+        add_index  :posts, :cached_votes_total
+        add_index  :posts, :cached_votes_up
+        add_index  :posts, :cached_votes_down
+      end
+
+      def self.down
+        remove_column :posts, :cached_votes_total
+        remove_column :posts, :cached_votes_up
+        remove_column :posts, :cached_votes_down
+      end
+    end
+
+## Testing
+
+All tests follow the RSpec format and are located in the spec directory
+
+## Thanks
+
+A huge thank you to Michael Bleigh and his Acts-As-Taggable-On gem.  I learned
+how to write gems by following his source code.
+
+## TODO
+
+- Smarter language syntax.  Example: ``@user.likes`` will return all of the votables
+that the user likes, while ``@user.likes @model`` will cast a vote for @model by
+@user.
+
+- Need to test a model that is votable as well as a voter
+
+- The aliased functions are referred to by using the terms 'up/down' amd/or
+'true/false'.  Need to come up with guidelines for naming these function.
+
+- Create more aliases. Specifically for counting votes and finding votes.

data/lib/acts_as_votable/alias.rb

@@ -3,7 +3,7 @@ module ActsAsVotable::Alias
   def self.words_to_alias object, words, call_function
     words.each do |word|
       if word.is_a?(String)
-        function = word.pluralize.to_sym
+        function = word.to_sym
         if !object.respond_to?(function)
           object.send(:alias_method, function, call_function)
         end

data/lib/acts_as_votable/init/votable.rb

@@ -20,8 +20,16 @@ module ActsAsVotable::Init
       end
 
       # aliasing
-      ActsAsVotable::Alias::words_to_alias self, ActsAsVotable::Vote.true_votes, :count_votes_true
-      ActsAsVotable::Alias::words_to_alias self, ActsAsVotable::Vote.false_votes, :count_votes_false
+
+      # voting
+      ActsAsVotable::Alias::words_to_alias self, %w(up_by upvote_by like_by liked_by vote_by), :vote_up
+      ActsAsVotable::Alias::words_to_alias self, %w(up_from upvote_from like_from liked_from vote_from), :vote_up
+      ActsAsVotable::Alias::words_to_alias self, %w(down_by downvote_by dislike_by disliked_by), :vote_down
+      ActsAsVotable::Alias::words_to_alias self, %w(down_from downvote_from dislike_from disliked_from), :vote_down
+
+      # finding
+      ActsAsVotable::Alias::words_to_alias self, %w(true_votes ups upvotes likes positives), :up_votes
+      ActsAsVotable::Alias::words_to_alias self, %w(false_votes downs downvotes dislikes negatives), :down_votes
 
     end
 

data/lib/acts_as_votable/init/voter.rb

@@ -18,6 +18,9 @@ module ActsAsVotable::Init
 
         include ActsAsVotable::Voter
 
+        ActsAsVotable::Alias::words_to_alias self, %w(likes upvotes up_votes), :vote_up_for
+        ActsAsVotable::Alias::words_to_alias self, %w(dislikes downvotes down_votes), :vote_down_for
+
       end
 
     end

data/lib/acts_as_votable/version.rb

@@ -1,3 +1,3 @@
 module ActsAsVotable
-  VERSION = "0.0.5"
+  VERSION = "0.1.0"
 end

data/lib/acts_as_votable/votable.rb

@@ -25,6 +25,7 @@ module ActsAsVotable
         }
       end
 
+      # voting
       def vote args = {}
 
         options = ActsAsVotable::Vote.default_voting_args.merge(args)
@@ -67,6 +68,14 @@ module ActsAsVotable
        
       end
 
+      def vote_up voter
+        self.vote :voter => voter, :vote => true
+      end
+
+      def vote_down voter
+        self.vote :voter => voter, :vote => false
+      end
+
       # caching
       def update_cached_votes
 
@@ -77,11 +86,11 @@ module ActsAsVotable
         end
 
         if self.respond_to?(:cached_votes_up=)
-          updates[:cached_votes_up] = count_votes_true(true)
+          updates[:cached_votes_up] = count_votes_up(true)
         end
 
         if self.respond_to?(:cached_votes_down=)
-          updates[:cached_votes_down] = count_votes_false(true)
+          updates[:cached_votes_down] = count_votes_down(true)
         end
 
         self.update_attributes(updates) if updates.size > 0
@@ -93,27 +102,37 @@ module ActsAsVotable
       def find_votes extra_conditions = {}
         ActsAsVotable::Vote.find(:all, :conditions => default_conditions.merge(extra_conditions))
       end
+      alias :votes :find_votes
+
+      def up_votes
+        find_votes(:vote_flag => true)
+      end
+
+      def down_votes
+        find_votes(:vote_flag => false)
+      end
+
 
+      # counting
       def count_votes_total skip_cache = false
         if !skip_cache && self.respond_to?(:cached_votes_total)
           return self.send(:cached_votes_total)
         end
         find_votes.size
       end
-      alias :votes :count_votes_total
 
-      def count_votes_true skip_cache = false
+      def count_votes_up skip_cache = false
         if !skip_cache && self.respond_to?(:cached_votes_up)
           return self.send(:cached_votes_up)
         end
-        find_votes(:vote_flag => true).size
+        up_votes.size
       end
 
-      def count_votes_false skip_cache = false
+      def count_votes_down skip_cache = false
         if !skip_cache && self.respond_to?(:cached_votes_down)
           return self.send(:cached_votes_down)
         end
-        find_votes(:vote_flag => false).size
+        down_votes.size
       end
 
       # voters

data/lib/acts_as_votable/vote.rb

@@ -13,11 +13,11 @@ module ActsAsVotable
     validates_presence_of :voter_id
 
     def self.true_votes
-      ['up', 'upvote', 'like', 'yes', 'good', 'true', 1, true]
+      ['up', 'upvote', 'like', 'liked', 'positive', 'yes', 'good', 'true', 1, true]
     end
 
     def self.false_votes
-      ['down', 'downvote', 'dislike', 'no', 'bad', 'false', 0, false]
+      ['down', 'downvote', 'dislike', 'disliked', 'negative', 'no', 'bad', 'false', 0, false]
     end
 
     ##

data/lib/acts_as_votable/voter.rb

@@ -18,6 +18,20 @@ module ActsAsVotable
         }
       end
 
+      # voting
+      def vote args
+        args[:votable].vote args.merge({:voter => self})
+      end
+
+      def vote_up_for model
+        vote :votable => model, :vote => true
+      end
+
+      def vote_down_for model
+        vote :votable => model, :vote => false
+      end
+
+      # results
       def voted_on? votable
         votes = find_votes(:votable_id => votable.id, :votable_type => votable.class.name)
         votes.size > 0
@@ -31,16 +45,30 @@ module ActsAsVotable
       end
       alias :voted_as_when_voting_for :voted_as_when_voting_on
 
+      
       def find_votes extra_conditions = {}
         ActsAsVotable::Vote.find(:all, :conditions => default_conditions.merge(extra_conditions))
       end
+      alias :votes :find_votes
 
-      def total_votes_for_class klass
-        find_votes({:votable_type => klass.name}).size
+      def find_up_votes
+        find_votes :vote_flag => true
       end
 
-      def vote args
-        args[:votable].vote args.merge({:voter => self})
+      def find_down_votes
+        find_votes :vote_flag => false
+      end
+
+      def find_votes_for_class klass, extra_conditions = {}
+        find_votes extra_conditions.merge({:votable_type => klass.name})
+      end
+
+      def find_up_votes_for_class klass
+        find_votes_for_class klass, :vote_flag => true
+      end
+
+      def find_down_votes_for_class klass
+        find_votes_for_class klass, :vote_flag => false
       end
 
     end

data/spec/alias_spec.rb

@@ -5,27 +5,60 @@ describe ActsAsVotable::Alias do
 
   before(:each) do
     clean_database
-    @votable = Votable.new(:name => 'votable with aliases')
-    @votable.save
-
-    @voter = Voter.new(:name => 'a voter')
-    @voter.save
   end
 
-  it "should alias a bunch of functions" do
-    @votable.respond_to?(:upvotes).should be true
-    @votable.respond_to?(:ups).should be true
-    @votable.respond_to?(:dislikes).should be true
-  end
+  describe "votable models" do
+
+    before(:each) do
+      clean_database
+      @votable = Votable.new(:name => 'votable with aliases')
+      @votable.save
+
+      @voter = Voter.new(:name => 'a voter')
+      @voter.save
+    end
+
+    it "should alias a bunch of functions" do
+      
+      # voting
+      @votable.respond_to?(:disliked_by).should be true
+      @votable.respond_to?(:up_from).should be true
+
+      # results
+      @votable.respond_to?(:upvotes).should be true
+      @votable.respond_to?(:ups).should be true
+      @votable.respond_to?(:dislikes).should be true
 
-  it "should only alias voting words that are strings" do
-    @votable.respond_to?('1s'.to_sym).should be false
+    end
+
+    it "should add callable functions" do
+      @votable.vote :voter => @voter
+      @votable.likes.size.should == 1
+    end
   end
 
-  it "should add callable functions" do
-    @votable.vote :voter => @voter
-    @votable.likes.should == 1
+  describe "voter models" do
+
+    before(:each) do
+      clean_database
+      @votable = Votable.new(:name => 'a votable')
+      @votable.save
+
+      @voter = Voter.new(:name => 'a voter with aliases')
+      @voter.save
+    end
+
+    it "should alias a bunch of functions" do
+      @voter.respond_to?(:upvotes).should be true
+      @voter.respond_to?(:dislikes).should be true
+    end
+
+    it "should add callable functions" do
+      @voter.likes @votable
+      @votable.likes.size.should == 1
+    end
   end
 
 
+
 end

data/spec/votable_spec.rb

@@ -35,31 +35,41 @@ describe ActsAsVotable::Votable do
 
     it "should have one vote when saved" do
       @votable.vote :voter => @voter, :vote => 'yes'
-      @votable.votes.should == 1
+      @votable.votes.size.should == 1
     end
     
     it "should have one vote when voted on twice by the same person" do
       @votable.vote :voter => @voter, :vote => 'yes'
       @votable.vote :voter => @voter, :vote => 'no'
-      @votable.votes.should == 1
+      @votable.votes.size.should == 1
+    end
+
+    it "should be callable with vote_up" do
+      @votable.vote_up @voter
+      @votable.up_votes.first.voter.should == @voter
+    end
+
+    it "should be callable with vote_down" do
+      @votable.vote_down @voter
+      @votable.down_votes.first.voter.should == @voter
     end
 
     it "should have 2 votes when voted on once by two different people" do
       @votable.vote :voter => @voter
       @votable.vote :voter => @voter2
-      @votable.votes.should == 2
+      @votable.votes.size.should == 2
     end
 
     it "should have one true vote" do
       @votable.vote :voter => @voter
       @votable.vote :voter => @voter2, :vote => 'dislike'
-      @votable.count_votes_true.should == 1
+      @votable.up_votes.size.should == 1
     end
 
     it "should have 2 false votes" do
       @votable.vote :voter => @voter, :vote => 'no'
       @votable.vote :voter => @voter2, :vote => 'dislike'
-      @votable.count_votes_false.should == 2
+      @votable.down_votes.size.should == 2
     end
 
     it "should have been voted on by voter2" do
@@ -102,6 +112,7 @@ describe ActsAsVotable::Votable do
     end
 
 
+
     describe "with cached votes" do
 
       before(:each) do
@@ -142,19 +153,19 @@ describe ActsAsVotable::Votable do
       it "should select from cached total votes if there a total column" do
         @votable_cache.vote :voter => @voter
         @votable_cache.cached_votes_total = 50
-        @votable_cache.votes.should == 50
+        @votable_cache.count_votes_total.should == 50
       end
 
       it "should select from cached up votes if there is an up vote column" do
         @votable_cache.vote :voter => @voter
         @votable_cache.cached_votes_up = 50
-        @votable_cache.count_votes_true.should == 50
+        @votable_cache.count_votes_up.should == 50
       end
 
       it "should select from cached down votes if there is a down vote column" do
         @votable_cache.vote :voter => @voter, :vote => 'false'
         @votable_cache.cached_votes_down = 50
-        @votable_cache.count_votes_false.should == 50
+        @votable_cache.count_votes_down.should == 50
       end
 
     end

data/spec/voter_spec.rb

@@ -55,17 +55,54 @@ describe ActsAsVotable::Voter do
       @voter.voted_as_when_voting_on(@votable).should be nil
     end
 
-    it "should return the total number of votes cast against a given class" do
-      @votable.vote :voter => @voter
-      @votable2.vote :voter => @voter
-      @voter.total_votes_for_class(Votable).should == 2
-    end
-
     it "should provide reserve functionality, voter can vote on votable" do
       @voter.vote :votable => @votable, :vote => 'bad'
       @voter.voted_as_when_voting_on(@votable).should be false
     end
 
+    it "should allow the voter to vote up a model" do
+      @voter.vote_up_for @votable
+      @votable.up_votes.first.voter.should == @voter
+    end
+
+    it "should allow the voter to vote down a model" do
+      @voter.vote_down_for @votable
+      @votable.down_votes.first.voter.should == @voter
+    end
+
+    it "should get all of the voters votes" do
+      @voter.vote_up_for @votable
+      @voter.find_votes.size.should == 1
+    end
+
+    it "should get all of the voters up votes" do
+      @voter.vote_up_for @votable
+      @voter.find_up_votes.size.should == 1
+    end
+
+    it "should get all of the voters down votes" do
+      @voter.vote_down_for @votable
+      @voter.find_down_votes.size.should == 1
+    end
+
+    it "should get all of the votes votes for a class" do
+      @votable.vote :voter => @voter
+      @votable2.vote :voter => @voter, :vote => false
+      @voter.find_votes_for_class(Votable).size.should == 2
+    end
+
+    it "should get all of the voters up votes for a class" do
+      @votable.vote :voter => @voter
+      @votable2.vote :voter => @voter, :vote => false
+      @voter.find_up_votes_for_class(Votable).size.should == 1
+    end
+
+    it "should get all of the voters down votes for a class" do
+      @votable.vote :voter => @voter
+      @votable2.vote :voter => @voter, :vote => false
+      @voter.find_down_votes_for_class(Votable).size.should == 1
+    end
+
     it "should be thread safe" do
       @voter.vote :votable => @votable, :vote => false
       @voter2.vote :votable => @votable

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 5
-  version: 0.0.5
+  version: 0.1.0
 platform: ruby
 authors: 
 - Ryan
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-30 00:00:00 -05:00
+date: 2011-02-09 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -58,6 +58,7 @@ files:
 - .gitignore
 - Gemfile
 - Gemfile.lock
+- README.markdown
 - Rakefile
 - acts_as_votable.gemspec
 - lib/acts_as_votable.rb