vote_fu

Allows an arbitrary number of entites (including Users) to vote on models.

Mixins

This plugin introduces three mixins to your recipe book:

1. acts_as_voteable : Intended for content objects like Posts, Comments, etc.
2. acts_as_voter : Intended for voting entities, like Users.
3. has_karma : Intended for voting entities, or other objects that own the things you're voting on.

Inspiration

This plugin started as an adaptation / update of act_as_voteable. It has grown different from that plugin in several ways:

1. You can specify the model name that initiates votes.
2. You can, with a little tuning, have more than one entity type vote on more than one model type.
3. Adds "acts_as_voter" behavior to the initiator of votes.
4. Introduces some newer Rails features like named_scope and :polymorphic keywords
5. Adds "has_karma" mixin for identifying key content contributors

Install

Run the following command:

./script/plugin install git://github.com/peteonrails/vote_fu.git

Create a new rails migration using the generator:

./script/generate voteable

Usage

Getting Started

Make your ActiveRecord model act as voteable.

class Model < ActiveRecord::Base
  acts_as_voteable
end

Make your ActiveRecord model(s) that vote act as voter.

class User < ActiveRecord::Base
  acts_as_voter
end

class Robot < ActiveRecord::Base
  acts_as_voter
end

To cast a vote for a Model you can do the following:

Shorthand syntax

voter.vote_for(voteable)     # Adds a +1 vote
voter.vote_against(voteable) # Adds a -1 vote
voter.vote(voteable, t_or_f) # Adds either +1 or -1 vote true => +1, false => -1

ActsAsVoteable syntax

The old acts_as_voteable syntax is still supported:

vote = Vote.new(:vote => true)
m    = Model.find(params[:id])
m.votes    << vote
user.votes << vote

Querying votes

Tallying Votes

You can easily retrieve voteable object collections based on the properties of their votes:

@items = Item.tally(
  {  :at_least => 1, 
      :at_most => 10000,  
      :start_at => 2.weeks.ago,
      :end_at => 1.day.ago,
      :limit => 10,
      :order => "items.name desc"
  })

This will select the Items with between 1 and 10,000 votes, the votes having been cast within the last two weeks (not including today), then display the 10 last items in an alphabetical list.

Tally Options:

:start_at    - Restrict the votes to those created after a certain time
:end_at      - Restrict the votes to those created before a certain time
:conditions  - A piece of SQL conditions to add to the query
:limit       - The maximum number of voteables to return
:order       - A piece of SQL to order by. Eg 'votes.count desc' or 'voteable.created_at desc'
:at_least    - Item must have at least X votes
:at_most     - Item may not have more than X votes

Lower level queries

ActiveRecord models that act as voteable can be queried for the positive votes, negative votes, and a total vote count by using the votes_for, votes_against, and votes_count methods respectively. Here is an example:

positiveVoteCount = m.votes_for
negativeVoteCount = m.votes_against
totalVoteCount    = m.votes_count

And because the Vote Fu plugin will add the has_many votes relationship to your model you can always get all the votes by using the votes property:

allVotes = m.votes

The mixin also provides these methods:

voter.voted_for?(voteable)  # True if the voter voted for this object. 
voter.vote_count([true|false|"all"]) # returns the count of +1, -1, or all votes 

voteable.voted_by?(voter) # True if the voter voted for this object. 
@voters = voteable.voters_who_voted

Named Scopes

The Vote model has several named scopes you can use to find vote details:

@pete_votes = Vote.for_voter(pete)
@post_votes = Vote.for_voteable(post)
@recent_votes = Vote.recent(1.day.ago)
@descending_votes = Vote.descending

You can chain these together to make interesting queries:

# Show all of Pete's recent votes for a certain Post, in descending order (newest first)
@pete_recent_votes_on_post = Vote.for_voter(pete).for_voteable(post).recent(7.days.ago).descending

Experimental: Voteable Object Owner Karma

I have just introduced the "has_karma" mixin to this package. It aims to assign a karma score to the owners of voteable objects. This is designed to allow you to see which users are submitting the most highly voted content. Currently, karma is only "positive". That is, +1 votes add to karma, but -1 votes do not detract from it.

class User 
  has_many :posts
  has_karma :posts
end

class Post
  acts_as_voteable
end

# in your view, you can then do this: 
Karma: <%= @user.karma %>

This feature is in alpha, but useful enough that I'm releasing it.

Credits

Juixe - The original ActsAsVoteable plugin inspired this code.

Xelipe - This plugin is heavily influenced by Acts As Commentable.

More

Documentation from the original acts_as_voteable plugin