Ajaxful Rating

Provides a simple way to add rating functionality to your application.

Repository

Find it at github.com/edgarjs/ajaxful-rating

Instructions

Install

To install the plugin: script/plugin install git://github.com/edgarjs/ajaxful-rating.git

Generate

script/generate 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 necesary images, styles, etc.

Example:

I suppose you have generated already an authenticated model.

script/generate authenticated user sessions

script/generate ajaxful_rating user

So this call will create a Rate model and will link it to your User model.

Prepare

• :stars Max number of stars that can be submitted.
• :allow_update Set to true if you want users to be able to update their votes.
• :cache_column Name of the column for storing the cached rating average.

  class Article < ActiveRecord::Base
    ajaxful_rateable :stars => 10
  end
  

Then you need to add a call ajaxful_rater in the user model. This includes a simple line so you can add it by your own as well (has_many :rates).

  class User < ActiveRecord::Base
    ajaxful_rater
  end
  

Finally, as a mere recomendation to make it even easier, modify your routes to map a rate action:

map.resources :articles, :member => {:rate => :post}

Use it

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).

  # show.html.erb
  <%= ratings_for @article %>

  # To display static stars:
  <%= ratings_for @article, :static %>
  

Or you can specify a custom user instance by passing it as parameter.

  <%= ratings_for @article, @user %>
  

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, :remote_options => {: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 the javascripts.

    # within the head tags of your layout...
    <%= javascript_include_tag :defaults %>
    <%= ajaxful_rating_style %>
  

When a user submits a rating it will call the action in your controller, for example (if you added the rate route):

  def rate
    @article = Article.find(params[:id])
    @article.rate(params[:stars], current_user)
    id = "ajaxful-rating-article-#{@article.id}" 
    render :update do |page|
      page.replace_html id, ratings_for(@article, :static)
      page.insert_html :bottom, id, "Thanks for rating!" 
      page.visual_effect :highlight, id
    end
  end
  

There are some more options for this helper, please see the rdoc for details.

Cache

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
    end

    def self.down
      remove_column :articles, :rating_average
    end
  end
  

If you want to customise 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
  

About backwards compatibility

Version 2.0 of the plugin works only from Rails 2.2 and on. It uses the module I18n which is new in rails 2.2. Please note that you can use it in past versions as long as you customise the source code.

I decided to jump directly to version 2.0 because there are many important changes. You can always checkout the version 1.0 from the repository though.

Feedback

I’ll really appreciate your feedback, please contact me at edgar.js[at]gmail.com

Credits

The helper’s style is from komodomedia with author’s permission.

License

This code is released under Creative Commons Attribution-Share Alike 3.0 license.