IS_REVIEWABLE ~ concept version ~

Rails: Make an ActiveRecord resource ratable/reviewable (rating + comment), without the usual extra code-smell.

Why another rating-plugin?

Many reasons; I felt the existing plugins all suck in one way or another (sorry, no hating). This is why IsReviweable is better if you ask me:

Don’t do assumptions that your rater/reviewer model is User. Relying on polymorphic assocation completely, so your reviewer can be…DonaldDuck.
…and optionally even accepts an IP as rater/reviewer. Disabled by default though.
Don’t make assumptions about your Review model – you can extend it without meta-programming, good ’ol subclassing folks.
Don’t make assumptions about what rating scale you wanna have, how the rating scale should be divided, or average rating rounding precision. The 1-5 scale is 80% of the cases, but there’s no real reason or overhead to support any scale. To sum it up: Scale can consist negative and/or positive range or explicit integer/float values…and you won’t even notice the difference on the outside. See the examples! =)
Possible to submit additional custom attributes while rating, such as title and body to make up a “review” instead of just a “rating”. Feel free.
Very sassy finders implemented using named scopes, i.e. less code smell.
No lame out-of-the-box views/javascripts/images that you probably won’t use in the final product anyway. That should be an extension to the plugin.
Transparently supports column-caching expensive calculations for the reviewable model. Will simply be turned on if these fields exists – otherwise fallback with an optimized DB hit instead.
If I can say it myself…this code should be very solid, optimized, and DRY. Shoot the messenger! o<;)

If you got suggestions how it could be even better, just hit me up. I appreciate critics for the cause of a rock solid plugin for rating/reviewing. Such a common “problem” as rating/reviewing should have had a great solution by now!

Installation

Gem:

sudo gem install is_reviewable

and in config/environment.rb:

config.gem 'is_reviewable'

Plugin:

./script/plugin install git://github.com/grimen/is_reviewable.git

Usage

1. Generate migration:

$ ./script/generate is_reviewable_migration

Generates db/migrations/{timestamp}_is_reviewable_migration with:

class IsReviewableMigration < ActiveRecord::Migration
  def self.up
    create_table :reviews do |t|
      t.references  :reviewable,    :polymorphic => true
      
      t.references  :reviewer,      :polymorphic => true
      t.string      :ip,            :limit => 24
      
      t.float       :rating
      t.text        :body
      
      #
      # Custom fields goes here...
      # 
      # t.string      :title
      # t.string      :mood
      # ...
      #
      
      t.timestamps
    end
    
    add_index :reviews, :reviewer_id
    add_index :reviews, :reviewer_type
    add_index :reviews, [:reviewer_id, :reviewer_type]
    add_index :reviews, [:reviewable_id, :reviewable_type]
  end
  
  def self.down
    drop_table :reviews
  end
end

2. Make your model reviewable:

class Post < ActiveRecord::Base
  is_reviewable :scale => 0..5
end

or, with explicit reviewer (or reviewers):

class Book < ActiveRecord::Base
  # Setup associations for the reviewer class(es) automatically, and specify an explicit scale instead.
  is_reviewable :by => [:users, :ducks], :scale => 0..5
end

3. …and here we go:

Examples:

Review.destroy_all # just in case...
@post = Post.first
@user = User.first

@post.review!(:by => @user, :rating => 2)  # new reviewer (type: object) => create
@post.review!(:by => @user, :rating => 5)  # same reviewer (type: object) => update

@post.total_reviews   # => 1
@post.average_rating  # => 5.0

@post.review!(:by => '128.0.0.0', :rating => 4)  # new reviewer (type: IP) => create
@post.review!(:by => '128.0.0.0', :rating => 2)  # same reviewer (type: IP) => update

@post.total_reviews   # => 2
@post.average_rating  # => 3.5

@post.review!(:by => @user, :rating => nil, :body => "Lorem ipsum...")  # same reviewer (type: IP) => update

@post.total_reviews   # => 2
@post.average_rating  # => 2.0, i.e. don't count nil (a.k.a. "no opinion")

@post.unreview!(:by => '128.0.0.0')  # delete existing review (type: IP) => destroy

