4
Allows an arbitrary number of entites (including Users) to vote on models.
7
This plugin introduces three mixins to your recipe book:
9
1. **acts\_as\_voteable** : Intended for content objects like Posts, Comments, etc.
10
2. **acts\_as\_voter** : Intended for voting entities, like Users.
11
3. **has\_karma** : Intended for voting entities, or other objects that own the things you're voting on.
15
This plugin started as an adaptation / update of act\_as\_voteable. It has grown different from that plugin in several ways:
17
1. You can specify the model name that initiates votes.
18
2. You can, with a little tuning, have more than one entity type vote on more than one model type.
19
3. Adds "acts\_as\_voter" behavior to the initiator of votes.
20
4. Introduces some newer Rails features like named\_scope and :polymorphic keywords
21
5. Adds "has\_karma" mixin for identifying key content contributors
25
Use either the plugin or the gem installation method depending on your preference. If you're not sure, the plugin method is simpler. Whichever you choose, create the migration afterward and run it to create the required model.
28
./script/plugin install git://github.com/peteonrails/vote_fu.git
31
Add the following to your application's environment.rb:
32
config.gem "peteonrails-vote_fu", :lib => 'vote_fu', :source => 'http://gems.github.com'
37
### Create vote_fu migration
38
Create a new rails migration using your new vote_fu generator (Note: "VoteableModel" is the name of the model on which you would like votes to be cast, e.g. Comment):
39
./script/generate vote_fu VoteableModel
49
### Make your ActiveRecord model act as voteable.
52
class Model < ActiveRecord::Base
57
### Make your ActiveRecord model(s) that vote act as voter.
59
class User < ActiveRecord::Base
63
class Robot < ActiveRecord::Base
67
### To cast a vote for a Model you can do the following:
70
voter.vote_for(voteable) # Adds a +1 vote
71
voter.vote_against(voteable) # Adds a -1 vote
72
voter.vote(voteable, t_or_f) # Adds either +1 or -1 vote true => +1, false => -1
74
#### ActsAsVoteable syntax
75
The old acts\_as\_voteable syntax is still supported:
77
vote = Vote.new(:vote => true)
78
m = Model.find(params[:id])
86
You can easily retrieve voteable object collections based on the properties of their votes:
91
:start_at => 2.weeks.ago,
94
:order => "items.name desc"
97
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.
100
:start_at - Restrict the votes to those created after a certain time
101
:end_at - Restrict the votes to those created before a certain time
102
:conditions - A piece of SQL conditions to add to the query
103
:limit - The maximum number of voteables to return
104
:order - A piece of SQL to order by. Eg 'votes.count desc' or 'voteable.created_at desc'
105
:at_least - Item must have at least X votes
106
:at_most - Item may not have more than X votes
108
#### Lower level queries
109
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:
111
positiveVoteCount = m.votes_for
112
negativeVoteCount = m.votes_against
113
totalVoteCount = m.votes_count
115
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:
119
The mixin also provides these methods:
121
voter.voted_for?(voteable) # True if the voter voted for this object.
122
voter.vote_count([true|false|"all"]) # returns the count of +1, -1, or all votes
124
voteable.voted_by?(voter) # True if the voter voted for this object.
125
@voters = voteable.voters_who_voted
130
The Vote model has several named scopes you can use to find vote details:
132
@pete_votes = Vote.for_voter(pete)
133
@post_votes = Vote.for_voteable(post)
134
@recent_votes = Vote.recent(1.day.ago)
135
@descending_votes = Vote.descending
137
You can chain these together to make interesting queries:
139
# Show all of Pete's recent votes for a certain Post, in descending order (newest first)
140
@pete_recent_votes_on_post = Vote.for_voter(pete).for_voteable(post).recent(7.days.ago).descending
142
### Experimental: Voteable Object Owner Karma
143
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.
154
# in your view, you can then do this:
155
Karma: <%= @user.karma %>
157
This feature is in alpha, but useful enough that I'm releasing it.
159
### One vote per user!
160
If you want to limit your users to a single vote on each item, take a look in lib/vote.rb.
162
# Uncomment this to limit users to a single vote on each item.
163
# validates_uniqueness_of :voteable_id, :scope => [:voteable_type, :voter_type, :voter_id]
165
And if you want that enforced at the database level, look in the generated migration for your voteable:
167
# If you want to enfore "One Person, One Vote" rules in the database, uncomment the index below
168
# add_index :votes, ["voter_id", "voter_type", "voteable_id", "voteable_type"], :unique => true, :name => "uniq_one_vote_only"
170
### Example Application
172
There is now a reference application available. Due to overwhelming demand for example
173
code and kickstart guides, I have open-sourced MyQuotable.com in order to provide an
174
easy-to-follow example of how to use VoteFu with RESTful Authentication, JRails, and
175
other popular plugins. To get the example code:
177
git clone git://github.com/peteonrails/myquotable.git
179
There will be a screencast coming soon too. Contact me if you want to help.
183
If you like this software and use it, please consider recommending me on Working With Rails.
185
I don't want donations: a simple up-vote would make my day. My profile is: [http://www.workingwithrails.com/person/12521-peter-jackson][4]
187
To go directly to the "Recommend Me" screen: [http://www.workingwithrails.com/recommendation/new/person/12521-peter-jackson][5]
195
* Bence Nagy, Budapest, Hungary
196
* Jon Maddox, Richmond, Virginia, USA
200
[Juixe - The original ActsAsVoteable plugin inspired this code.][1]
202
[Xelipe - This plugin is heavily influenced by Acts As Commentable.][2]
204
[1]: http://www.juixe.com/techknow/index.php/2006/06/24/acts-as-voteable-rails-plugin/
205
[2]: http://github.com/jackdempsey/acts_as_commentable/tree/master
210
Support: [Use my blog for support.][6]
213
[Documentation from the original acts\_as\_voteable plugin][3]
215
[3]: http://www.juixe.com/techknow/index.php/2006/06/24/acts-as-voteable-rails-plugin/
216
[4]: http://www.workingwithrails.com/person/12521-peter-jackson
217
[5]: http://www.workingwithrails.com/recommendation/new/person/12521-peter-jackson
218
[6]: http://blog.peteonrails.com
220
Copyright (c) 2008 Peter Jackson, released under the MIT license