acts_as_reviewable 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1a1092dcf9cab7737bf24efc3ffa2305648b5553
+  data.tar.gz: 0c2d95915e84ecd557a57082e3ddc2d9440a4e96
+SHA512:
+  metadata.gz: 63757e0b3829e8ec3c2a0db917d8609a45ddcd72fd4c9758f743fa9ded8f76f6d1d50adeec36f5a416b3fb9a3c86819a3a2b79c891cf436593ef35fe4150a968
+  data.tar.gz: 7fb55d75509c2055769d653eb647455962be041657027c68c35145f7133aaf13bd646f98441c79e905a48a00b46a53198fd9fb4c9a3df7dbb907d4d2ced380b1

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+
+gem "rails", "3.0.5"
+gem "capybara", ">= 0.4.0"
+gem "sqlite3"
+
+gem "rspec-rails", ">= 2.0.0.beta"
+gem "genspec"
+
+
+# To use debugger (ruby-debug for Ruby 1.8.7+, ruby-debug19 for Ruby 1.9.2+)
+# gem 'ruby-debug'
+# gem 'ruby-debug19'

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2011 YOURNAME
+
+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.md

@@ -0,0 +1,321 @@
+# ActsAsReviewable
+
+Reviews for any AR model with multi-dimensional ratings, review commentary, and info-graphics.
+
+## ActsAsReviewable -  concept v0.0.1.
+
+_Rails: Make an ActiveRecord resource rateable/reviewable  (rating + comment) across multiple dimensions with infographics._
+
+## Why another rating/review-plugin?
+
+Existing plugins rate on one dimension and provide basic analytics and no charting.
+
+* Don't assume that your rater/reviewer model is *User*. Use polymorphic associations, so your reviewer can be...*anymodel*.
+* Don't make assumptions about the rating scale, how it should be divided, or rounding precision for stats.
+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 a *title* and *body* to make up a "review" instead of just a "rating". Feel free.
+* Finders implemented using scopes, i.e.. less code smell.
+* Information graphics provided as an optional extension to the plugin. Engine for charting would be useful, even if just for admins.
+
+## Installation
+
+*Gem:*
+
+`gem install acts_as_reviewable`
+
+for rails 3, in your Gemfile:
+
+`gem 'acts_as_reviewable'`
+
+# Usage
+
+## 1. Generate migration:
+
+`$ rails generate acts_as_reviewable_migration`
+
+Generates *db/migrations/{timestamp}_acts_as_reviewable_migration* with
+
+
+<pre>
+class ActsAsReviewableMigration &lt; ActiveRecord::Migration
+  def self.up
+    create_table :reviews do |t|
+      t.references  :reviewable,    :polymorphic => true
+
+      t.references  :reviewer,      :polymorphic => true
+
+      t.float       :rating
+      t.text        :comment
+
+      #
+      # Custom fields go here...
+      #
+      # t.string      :title
+      # t.string      :intention
+      # ...
+      #
+
+      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>
+
+## 2. Make your model reviewable:
+<pre>
+class Post &lt; ActiveRecord::Base
+   acts_as_reviewable :scale => 0..5
+end
+</pre>
+
+or, with explicit reviewer (or reviewers):
+
+<pre>
+class Book &lt; ActiveRecord::Base
+  # Setup associations for the reviewer class(es) automatically, and specify an explicit scale instead.
+  acts_as_reviewable :by => [:users, :authors], :scale => 0..5
+end
+</pre>
+
+## 3. API - a stable public api is scheduled for release 1.0.0 (plausibly June 2011)
+
+Examples:
+
+<pre>
+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.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 => @user)  # delete existing review (type: User) => 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>
+
+# Mixin Arguments
+
+The *acts_as_reviewable* mixin takes the following 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]. =)
+
+*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 ActsAsReviewable 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:
+
+<pre>
+@post.reviews.first.owner == post.reviews.first.reviewer      # => true
+@post.reviews.first.object == post.reviews.first.reviewable   # => true
+</pre>
+
+# Finders (Named Scopes)
+
+ActsAsReviewable has plenty of useful finders implemented using 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 scopes for Reviewable._
+
+## *Reviewer*
+
+_TODO: Documentation on scopes for Reviewer._
+
+## 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
+
+</pre>
+
+# Additional Methods
+
+## Routes
+
+*config/routes.rb*
+
+<pre>
+resources :posts, :member => {:rate => :put}
+</pre>
+
+## Views
+
+ActsAsReviewable comes with no view templates (etc.), 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>
+
+## JavaScript/AJAX
+
+
+Done! =)
+
+# Additional Use Cases
+
+## Like/Dislike
+
+ActsAsReviewable 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 ActsAsReviewable:
+
+Example:
+
+<pre>
+class Post &lt; ActiveRecord::Base
+  acts_as_reviewable :by => :users, :values => [0, 1]
+end
+</pre>
+
+*Note:* *:values* is an alias for *:scale* for semantical reasons in cases like these.
+
+# Dependencies
+
+For testing: "rspec" and "sqlite3-ruby":http://gemcutter.org/gems/sqlite3-ruby.
+
+# Notes
+
+* Tested with Ruby 1.9.2 and Rails 3.0.5.
+* Let me know if you find any bugs; not used in production yet so consider this a concept version.
+
+# TODO
+
+## Priority:
+
+* bug: Accept , etc..
+* documentation: A few more README-examples.
+* feature: Useful finders for *Reviewable*.
+* feature: Useful finders for *Reviewer*.
+* testing: More thorough tests, especially for scopes which is a bit tricky.
+
+## Maybe:
+
+# 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.
+
+
+# Versioning
+
+This project uses Semantic Versioning -- Please read and use to make the world a better place for software: http://semver.org/
+
+# License
+
+Released under the MIT license.
+Copyright (c) "Eric Steen":http://github.com/rubycoder1
+
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,25 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+require 'rake/rdoctask'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ActsAsReviewable'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/acts_as_reviewable.rb