@post.total_reviews   # => 1
@post.average_rating  # => 2.0

@post.reviews       # => reviews on @post
@post.reviewers     # => reviewers that reviewed @post
@user.reviews       # => reviews by @user
@user.reviewables   # => reviewable objects that got reviewed by @user

# TODO: A few more samples...

# etc...

Mixin Arguments

The is_reviewable mixin takes some hash arguments for customization:

Basic

:by – the reviewer model(s), e.g. User, Account, etc. (accepts either symbol or class, i.e. User <=> :user <=> :users, or an array of such if there are more than one reviewer model). The reviewer model will be setup for you. Note: Polymorhic, so it accepts any model. Default: nil.
:scale/:range/:values – range, or array, of valid rating values. Default: 1..5. Note: Negative values are allowed too, and a range of values are not required, i.e. [-1, 1] is valid as well as [1,3,5]. =)
:accept_ip – accept anonymous users uniquely identified by IP (well…you handle the bots =D). See examples below how to use this as your visitor object. Default: false.

Advanced

:total_precision – maximum number of digits for the average rating value. Default: 1.
:step – useful if you want to specify a custom step for each scale value within a range of values. Default: 1 for range of fixnum, auto-detected based on first value in range of float.
:steps – similar to :step (they relate to each other), but instead of specifying a step you can specify how many steps you want. Default: auto-detected based on custom or default value :step.

Aliases

To make the usage of IsReviewable a bit more generic (similar to other plugins you may use), there are two useful aliases for this purpose:

Review#owner <=> Review#reviewer
Review#object <=> Review#reviewable

Example:

@post.reviews.first.owner == post.reviews.first.reviewer      # => true
@post.reviews.first.object == post.reviews.first.reviewable   # => true

Finders (Named Scopes)

IsReviewable has plenty of useful finders implemented using named scopes. Here they are:

`Review`

Order:

in_order – most recent reviews last (order by creation date).
most_recent – most recent reviews first (opposite of in_order above).
lowest_rating – reviews with lowest ratings first.
highest_rating – reviews with highest ratings first.

Filter:

limit(<number_of_items>) – maximum <number_of_items> reviews.
since(<created_at_datetime>) – reviews created since <created_at_datetime>.
recent(<datetime_or_size>) – if DateTime: reviews created since <datetime_or_size>, else if Fixnum: pick last <datetime_or_size> number of reviews.
between_dates(<from_date>, to_date) – reviews created between two datetimes.
with_rating(<rating_value_or_range>) – reviews with(in) rating value (or range) <rating_value_or_range>.
with_a_rating – reviews with a rating value, i.e. not nil.
without_a_rating – opposite of with_a_rating (above).
with_a_body – reviews with a body/comment, i.e. not nil/blank.
without_a_body – opposite of with_a_body (above).
complete – reviews with both rating and comments, i.e. “full reviews” where.
of_reviewable_type(<reviewable_type>) – reviews of <reviewable_type> type of reviewable models.
by_reviewer_type(<reviewer_type>) – reviews of <reviewer_type> type of reviewer models.
on(<reviewable_object>) – reviews on the reviewable object <reviewable_object> .
by(<reviewer_object>) – reviews by the <reviewer_object> type of reviewer models.

`Reviewable`

TODO: Documentation on named scopes for Reviewable.

`Reviewer`

TODO: Documentation on named scopes for Reviewer.

Examples using finders:

@user = User.first
@post = Post.first

@post.reviews.recent(10)          # => [10 most recent reviews]
@post.reviews.recent(1.week.ago)  # => [reviews created since 1 week ago]

@post.reviews.with_rating(3.5..4.0)     # => [all reviews on @post with rating between 3.5 and 4.0]

@post.reviews.by_reviewer_type(:user)   # => [all reviews on @post by User-objects]
# ...or:
@post.reviews.by_reviewer_type(:users)  # => [all reviews on @post by User-objects]
# ...or:
@post.reviews.by_reviewer_type(User)    # => [all reviews on @post by User-objects]

@user.reviews.on(@post)  # => [all reviews by @user on @post]
@post.reviews.by(@user)  # => [all reviews by @user on @post] (equivalent with above)

