Stars¶ ↑

Stars is a Rails engine plugin that provides simple rating logic for your Rails apps with high customizability.

By default Stars provide a simple rating widget with 5 “stars” (duh). Think of the rating system on YouTube. Logged in users can click on the widget to submit their own rating (works through AJAX).

NOTE: Although this is good enough for my own use it’s not yet a finished “product” (as the incomplete status of this doc probably shows). Please check the TODO list below to see if any of the missing items are things you need before using this plugin.

Requirements¶ ↑

So far it’s only been tested on Rails 2.3.X, but it would probably work just as fine on 2.2.x
An user model (class name can be specified through configuration), and logged in user accessible through a controller method (e.g. current_user)
Resourceful routes

Features¶ ↑

Built-in controller logic (via Rails engines), no need for generators
Built-in rating model (can be used to rate any other ActiveRecord model through polymorphic associations)
Helper methods to generate rating “widgets” in your views
Reflection method for ActiveRecord models: is_rateable as a pretty alternative to include Stars::Rateable
Shorthand method for routes: ratings as a pretty alternative to resource :ratings, :only => :create
Generators for migrations and assets (JS, CSS and images)
HTML5-based event handling, allowing for JavaScript framework independence (by default only a Prototype-based handler is provided, but porting to jQuery, mootools or other similar frameworks shouldn’t be too hard)
Pretty configuration through an initializer

Installing¶ ↑

To install as a plugin simply run:

script/plugin install git://github.com/pilaf/stars.git

(Remember to restart your local server afterward)

NOTE: Installing the plugin will automatically generate asset files (JS, CSS and images) under their respective directories in public and an initializer file under config/initializers. These files will be removed for you if you choose to uninstall the plugin using script/plugin remove stars.

Usage¶ ↑

Setup of Models and Routes¶ ↑

After installing you’ll need to generate the ratings migration and run it:

script/generate ratings_migration
rake db:migrate

To make a model/resource rateable add the following line to your model class:

class Article < ActiveRecord::Base
  is_rateable
end

You’ll also need to add a rating_average column to the model’s table. Fortunately there’s a generator to do that for you:

script/generate add_rating_average_migration article
rake db:migrate

And then the corresponding resource in your config/routes.rb file:

map.resources :articles do |article|
  article.ratings 
end

Views¶ ↑

To use in your views make sure to include the plugin’s JavaScript and CSS files in your views:

<%= stars_rating_stylesheets %>
<%= stars_rating_javascripts %>

If you’re planning to use both in the head tag you can also use the shorthand version:

<%= stars_rating_assets %>

Though I recommend including the JavaScript at the bottom of your body tag.

To insert a rating widget use the rating_for helper, passing it the model instance to be rated:

<%= rating_for @article %>

Configuration¶ ↑

To configure edit your config/initializers/stars_rating.rb.

Internals (How Things Work)¶ ↑

TODOs¶ ↑

Add tests
Add rake tasks to recalculate all averages
Add I18n support
Distribute as gem
Test on multiple browsers

Known issues¶ ↑

Because of the way the JavaScript event handler works, all elements in the nested chain from the rating widget to the top of the document must have the “hasLayout” property for IE6 and IE7, or otherwise the Prototype function Element.cumulativeOffset calculates a wrong offset and all hell breaks loose. Check www.satzansatz.de/cssd/onhavinglayout.html for a list of ways in which you can achieve hasLayout in IE6 and IE7.

pilaf / stars