Provides a simple way to add rating functionality to your application. This fork uses jQuery instead of prototype and uses unobtrusive javascript. This fork only supports Rails 3.
Forked from (rails 2.x version) http://github.com/kamui/ajaxful_rating_jquery
The original repository, which uses Prototype, is located at http://github.com/edgarjs/ajaxful-rating
To install the plugin run the next command:
rails plugin install git://github.com/mrbrdo/ajaxful_rating_jquery.git
rails g ajaxful_rating UserModelName
The generator takes one argument: UserModelName, which is the name of your current
user model. This is necessary to link both the rate and user models.
Also this generator copies the necessary images, styles, etc.
Example:
I suppose you have generated already an authenticated model…
rails g authenticated user sessions rails g ajaxful_rating user
So this call will create a Rate model and will link it to your User model.
To let a model be rateable just add ajaxful_rateable. You can pass a hash of options to
customize this call:
:starsMax number of stars that can be submitted.:allow_updateSet to true if you want users to be able to update their votes.:cache_columnName of the column for storing the cached rating average.:dimensionsArray of dimensions. Allows to rate the model on various specs,
like for example: a car could be rated for its speed, beauty or price.
class Car < ActiveRecord::Base ajaxful_rateable :stars => 10, :dimensions => [:speed, :beauty, :price] end
Then you need to add a call ajaxful_rater in the user model to make your User model able to rate objects.
class User < ActiveRecord::Base ajaxful_rater end
Finally, as a mere recommendation to make it even easier, modify your routes to
map a rate action:
resources :cars do post :rate, :on => :member end
To add the star links you need to call the helper method ratings_for.
It tries to call current_user method as the rater instance. You can pass :static
as the second param to display only the static stars (not clickables).
And also you can pass the dimension you want to show the ratings for.
#show.html.erb <%= ratings_for @article %> #To display static stars: <%= ratings_for @article, :static %> #To display the ratings for a dimension: <%= ratings_for @article, :dimension => :speed %>
Or you can specify a custom user instance by passing it as parameter.
<%= ratings_for @article, @user %>
By default ratings_for will display the average user rating. If you would like it to
display the rating for the current_user, then set the :show_user_rating parameter to true.
For example:
# To display the rating for the current user (current_user): <%= ratings_for @article, :show_user_rating => true %> # To change the size of the stars you can also specify an optional :size value. If none is set it uses the large size, otherwise you can specify medium or small: <%= ratings_for @article, :size => "medium" %> # To display the rating for the user specified by @user: <%= ratings_for @article, @user, :show_user_rating => true %>
There’s a condition here, if you didn’t add the route rate to your resource
(as shown above) or you named it different, you’ll need to pass the url to the
correct action in your controller:
<%= ratings_for @article, :url => your_rate_path(@article) %>
To display the stars properly you need to add a call in the head of your layout, which will generate the
required CSS style for the list. Also don’t forget to include jQ—uery.
It’s also important to note that this call MUST be within your head tags in your layout, as for now it seems to doesn’t work with the content_for tag.
#within the head tags of your layout... <%= javascript_include_tag "http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js" %> <%= ajaxful_rating_style %> <%= ajaxful_rating_script %>
When a user submits a rating it will call the action in your controller, for
example (if you added the rate route):
def rate
@car = Car.find(params[:id])
@car.rate(params[:stars], current_user, params[:dimension])
average = @car.rate_average(true, params[:dimension])
width = (average / @car.class.max_stars.to_f) * 100
render :json => {:id => @car.wrapper_dom_id(params), :average => average, :width => width}
end
There are some more options for this helper, please see the rdoc for details.
From now on you can pass an optional parameter to the rates method for your rateable object to retrieve the
corresponding rates for the dimension you want.
For example, you defined these dimensions:
class Car < ActiveRecord::Base ajaxful_rateable :dimensions => [:speed, :beauty, :price] end
And hence you can call car.rates(:price) for the price rates or car.rates(:speed) for the speed ratings and so on.
If you use the plugin inside a namespace you’ll need to specify the rating url which should points to
a controller inside a namespace. Your files should be like these:
routes.rb:
map.namespace :admin do |admin|
admin.resources :articles, :member => {:rate => :post}
end
views/admin/articles/show.html.erb
<%= ratings_for @article, :url => rate_admin_article_path(@article) %>
To cache the model’s rating average add a column named rating_average to your model table:
class AddRatingAverageToArticles < ActiveRecord::Migration
def self.up
add_column :articles, :rating_average, :decimal, :default => 0, :precision => 6, :scale => 2
end
def self.down
remove_column :articles, :rating_average
end
end
If you want to customize the name of the cache column just pass it in the options hash:
class Article < ActiveRecord::Base ajaxful_rateable :cache_column => :my_cached_rating end
To use caching with dimensions, make sure you have a cache column defined for each dimension you want cached.
So if you want to cache the spelling dimension, you’ll need to have a column called rating_average_spelling on the articles table.
If you use a custom cache column name, follow the pattern cache_column_name_dimension_name to add cache columns for dimensions.
If you find bugs please open a ticket at http://github.com/kamui/ajaxful_rating_jquery/issues
I’ll really appreciate your feedback, please contact me at kamuigt[at]gmail[dot]com
The original developer of ajaxify_rating, Edgar J. Suarez
The helper’s style is from komodomedia with author’s permission.
If you need the psd files of the stars you can grab them here
Thanks to bborn for the dimensions base implementation.
This code is released under Creative Commons Attribution-Share Alike 3.0 license.
