-
Notifications
You must be signed in to change notification settings - Fork 19
/
README
147 lines (98 loc) · 4.77 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
= acts_as_rated
The ultimate rating system for ActiveRecord models. Highly flexible and configurable, while easy to use with the defaults. Supports 3 different ways to manage the statistics, and creates all the needed associations for easy access to everything.
Comes complete with the needed migrations code to make it easy to add to any project.
<em>NOTE:</em> It uses some advanced SQL constructs that might not be supported by all servers. It was tested on Postgres only. If you have patches/fixes for other databases, please send them and I will add them to the plugin. <em>UPDATE:</em> Thanks to work done by Tiago Serafim it now passes all but one tests on MySQL. And this test fails due to strangeness in the avg() function in MySQL, according to Tiago.
== Features
* Rate any model
* Optionally add fields to the rated objects to optimize speed
* Optionally add an external rating statistics table with a record for each rated model
* Can work with the added fields, external table or just using direct SQL count/avg calls
* Use any model as the rater (defaults to User)
* Limit the range of the ratings
* Average, total and number of ratings
* Find objects by ratings or rating ranges
* Find objects by rater
* Check if an object is rated by a specific rater. (Added by Tiago Serafim, thanks!)
* Extensively tested
== Basic Details
Install
* script/plugin install svn://rubyforge.org/var/svn/acts-as-rated/trunk/acts_as_rated
* gem install - <b>coming soon</b>
Rubyforge project
* http://rubyforge.org/projects/acts-as-rated
RDocs
* http://acts-as-rated.rubyforge.org
Subversion
* svn://rubyforge.org/var/svn/acts-as-rated
Agile Web Development directory
* http://www.agilewebdevelopment.com/plugins/acts_as_rated
My blog with some comments about the plugin
* http://devblog.famundo.com
Work done as part of Famundo development
* http://www.famundo.com
Contact me at
== Changes
* V3 - Added improved find_by_rating as proposed by Ian McIntosh
* V2 - Passing MySQL tests, check if rated by a specific rater as proposed by Tiago Serafim
== TODO
* Test with more databases
* Test with other versions of Rails (tested against 1.2.1)
* Add view helpers for easy display and entering of the ratings
== Example of usage:
=== Simple rating system
Look at the file <tt>test/rating_test.rb</tt> for many usage examples covering all variations of the plugin.
class Book < ActiveRecord::Base
acts_as_rated
end
bill = User.find_by_name 'bill'
jill = User.find_by_name 'jill'
catch22 = Book.find_by_title 'Catch 22'
hobbit = Book.find_by_title 'Hobbit'
catch22.rate 5, bill
hobbit.rate 3, bill
catch22.rate 1, jill
hobbit.rate 5, jill
hobbit.rating_average # => 4
hobbit.rated_total # => 8
hobbit.rated_count # => 2
hobbit.unrate bill
hobbit.rating_average # => 5
hobbit.rated_total # => 5
hobbit.rated_count # => 1
bks = Book.find_by_rating 5 # => [hobbit]
bks = Book.find_by_rating 1..5 # => [catch22, hobbit]
usr = Book.find_rated_by jill # => [catch22, hobbit]
=== Migration
The file <tt>test/fixtures/migrations/001_add_rating_tables.rb</tt> shows examples of all types of migration options.
See also the detailed documentation for the <tt>acts_as_rated</tt> method on how to declare it, and the rest of the documentation for how to generate the migration columns/files and how to use it.
class AddRatingTables < ActiveRecord::Migration
def self.up
ActiveRecord::Base.create_ratings_table
# Movies table has the columns for the ratings added while it's created
create_table(:movies) do |t|
t.column :title, :text
Movie.generate_ratings_columns t
end
# Cars table has the columns for the ratings added, but after the fact, using ALTER TABLE calls.
# Usually used if the model already exist and we want to add the ratings after the fact
create_table(:cars) do |t|
t.column :title, :text
end
Car.add_ratings_columns
end
def self.down
# Remove the columns we added
Car.remove_ratings_columns
drop_table :movies rescue nil
drop_table :cars rescue nil
ActiveRecord::Base.drop_ratings_table
end
end
== Testing the plugin
The plugin comes with a full set of tests, both for migrations and for the code itself. The framework was taken from the acts_as_versioned plugin, allowing it to run stand-alone in the test directory.
run the tests:
rake test
In order for testing to work, you need to create a database (default name is acts_as_rated_plugin_test) and edit test/database.yml to make sure the login and password are correct. You can also change there the name of the database.
Testing defaults to postgresql, to change it set the environment variable DB to the driver you want to use:
env DB='mysql' rake test