is_reviewable 0.1.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Jonas Grimfelt
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,421 @@
+h1. IS_REVIEWABLE ~ concept version ~
+
+_Rails: Make an ActiveRecord resource ratable/reviewable (rating + comment), without the usual extra code-smell._
+
+h2. 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!
+
+h2. Installation
+
+*Gem:*
+
+<pre>sudo gem install grimen-is_reviewable</pre>
+
+and in @config/environment.rb@:
+
+<pre>config.gem 'grimen-is_reviewable', :lib => 'is_reviewable'</pre>
+
+*Plugin:*
+
+<pre>./script/plugin install git://github.com/grimen/is_reviewable.git</pre>
+
+h2. Usage
+
+h3. 1. Generate migration:
+
+<pre>$ ./script/generate is_reviewable_migration</pre>
+
+Generates @db/migrations/{timestamp}_is_reviewable_migration@ with:
+
+<pre>
+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
+</pre>
+
+h3. 2. Make your model reviewable:
+
+<pre>
+class Post < ActiveRecord::Base
+  is_reviewable :scale => 0..5
+end
+</pre>
+
+or, with explicit reviewer (or reviewers):
+
+<pre>
+class Book < ActiveRecord::Base
+  # Setup associations for the reviewer class(es) automatically, and specify an explicit scale instead.
+  is_reviewable :by => [:users, :journalists], :scale => 0..5
+end
+</pre>
+
+*Note:* @:by@ is optional if you choose any of @User@ or @Account@ as reviewer classes.
+
+h3. 3. ...and here we go:
+
+Examples:
+
+<pre>
+Review.destroy_all # just in case...
+@post = Post.first
+@user = User.first
+
+@post.review!(:reviewer => @user, :rating => 2)  # new reviewer (type: object) => create
+@post.review!(:reviewer => @user, :rating => 5)  # same reviewer (type: object) => update
+
+@post.total_reviews   # => 1
+@post.average_rating  # => 5.0
+
+@post.review!(:reviewer => '128.0.0.0', :rating => 4)  # new reviewer (type: IP) => create
+@post.review!(:reviewer => '128.0.0.0', :rating => 2)  # same reviewer (type: IP) => update
+
+@post.total_reviews   # => 2
+@post.average_rating  # => 3.5
+
+@post.review!(:reviewer => @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!(:reviewer => '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...
+</pre>
+
+h2. Mixin Arguments
+
+The @is_reviewable@ mixin takes some hash arguments for customization:
+
+*Basic*
+
+* @:by@ - the reviewer model, e.g. User, Account, etc. (accepts either symbol or class, i.e. @User@ <=> @:user@ <=> @:users@). The reviewer model will be setup for you. Note: Polymorhic, so it accepts any model. Default: @User@, or auto-detection fails.
+* @: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 in comparison to reviewer model. 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@.
+
+h2. Finders
+
+IsReviewable has plenty of useful finders implemented using named scopes. Here they are:
+
+h3. @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 lowest 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.
+
+h3. @Reviewable@
+
+*Order:*
+
+_TODO: Documentation on named scopes for reviewable._
+
+*Filter:*
+
+_TODO: Documentation on named scopes for reviewable._
+
+h3. @Reviewer@
+
+*Order:*
+
+_TODO: Documentation on named scopes for reviewable._
+
+*Filter:*
+
+_TODO: Documentation on named scopes for reviewable._
+ 
+h3. Examples using finders:
+
+<pre>
+@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.
+</pre>
+
+h2. Additional Methods
+
+*Note:* See documentation (RDoc).
+
+h2. 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:
+
+<pre>
+class Review < IsReviewable::Review
+  
+  # Do what you do best here... (stating the obvious: core IsReviewable associations, named scopes, etc. will be inherited)
+  
+end
+</pre>
+
+h2. Caching
+
+If the visitable class table - in the sample above @Post@ - contains a columns @reviews_count@ and @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):
+
+<pre>
+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
+</pre>
+
+h2. Example
+
+h3. 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":http://github.com/josevalim/inherited_resources):
+
+Example: @app/controllers/reviews_controller.rb@:
+
+<pre>
+class ReviewsController < InheritedResources::Base
+  
+  actions :create, :update, :destroy
+  respond_to :js
+  layout false
+  
+end
+</pre>
+
+..or in the more basic rating case - @app/controllers/posts_controller.rb@:
+
+<pre>
+class PostsController < InheritedResources::Base
+  
+  actions :all
+  respond_to :html, :js
+  layout false if request.format == :js
+  
+  def rate
+    begin
+      @post.review! :reviewer => 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
+</pre>
+
+h3. Routes
+
+@config/routes.rb@
+
+<pre>
+map.resources :posts, :member => {:rate => :put}
+</pre>
+
+h3. 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@
+
+<pre>
+%h1
+  = @post.title
+%p
+  = @post.body
+%p
+  = "Your rating:"
+  #rating_wrapper= render '/reviews/rating', :resource => @post
+</pre>
+
+Example: @app/views/reviews/_rating.html.haml@
+
+<pre>
+.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}"}
+</pre>
+
+*Note:* Skipping review-body (etc.) in this view sample, but that is straightforward to implement anyways.
+
+h3. 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@
+
+<pre>
+page.replace_html '#rating_wrapper', render('/reviews/rating', :reviewable => @post, :reviewer => current_user)
+page.visual_effect :highlight, '.rating .current'
+</pre>
+
+Done! =)
+
+h2. Design Implications: Additional Use Cases
+
+h3. 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:
+
+Example:
+
+<pre>
+class Post < ActiveRecord::Base
+  is_reviewable :by => :users, :values => [-1, 1]
+end
+</pre>
+
+*Note:* @:values@ is an alias for @:scale@ for semantical reasons in cases like these.
+
+h2. Dependencies
+
+Basic usage:
+
+* "rails":http://github.com/rails/rails (well...)
+
+For running tests:
+
+* sqlite3-ruby
+* "thoughtbot-shoulda":http://github.com/thoughtbot/shoulda
+* "nakajima-acts_as_fu":http://github.com/nakajima/acts_as_fu
+* "jgre-monkeyspecdoc":http://github.com/jgre/monkeyspecdoc (optional)
+
+h2. Notes
+
+* Tested with Ruby 1.9.1.
+* Let me know if you find any bugs; not used in production yet so consider this a concept version.
+
+h2. TODO
+
+h3. Priority:
+
+* bug: Accept multiple reviewers (of different types): @average_rating_by@, etc.. 
+* documentation: A few more README-examples.
+* feature: Reviewable on multiple contexts, e.g. @is_reviewable :on => [:acting, :writing, ...]@. Alias method @is_reviewable_on@.
+* testing: More thorough tests, especially for named scopes which is a bit tricky.
+* feature: Useful finders for @Reviewable@.
+* feature: Useful finders for @Reviewer@.
+
+h3. Maybe:
+
+* feature: Make alias helpers to implement functionality like VoteFu (http://github.com/peteonrails/vote_fu), simply just aliasing methods with existing ones with hardcoded parameters. Not required because this is supported already, it's all about semantics and sassy code.
+
+h2. Related Links
+
+...that might be of interest.
+
+* "jQuery Star Rating":http://github.com/rathgar/jquery-star-rating/ - javascript star rating plugin for Rails on jQuery, if you don't want to do the rating widget on your own. It should be quite straightforward to customize the appearance of it for your needs too.
+
+h2. License
+
+Copyright (c) 2009 Jonas Grimfelt, released under the MIT-license.

data/Rakefile

@@ -0,0 +1,51 @@
+# coding: utf-8
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+NAME = "is_reviewable"
+SUMMARY = %Q{Rails: Make an ActiveRecord resource ratable/reviewable (rate + text), without the usual extra code-smell.}
+HOMEPAGE = "http://github.com/grimen/#{NAME}"
+AUTHOR = "Jonas Grimfelt"
+EMAIL = "grimen@gmail.com"
+SUPPORT_FILES = %w(README.textile)
+
+begin
+  gem 'technicalpickles-jeweler', '>= 1.2.1'
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = NAME
+    gem.summary = SUMMARY
+    gem.description = SUMMARY
+    gem.homepage = HOMEPAGE
+    gem.author = AUTHOR
+    gem.email = EMAIL
+    
+    gem.require_paths = %w{lib}
+    gem.files = SUPPORT_FILES << %w(MIT-LICENSE Rakefile) << Dir.glob(File.join('{generators,lib,test,rails}', '**', '*'))
+    gem.executables = %w()
+    gem.extra_rdoc_files = SUPPORT_FILES
+  end
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+desc %Q{Default: Run unit tests for "#{NAME}".}
+task :default => :test
+
+desc %Q{Run unit tests for "#{NAME}".}
+Rake::TestTask.new(:test) do |test|
+  test.libs << %w(lib test)
+  test.pattern = File.join('test', '**', '*_test.rb')
+  test.verbose = true
+end
+
+desc %Q{Generate documentation for "#{NAME}".}
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = NAME
+  rdoc.options << '--line-numbers' << '--inline-source' << '--charset=UTF-8'
+  rdoc.rdoc_files.include(SUPPORT_FILES)
+  rdoc.rdoc_files.include(File.join('lib', '**', '*.rb'))
+end