@@ -0,0 +1,2 @@
+require 'reviewable_methods'
+require 'review_methods'

data/lib/generators/review/USAGE

@@ -0,0 +1,6 @@
+Description:
+    Copies review.rb to app/models/.
+    Copies create_review.rb to db/migrate
+
+Examples:
+    `rails generate acts_as_reviewable`

data/lib/generators/review/review_generator.rb

@@ -0,0 +1,19 @@
+require 'rails/generators/migration'
+
+class ActsAsReviewableMigrationGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  desc "run this generator to create reviews"
+
+  def self.source_root
+    @_acts_as_reviewable_source_root ||= File.expand_path("../templates", __FILE__)
+  end
+
+  def self.next_migration_number(path)
+    Time.now.utc.strftime("%Y%m%d%H%M%S")
+  end
+
+  def create_model_file
+    template "review.rb", "app/models/review.rb"
+    migration_template "create_reviews.rb", "db/migrate/create_reviews.rb"
+  end
+end

data/lib/generators/review/templates/create_reviews.rb

@@ -0,0 +1,21 @@
+class CreateReviews < ActiveRecord::Migration
+  def self.up
+    create_table :reviews do |t|
+      t.string :title, :limit => 50, :default => ""
+      t.text :review
+      t.references :reviewable, :polymorphic => true
+      t.references :user
+      t.string :role, :default => "reviews"
+      t.timestamps
+    end
+
+    add_index :comments, :reviewable_type
+    add_index :comments, :reviewable_id
+    add_index :comments, :user_id
+  end
+
+  def self.down
+    drop_table :reviews
+  end
+end
+

data/lib/generators/review/templates/review.rb

@@ -0,0 +1,15 @@
+class Review < ActiveRecord::Base
+
+  include ActsAsReviewable::Review
+
+  belongs_to :reviewable, :polymorphic => true
+  belongs_to :reviewer, :polymorphic => true
+
+  default_scope :order => 'created_at ASC'
+
+  # NOTE: install the acts_as_votable plugin if you
+  # want votes on reviews.
+  #acts_as_voteable
+
+end
+

data/lib/review_methods.rb

@@ -0,0 +1,42 @@
+module ActsAsReviewable
+  # including this module into your Review model will give you finders and named scopes
+  # useful for working with Reviews.
+  # The named scopes are:
+  # in_order: Returns reviews in the order they were created (created_at ASC).
+  # recent: Returns reviews by how recently they were created (created_at DESC).
+  # limit(N): Return no more than N reviews.
+  module Review
+
+    def self.included(review_model)
+      review_model.extend Finders
+      review_model.scope :in_order, review_model.order('created_at ASC')
+      review_model.scope :recent, review_model.order('created_at DESC')
+
+    end
+
+    def is_review_type?(type)
+      type.to_s == role.singularize.to_s
+    end
+
+    module Finders
+      # Helper class method to lookup all reviews assigned
+      # to all reviewable types for a given user.
+      def find_reviews_by_user(user, role = "reviews")
+        where(["user_id = ? and role = ?", user.id, role]).order("created_at DESC")
+      end
+
+      # Helper class method to look up all reviews for
+      # reviewable class name and reviewable id.
+      def find_reviews_for_reviewable(reviewable_str, reviewable_id, role = "reviews")
+        where(["reviewable_type = ? and reviewable_id = ? and role = ?", reviewable_str, reviewable_id, role]).order("created_at DESC")
+      end
+
+      # Helper class method to look up a reviewable object
+      # given the reviewable class name and id
+      def find_reviewable(reviewable_str, reviewable_id)
+        model = reviewable_str.constantize
+        model.respond_to?(:find_reviews_for) ? model.find(reviewable_id) : nil
+      end
+    end
+  end
+end

data/lib/reviewable_methods.rb

@@ -0,0 +1,71 @@
+require 'active_record'
+
+# ActsAsReviewable
+module RapidFire
+  module Acts #:nodoc:
+    module Reviewable #:nodoc:
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def acts_as_reviewable(*args)
+          review_roles = args.to_a.flatten.compact.map(&:to_sym)
+          write_inheritable_attribute(:review_types, (review_roles.blank? ? [:reviews] : review_roles))
+          class_inheritable_reader(:review_types)
+
+          options = ((args.blank? or args[0].blank?) ? {} : args[0])
+
+          if !review_roles.blank?
+            review_roles.each do |role|
+              has_many "#{role.to_s}_reviews".to_sym,
+                {:class_name => "Review",
+                  :as => :reviewable,
+                  :dependent => :destroy,
+                  :conditions => ["role = ?", role.to_s],
+                  :before_add => Proc.new { |x, c| c.role = role.to_s }}
+            end
+          else
+            has_many :reviews, {:as => :reviewable, :dependent => :destroy}
+          end
+
+          review_types.each do |role|
+            method_name = (role == :reviews ? "reviews" : "#{role.to_s}_reviews").to_s
+            class_eval %{
+              def self.find_#{method_name}_for(obj)
+              reviewable = self.base_class.name
+              review.find_reviews_for_reviewable(reviewable, obj.id, "#{role.to_s}")
+              end
+
+              def self.find_#{method_name}_by_user(user)
+              reviewable = self.base_class.name
+              review.where(["user_id = ? and reviewable_type = ? and role = ?", user.id, reviewable, "#{role.to_s}"]).order("created_at DESC")
+              end
+
+              def #{method_name}_ordered_by_submitted
+              review.find_reviews_for_reviewable(self.class.name, id, "#{role.to_s}")
+              end
+
+              def add_#{method_name.singularize}(review)
+              review.role = "#{role.to_s}"
+              #{method_name} << review
+              end
+              }
+
+            include RapidFire::Acts::Reviewable::InstanceMethods
+          end
+        end # def acts_as_reviewable
+      end # module ClassMethods
+
+      module InstanceMethods
+
+        
+      end # module InstanceMethods
+      
+    end # module Reviewable
+  end
+end
+
+ActiveRecord::Base.class_eval { include RapidFire::Acts::Reviewable }
+

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: acts_as_reviewable
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ernest Wu
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-16 00:00:00.000000000 Z
+dependencies: []
+description: Reviews for any AR model with multi-dimensional ratings and review commentary.
+email: wuboys@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/acts_as_reviewable.rb
+- lib/generators/review/review_generator.rb
+- lib/generators/review/templates/create_reviews.rb
+- lib/generators/review/templates/review.rb
+- lib/generators/review/USAGE
+- lib/review_methods.rb
+- lib/reviewable_methods.rb
+- MIT-LICENSE
+- Rakefile
+- Gemfile
+- README.md
+homepage: 
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.5
+signing_key: 
+specification_version: 4
+summary: Reviews for any AR model with multi-dimensional ratings and review commentary.
+test_files: []