Review.on(@post)  # => [all reviews on @user] <=> @post.reviews
Review.by(@user)  # => [all reviews by @user] <=> @user.reviews

# etc, etc. It's all named scopes, so it's really no new hokus-pokus you have to learn.

Additional Methods

Note: See documentation (RDoc).

Extend the Review model

This is optional, but if you wanna be in control of your models (in this case Review) you can take control like this:

class Review < IsReviewable::Review
  
  # Do what you do best here... (stating the obvious: core IsReviewable associations, named scopes, etc. will be inherited)
  
end

Caching

If the visitable class table – in the sample above Post – contains a columns cached_total_reviews and cached_average_rating, then a cached value will be maintained within it for the number of reviews and the average rating the object have got.

Additional caching fields (to a reviewable model table):

class AddIsReviewableToPostsMigration < ActiveRecord::Migration
  def self.up
    # Enable is_reviewable-caching.
    add_column :posts, :cached_total_reviews, :integer
    add_column :posts, :cached_average_rating, :integer
  end
  
  def self.down
    remove_column :posts, :cached_total_reviews
    remove_column :posts, :cached_average_rating
  end
end

Example

Controller

Depending on your implementation: You might – or might not – need a Controller, but for most cases where you only want to allow rating of something, a controller most probably is overkill. In the case of a review, this is how one cold look like (in this example, I’m using the excellent the InheritedResources):

Example: app/controllers/reviews_controller.rb:

class ReviewsController < InheritedResources::Base
  
  actions :create, :update, :destroy
  respond_to :js
  layout false
  
end

..or in the more basic rating case – app/controllers/posts_controller.rb:

class PostsController < InheritedResources::Base
  
  actions :all
  respond_to :html, :js
  layout false if request.format == :js
  
  def rate
    begin
      @post.review! :by => current_user, params.slice(:rating, :body)
    rescue
      flash[:error] = 'Sad panda...could not rate for some reason. O_o'
    end
    respond_to do |format|
      format.html { redirect_to @post }
      format.js   # app/views/posts/rate.js.rjs
    end
  end
  
end

Routes

config/routes.rb

map.resources :posts, :member => {:rate => :put}

Views

IsReviewable comes with no view templates (etc.) because of already stated reasons, but basic rating mechanism is trivial to implement (in this example, I’m using HAML because I despise ERB):

Example: app/views/posts/show.html.haml

%h1
  = @post.title
%p
  = @post.body
%p
  = "Your rating:"
  #rating_wrapper= render '/reviews/rating', :resource => @post

Example: app/views/reviews/_rating.html.haml

.rating
  - if resource.present? && resource.reviewable?
    - if reviewer.present?
      - current_rating = resource.review_by(reviewer).try(:rating)
      - resource.reviewable_scale.each do |rating|
        = link_to_remote "#{rating.to_i}", :url => rate_post_path(resource, :rating => rating.to_i), :method => :put, :html => {:class => "rate rated_#{rating.to_i}#{' current' if current_rating == rating}"}
      = link_to_remote "no opinion", :url => rate_post_path(resource, :rating => nil), :method => :put, :html => {:class => "rate rated_none#{' current' unless current_rating}"}
    - else # static rating
      - current_rating = resource.average_rating.round
      - resource.reviewable_scale.each do |rating|
        {:class => "rate rated_#{rating}#{' current' if current_rating == rating}"}

Note: Skipping review-body (etc.) in this view sample, but that is straightforward to implement anyways.

JavaScript/AJAX

…and finally – as we in this example using AJAX – the javascript response (in this example, I’m using RJS + jQuery – don’t get me started on why I don’t use Prototype for UI…).

Example: app/views/reviews/rate.js.rjs

page.replace_html '#rating_wrapper', render('/reviews/rating', :reviewable => @post, :reviewer => current_user)
page.visual_effect :highlight, '.rating .current'

Done! =)

Design Implications: Additional Use Cases

Like/Dislike

IsReviewable is designed in such way that you as a developer are not locked to how traditional rating works. As an example, this is how you could implement like/dislike (like VoteFu) pattern using IsReviewable: