rateable_attributes 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg
+doc
+Manifest

data/README.rdoc

@@ -0,0 +1,52 @@
+= RateableAttributes
+
+RateableAttributes is a re-implementation of ActsAsRateable for multiple attribute support.
+
+== Usage
+
+=== Installation
+
+To install as plugin:
+
+  script/plugin install git://github.com/sdepold/rateable_attributes.git
+
+=== Preparation
+
+In order to create the rating table just run the following commands:
+  
+  script/generate rateable_attributes
+  rake db:migrate
+  
+This will generate a migration. Run rake db:migrate.
+
+=== In the model
+  
+  rateable_attributes :graphics, :sound, :whatever, :range => 1..5
+  
+This allows you to rate the model for the attributes graphics, sound and whatever.
+To do so use
+
+  my_model.rate(3, a_user[, :the_attribute]) # you can just ignore the attribute to create a general rating
+  my_model.rate_graphics(3, a_user) # equals my_model.rate(3, a_user, :graphics)
+
+=== Visualizing the average rating
+
+RateableAttributes a method to the model called visualize_average_rating.
+It can be called the following options:
+
+- attribute = The attribute you want to display. Default: nil
+- image_rated = The image/symbol you wish to be shown as reached rating. Default: A yellow star
+- image_unrated = The image/symbol you wish to be shown as unreached rating. Default: A white star
+- image_hover = The image/symbol you wish to be shown when hovering one of the rating images (see next option). Default: An orange star
+- enable_rating = Should the user be able to click and rate?
+- click_url = The URL which gets called, when a user clicked on a star to rate the model.
+
+When you enable the rating option, the controller should return a json object as follows:
+
+  {new_rating: 2}
+  
+Important as well is, that you include the generated javascript file. Just do the following in your documents head:
+
+  = javascript_include_tag "rateable_attributes.js"
+  
+The javascript uses the prototype plugin. Feel free to change it for JQuery if you are using it.

data/Rakefile

@@ -0,0 +1,19 @@
+begin
+  task :default => :spec
+
+  require 'spec/rake/spectask'
+  require 'jeweler'
+
+  Spec::Rake::SpecTask.new {|t| t.spec_opts = ['--color']}
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name        = "rateable_attributes"
+    gemspec.summary     = "Rate multiple attributes of models with Active Record."
+    gemspec.description = "Rate multiple attributes of models with Active Record."
+    gemspec.email       = "dev@depold.com"
+    gemspec.homepage    = "http://github.com/sdepold/rateable_attributes"
+    gemspec.authors     = ["Sascha Depold"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/generators/USAGE

@@ -0,0 +1 @@
+blab

data/generators/rateable_attributes_generator.rb

@@ -0,0 +1,13 @@
+class RateableAttributesGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.migration_template 'migration.rb', 'db/migrate', :migration_file_name => "rateable_attributes_migration"
+      m.directory "public/images/ratings"
+      m.file "star_rated.png", "public/images/ratings/star_rated.png"
+      m.file "star_unrated.png", "public/images/ratings/star_unrated.png"
+      m.file "star_hover.png", "public/images/ratings/star_hover.png"
+      m.file "rateable_attributes.js", "public/javascripts/rateable_attributes.js"
+      m.file "rateable_attributes_helper.rb", "app/helpers/rateable_attributes_helper.rb"
+    end
+  end
+end

data/generators/templates/migration.rb

@@ -0,0 +1,17 @@
+class RateableAttributesMigration < ActiveRecord::Migration
+  def self.up
+    create_table :ratings do |t|
+      t.integer :user_id
+      t.integer :rateable_id
+      t.string :rateable_type
+      t.string :rateable_attribute
+      t.integer :rating
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :ratings
+  end
+end

data/generators/templates/rateable_attributes.js

@@ -0,0 +1,24 @@
+function rateableAttributesHoverRatingImage(objectRating, idPrefix, hoveredRating, hoverImage) {
+  for(var i = 0; i <= hoveredRating; i++)
+    $(idPrefix + "_" + i).src = "/images/" + hoverImage;
+}
+
+function rateableAttributesUnhoverRatingImage(objectRating, maxRating, idPrefix, ratedImage, unratedImage) {
+  for(var i = 0; i < maxRating; i++) {
+    var imageURL = "/images/" + ((i < objectRating) ? ratedImage : unratedImage);
+    $(idPrefix + "_" + i).src = imageURL;
+  }
+}
+
+function rateableAttributesClickRatingImage(ajaxURL, clickedRating, clickedAttribute, maxRating, idPrefix, ratedImage, unratedImage) {
+  new Ajax.Request(ajaxURL, {
+    parameters: { 
+      rating: clickedRating,
+      attribute: clickedAttribute
+    },
+    onSuccess:function(data) {
+      var result = data.responseJSON;
+      rateableAttributesUnhoverRatingImage(result.new_rating, maxRating, idPrefix, ratedImage, unratedImage);
+    }
+  });
+}

data/generators/templates/rateable_attributes_helper.rb

@@ -0,0 +1,31 @@
+module RateableAttributesHelper
+  def visualize_average_rating(object, options={})
+    options[:attribute] ||= nil
+    options[:image_rated] ||= "ratings/star_rated.png"
+    options[:image_unrated] ||= "ratings/star_unrated.png"
+    options[:image_hover] ||= "ratings/star_hover.png"
+    options[:click_url] ||= ""
+
+    result = ""
+    rating = object.average_rating_rounded(options[:attribute])
+    max_rating = object.rateable_range.end
+    
+    max_rating.times do |i|
+      id = "#{object.class.to_s.downcase}_#{options[:attribute] || "general"}_#{object.id}"
+      image_options = {:id => "#{id}_#{i}"}
+      image = ((i + 1) <= rating) ? options[:image_rated] : options[:image_unrated]
+      
+      if options[:enable_rating]
+        image_options.merge!({
+          :onmousemove => "rateableAttributesHoverRatingImage(#{rating}, '#{id}', #{i}, '#{options[:image_hover]}')",
+          :onmouseout => "rateableAttributesUnhoverRatingImage(#{rating}, #{max_rating}, '#{id}', '#{options[:image_rated]}', '#{options[:image_unrated]}')",
+          :onclick => "rateableAttributesClickRatingImage('#{options[:click_url]}', #{i + 1}, '#{options[:attribute]}', #{max_rating}, '#{id}', '#{options[:image_rated]}', '#{options[:image_unrated]}')"
+        })
+      end
+      
+      result << image_tag(image, image_options)
+    end
+    
+    result
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require "rateable_attributes"

data/lib/rateable_attributes.rb

@@ -0,0 +1,89 @@
+module RateableAttributes
+  def self.included(base)
+    base.extend ClassMethods
+  end
+  
+  module ClassMethods
+    def rateable_attributes(*args)
+      has_many :ratings, :as => :rateable
+      
+      options = args.extract_options!
+      options[:range] ||= 1..5
+      
+      { :rateable_range => options[:range], :rateables => args }.each do |accessor, value|
+        next if respond_to?(accessor)
+        class_inheritable_accessor accessor
+        attr_protected accessor
+        self.send("#{accessor}=", value)
+      end
+      
+      include RateableAttributes::ClassMethods
+      include RateableAttributes::InstanceMethods
+    end
+  end
+  
+  module ClassMethods
+  end
+  
+  module InstanceMethods
+    def is_valid_rateable_attribute?(attribute)
+      attribute.nil? || rateables.include?(attribute.to_sym)
+    end
+    
+    def validate_rating_data!(rating, attribute)
+      raise "#{attribute} is not valid for this model. Choose one of the following: #{rateables.join(', ')}" unless is_valid_rateable_attribute?(attribute)
+      raise "The rating #{rating} is not in allowed rating range: #{rateable_range.to_s}" unless rateable_range.include?(rating)
+      true
+    end
+    
+    def rate(rating, user, attribute=nil)
+      validate_rating_data!(rating, attribute)
+      return rating_by(user, attribute) if was_rated_by?(user, attribute)
+      Rating.create({:user => user, :rating => rating, :rateable_attribute => attribute, :rateable => self}) 
+    end
+    
+    def rate!(rating, user, attribute=nil)
+      validate_rating_data!(rating, attribute)
+      Rating.create!({:user => user, :rating => rating, :rateable_attribute => attribute, :rateable => self}) 
+    end
+    
+    def average_rating(attribute=nil)
+      attribute = attribute.to_s unless attribute.nil?
+      all_ratings = ratings.find(:all, :conditions => {:rateable_attribute => attribute})
+      return 0.0 if all_ratings.empty?
+      all_ratings.sum(&:rating) / all_ratings.size
+    end
+    
+    def average_rating_rounded(attribute=nil)
+      average_rating(attribute).round
+    end
+    
+    def average_rating_percentage(attribute=nil)
+      average_rating(attribute) * 100 / rateable_range.end
+    end
+    
+    def was_rated_by?(user, attribute=nil)
+      attribute = attribute.to_s unless attribute.nil?
+      ratings.find(:first, :conditions => {:user_id => user.id, :rateable_attribute => attribute}).present?
+    end
+    
+    def rating_by(user, attribute=nil)
+      attribute = attribute.to_s unless attribute.nil?
+      ratings.find(:first, :conditions => {:user_id => user.id, :rateable_attribute => attribute})
+    end
+    
+    private
+    
+    def method_missing(method, *args, &block)
+      return super(method, *args, &block) unless method.to_s.starts_with?("rate_")
+
+      # this will find method calls like rate_accuracy
+      attribute = method.to_s.split("rate_").last
+      rate(args[0], args[1], attribute) if rateables.include?(attribute.to_sym) && ![args[0], args[1]].include?(nil)
+    end 
+  end
+end
+
+class ActiveRecord::Base
+  include RateableAttributes
+end

data/lib/rating.rb

@@ -0,0 +1,6 @@
+class Rating < ActiveRecord::Base
+  belongs_to :user
+  validates_presence_of :rateable_id, :rateable_type, :user_id, :rating
+  validates_uniqueness_of :rateable_id, :scope => [:rateable_type, :user_id, :rateable_attribute]
+  belongs_to :rateable, :polymorphic => true
+end

data/rateable_attributes.gemspec

@@ -0,0 +1,58 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{rateable_attributes}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Sascha Depold"]
+  s.date = %q{2010-02-28}
+  s.description = %q{Rate multiple attributes of models with Active Record.}
+  s.email = %q{dev@depold.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "generators/USAGE",
+     "generators/rateable_attributes_generator.rb",
+     "generators/templates/migration.rb",
+     "generators/templates/rateable_attributes.js",
+     "generators/templates/rateable_attributes_helper.rb",
+     "generators/templates/star_hover.png",
+     "generators/templates/star_rated.png",
+     "generators/templates/star_unrated.png",
+     "init.rb",
+     "lib/rateable_attributes.rb",
+     "lib/rating.rb",
+     "rateable_attributes.gemspec",
+     "spec/make_rateable_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/sdepold/rateable_attributes}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Rate multiple attributes of models with Active Record.}
+  s.test_files = [
+    "spec/make_rateable_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/spec/make_rateable_spec.rb

@@ -0,0 +1,163 @@
+require File.dirname(__FILE__)+'/spec_helper'
+
+describe Project do
+  describe :rateable_range do
+    it "should have a range" do
+      Project.rateable_range.should_not be_nil
+    end
+    
+    it "should have the attributes, specified in model" do
+      Project.rateables.should == [:usability, :performance, :functionality]
+    end
+  end
+  
+  describe :is_valid_rateable_attribute? do
+    before :all do
+      @project = Project.create(:name => "foo")
+    end
+    
+    it "should return true if passed value is nil (= general rating)" do
+      @project.is_valid_rateable_attribute?(nil).should be_true
+    end
+    
+    it "should return true if passed value is one of the specified attributes" do
+      @project.is_valid_rateable_attribute?(:usability).should be_true
+    end
+    
+    it "should return false if passed value is not nil and not one of the specified attributes" do
+      @project.is_valid_rateable_attribute?(:bar).should be_false
+    end
+  end
+  
+  describe :validate_rating_data! do
+    before :all do
+      @project = Project.create(:name => "foo")
+    end
+    
+    it "should throw an exception if is_valid_rateable_attribute? returns false" do
+      lambda{@project.validate_rating_data!(9, :foo)}.should raise_error
+    end
+    
+    it "should throw an exception if rating is not in rateable_range" do
+      lambda{@project.validate_rating_data!(8, nil)}.should raise_error
+    end
+    
+    it "should return true if everything is nice" do
+      @project.validate_rating_data!(3, nil).should be_true
+    end
+  end
+  
+  describe :rate do
+    before :each do
+      @project = Project.create(:name => "foo")
+      @project.should_receive(:validate_rating_data!).and_return true
+      @user = User.create(:name => "max")
+    end
+    
+    it "should return available rating if already rated by user" do
+      @project.should_receive(:was_rated_by?).and_return true
+      @project.should_receive(:rating_by)
+      lambda{@project.rate(1, @user)}.should_not change(Rating, :count).by(1)
+    end
+    
+    it "should not return a given rating but create one if not yet rated by user" do
+      @project.should_receive(:was_rated_by?).and_return false
+      @project.should_not_receive(:rating_by)
+      lambda{@project.rate(1, @user)}.should change(Rating, :count).by(1)      
+    end
+  end
+  
+  describe :average_rating do
+    before :each do
+      Rating.destroy_all
+    end
+
+    it "should return 0.0 if no rating is given" do
+      Project.create(:name => "foo").average_rating.should == 0.0
+    end
+    
+    it "should calculate correctly" do
+      p = Project.create(:name => "foo")
+      u = User.create(:name => "max")
+      u2 = User.create(:name => "maxine")
+      
+      p.rate 1, u
+      p.rate 5, u2
+      
+      p.average_rating.should == 3.0
+    end
+  end
+  
+  describe :average_rating_rounded do
+    it "should return rounded ratings" do
+      Rating.destroy_all
+      
+      p = Project.create(:name => "foo")
+      u = User.create(:name => "max")
+      u2 = User.create(:name => "maxine")
+      
+      p.rate 1, u
+      p.rate 2, u2
+      
+      p.average_rating_rounded.should == 1
+    end
+  end
+  
+  describe :average_rating_percentage do
+    it "should return a percentage" do
+      p = Project.create(:name => "foo")
+      p.rate 4, User.create(:name => "max")
+      
+      p.average_rating_percentage.should == 80
+    end
+  end
+  
+  describe :was_rated_by? do
+    before :each do
+      @project = Project.create(:name => "hello world")
+      @user = User.create(:name => "my_user")
+    end
+    
+    it "should return false if user hasn't rated yet" do
+      @project.was_rated_by?(@user).should be_false
+    end
+    
+    it "should return true if user has already rated" do
+      @project.rate 1, @user
+      @project.was_rated_by?(@user).should be_true
+    end
+  end
+  
+  describe :rating_by do
+    before :each do
+      @project = Project.create(:name => "hello world")
+      @user = User.create(:name => "my_user")
+    end
+    
+    it "should return nil if no rating was given" do
+      @project.rating_by(@user).should be_nil
+    end
+    
+    it "should return the rating object if rating was given" do
+      @project.rate 1, @user
+      r = @project.rating_by(@user)
+      r.should_not be_nil
+      r.class.to_s.should == "Rating"
+      r.rating.should == 1
+    end
+  end
+  
+  describe :method_missing do
+    before :each do
+      @project = Project.create(:name => "hello world")
+      @user = User.create(:name => "my_user")
+    end
+    
+    
+    it "should add methods for rating the defined attributes" do
+      lambda{@project.rate_usability(1, @user)}.should change(Rating, :count).by(1)
+      lambda{@project.rate_performance(1, @user)}.should change(Rating, :count).by(1)
+      lambda{@project.rate_functionality(1, @user)}.should change(Rating, :count).by(1)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,36 @@
+require 'rubygems'
+require "active_record"
+require "action_view"
+require File.dirname(__FILE__)+"/../lib/rateable_attributes.rb"
+require File.dirname(__FILE__)+"/../generators/templates/migration.rb"
+require File.dirname(__FILE__)+"/../lib/rating.rb"
+
+
+ActiveRecord::Base.establish_connection({
+  :adapter => "sqlite3",
+  :database => ":memory:"
+})
+
+ActiveRecord::Schema.define(:version => 1) do
+  RateableAttributesMigration.up
+  
+  create_table :projects, :force=>true do |t|
+    t.string :name
+    t.timestamps
+  end
+  
+  create_table :users, :force => true do |t|
+    t.string :name
+    t.timestamps
+  end
+end
+
+class Project < ActiveRecord::Base
+  rateable_attributes :usability, :performance, :functionality
+  validates_presence_of :name
+end
+
+class User < ActiveRecord::Base
+  validates_presence_of :name
+  has_many :ratings
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: rateable_attributes
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Sascha Depold
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-28 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Rate multiple attributes of models with Active Record.
+email: dev@depold.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .gitignore
+- README.rdoc
+- Rakefile
+- VERSION
+- generators/USAGE
+- generators/rateable_attributes_generator.rb
+- generators/templates/migration.rb
+- generators/templates/rateable_attributes.js
+- generators/templates/rateable_attributes_helper.rb
+- generators/templates/star_hover.png
+- generators/templates/star_rated.png
+- generators/templates/star_unrated.png
+- init.rb
+- lib/rateable_attributes.rb
+- lib/rating.rb
+- rateable_attributes.gemspec
+- spec/make_rateable_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/sdepold/rateable_attributes
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Rate multiple attributes of models with Active Record.
+test_files: 
+- spec/make_rateable_spec.rb
+- spec/spec_helper.rb