edgarjs-ajaxful_rating 2.1.0

data/CHANGELOG

@@ -0,0 +1,2 @@
+== 2.1.0 July 25, 2009
+* AjaxfulRating is now available as a gem

data/Manifest

@@ -0,0 +1,15 @@
+CHANGELOG
+generators/ajaxful_rating/ajaxful_rating_generator.rb
+generators/ajaxful_rating/templates/images/star.png
+generators/ajaxful_rating/templates/images/star_small.png
+generators/ajaxful_rating/templates/migration.rb
+generators/ajaxful_rating/templates/model.rb
+generators/ajaxful_rating/templates/style.css
+generators/ajaxful_rating/USAGE
+init.rb
+lib/ajaxful_rating.rb
+lib/ajaxful_rating_helper.rb
+lib/ajaxful_rating_model.rb
+Manifest
+Rakefile
+README.textile

data/README.textile

@@ -0,0 +1,223 @@
+h1. Ajaxful Rating
+
+Provides a simple way to add rating functionality to your application.
+
+h2. Repository
+
+Find it at "github.com/edgarjs/ajaxful-rating":http://github.com/edgarjs/ajaxful-rating
+
+h2. Demo
+
+You can find a demo working app for this plugin at "http://github.com/edgarjs/ajaxful-rating_demo_app":http://github.com/edgarjs/ajaxful-rating_demo_app
+Just migrate and run...
+
+*******************************************************************
+
+h2. Instructions
+
+h3. Install
+
+To install the plugin:
+
+  @script/plugin install git://github.com/edgarjs/ajaxful-rating.git@
+
+Or the gem
+
+  @sudo gem install edgarjs-ajaxful_rating --source=http://gems.github.com@
+  
+You can configure it in your environment.rb file also:
+
+  @config.gem "edgarjs-ajaxful_rating", :lib => "ajaxful_rating", :source => "http://gems.github.com"@
+
+h3. Generate
+
+  @script/generate ajaxful_rating UserModelName@
+	
+The generator takes one argument: UserModelName, which is the name of your *current*
+user model. This is necessary to link both the rate and user models.
+
+Also this generator copies the necesary images, styles, etc.
+
+Example:
+_I suppose you have generated already an authenticated model..._
+
+  <pre><code>
+  script/generate authenticated user sessions
+  script/generate ajaxful_rating user
+  </code></pre>
+
+So this call will create a Rate model and will link it to your User model.
+
+h3. Prepare
+
+To let a model be rateable just add @ajaxful_rateable@. You can pass a hash of options to
+customise this call:
+* @:stars@ Max number of stars that can be submitted.
+* @:allow_update@ Set to true if you want users to be able to update their votes.
+* @:cache_column@ Name of the column for storing the cached rating average.
+* @:dimensions@ Array of dimensions. Allows to rate the model on various specs,
+like for example: a car could be rated for its speed, beauty or price.
+
+  <pre><code>
+  class Car < ActiveRecord::Base
+    ajaxful_rateable :stars => 10, :dimensions => [:speed, :beauty, :price]
+  end
+  </code></pre>
+
+Then you need to add a call @ajaxful_rater@ in the user model. This includes a simple line so
+you can add it _by your own_ as well (@has_many :rates@).
+
+  <pre><code>
+  class User < ActiveRecord::Base
+    ajaxful_rater
+  end
+  </code></pre>
+
+Finally, as a mere recomendation to make it even easier, modify your routes to
+map a rate action:
+
+  @map.resources :cars, :member => {:rate => :post}@
+
+h3. Use it
+
+To add the star links you need to call the helper method @ratings_for@.
+It tries to call @current_user@ method as the rater instance. You can pass @:static@
+as the second param to display only the static stars (not clickables).
+And also you can pass the dimension you want to show the ratings for.
+
+  <pre><code>
+  #show.html.erb
+  <%= ratings_for @article %>
+  
+  #To display static stars:
+  <%= ratings_for @article, :static %>
+
+  #To display the ratings for a dimension:
+  <%= ratings_for @article, :dimension => :speed %>
+  </code></pre>
+
+Or you can specify a custom user instance by passing it as parameter.
+
+  <pre><code>
+  <%= ratings_for @article, @user %>
+  </code></pre>
+		
+There's a condition here, if you didn't add the route @rate@ to your resource 
+(as shown above) or you named it different, you'll need to pass the url to the
+correct action in your controller:
+
+  <pre><code>
+  <%= ratings_for @article, :remote_options => {:url => your_rate_path(@article)} %>
+  </code></pre>
+
+*To display the stars properly you need to add a call in the head of your layout, which will generate the
+required CSS style for the list. Also don't forget to include the javascripts.*
+
+  <pre><code>
+    #within the head tags of your layout...
+    <%= javascript_include_tag :defaults %>
+    <%= ajaxful_rating_style %>
+  </code></pre>
+		
+When a user submits a rating it will call the action in your controller, for
+example (if you added the @rate@ route):
+
+  <pre><code>
+  def rate
+    @article = Article.find(params[:id])
+    @article.rate(params[:stars], current_user, params[:dimension])
+    id = "ajaxful-rating-#{!params[:dimension].blank? ? "#{params[:dimension]}-" : ''}article-#{@article.id}"
+    render :update do |page|
+      page.replace_html id, ratings_for(@article, :wrap => false, :dimension => params[:dimension])
+      page.visual_effect :highlight, id
+    end
+  end
+  </code></pre>
+
+There are some more options for this helper, please see the rdoc for details.
+
+h3. Dimensions
+
+From now on you can pass an optional parameter to the @rates@ method for your rateable object to retrieve the
+corresponding rates for the dimension you want.
+
+For example, you defined these dimensions:
+
+  <pre><code>
+  class Car < ActiveRecord::Base
+    ajaxful_rateable :dimensions => [:speed, :beauty, :price]
+  end
+  </code></pre>
+
+And hence you can call @car.rates(:price)@ for the price rates or @car.rates(:speed)@ for the speed ratings and so on.
+
+h3. Namespaces
+
+If you use the plugin inside a namespace you’ll need to specify the rating url which should points to
+a controller inside a namespace. Your files should be like these:
+
+  <pre><code>
+  routes.rb:
+  map.namespace :admin do |admin|
+    admin.resources :articles, :member => {:rate => :post}
+  end
+
+  views/admin/articles/show.html.erb
+  <%= ratings_for @article, :remote_options => {:url => rate_admin_article_path(@article)} %>
+  </code></pre>
+
+h3. Cache
+
+To cache the model's rating average add a column named @rating_average@ to your model table:
+
+  <pre><code>
+  class AddRatingAverageToArticles < ActiveRecord::Migration
+    def self.up
+      add_column :articles, :rating_average, :decimal, :default => 0
+    end
+  
+    def self.down
+      remove_column :articles, :rating_average
+    end
+  end
+  </code></pre>
+
+If you want to customise the name of the cache column just pass it in the options hash:
+
+  <pre><code>
+  class Article < ActiveRecord::Base
+    ajaxful_rateable :cache_column => :my_cached_rating
+  end
+  </code></pre>
+
+To use caching with dimensions, make sure you have a cache column defined for each dimension you want cached.
+So if you want to cache the @spelling@ dimension, you’ll need to have a column called @rating_average_spelling@ on the articles table.
+If you use a custom cache column name, follow the pattern @cache_column_name_dimension_name@ to add cache columns for dimensions.
+
+h2. About backwards compatibility
+
+*Version 2.0 of the plugin works only from Rails 2.2 and on. It uses the module @I18n@ which is new in rails 2.2. Please note that you can use it in past versions as long as you _customise_ the source code.*
+
+I decided to jump directly to version 2.0 because there are many important changes. You can always
+checkout the version 1.0 from the repository though.
+
+h2. Feedback
+
+If you find bugs please open a ticket at "http://github.com/edgarjs/ajaxful-rating/issues":http://github.com/edgarjs/ajaxful-rating/issues
+
+I'll really appreciate your feedback, please contact me at e[at]dgar[dot]org
+
+h2. Credits
+
+The helper's style is from "komodomedia":http://www.komodomedia.com/blog/2007/01/css-star-rating-redux/ with author's permission.
+
+If you need the psd files of the stars you can grab them "here":http://aws3-edgarjs-zips.s3.amazonaws.com/ajaxful_rating_stars.zip
+
+Thanks to "bborn":http://github.com/bborn for the dimensions base implementation.
+
+h2. License
+
+This code is released under Creative Commons Attribution-Share Alike 3.0 license.
+
+!http://i.creativecommons.org/l/by-sa/3.0/88x31.png!:http://creativecommons.org/licenses/by-sa/3.0/
+

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('ajaxful_rating', '2.1.0') do |p|
+  p.description    = "Provides a simple way to add rating functionality to your application."
+  p.url            = "http://github.com/edgarjs/ajaxful-rating"
+  p.author         = "Edgar J. Suarez"
+  p.email          = "e@dgar.org"
+  p.ignore_pattern = ["tmp/*", "script/*"]
+  p.development_dependencies = []
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/ajaxful_rating.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{ajaxful_rating}
+  s.version = "2.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Edgar J. Suarez"]
+  s.date = %q{2009-07-25}
+  s.description = %q{Provides a simple way to add rating functionality to your application.}
+  s.email = %q{e@dgar.org}
+  s.extra_rdoc_files = ["CHANGELOG", "lib/ajaxful_rating.rb", "lib/ajaxful_rating_helper.rb", "lib/ajaxful_rating_model.rb", "README.textile"]
+  s.files = ["CHANGELOG", "generators/ajaxful_rating/ajaxful_rating_generator.rb", "generators/ajaxful_rating/templates/images/star.png", "generators/ajaxful_rating/templates/images/star_small.png", "generators/ajaxful_rating/templates/migration.rb", "generators/ajaxful_rating/templates/model.rb", "generators/ajaxful_rating/templates/style.css", "generators/ajaxful_rating/USAGE", "init.rb", "lib/ajaxful_rating.rb", "lib/ajaxful_rating_helper.rb", "lib/ajaxful_rating_model.rb", "Manifest", "Rakefile", "README.textile", "ajaxful_rating.gemspec"]
+  s.homepage = %q{http://github.com/edgarjs/ajaxful-rating}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Ajaxful_rating", "--main", "README.textile"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{ajaxful_rating}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Provides a simple way to add rating functionality to your application.}
+
+  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/generators/ajaxful_rating/USAGE

@@ -0,0 +1,5 @@
+Description:
+    Generates a model called Rate linked to a user model named as the passed parameter.
+
+Example:
+    ./script/generate ajaxful_rating User

data/generators/ajaxful_rating/ajaxful_rating_generator.rb

@@ -0,0 +1,30 @@
+class AjaxfulRatingGenerator < Rails::Generator::NamedBase
+  def initialize(runtime_args, runtime_options = {})
+    super
+      
+    # if there's no user model
+    model_file = File.join('app/models', "#{file_path}.rb")
+    raise "User model (#{model_file}) must exits." unless File.exists?(model_file)
+  end
+  
+  def manifest
+    record do |m|
+      m.class_collisions 'Rate'
+      m.template 'model.rb', File.join('app/models', 'rate.rb')
+      m.migration_template 'migration.rb', 'db/migrate',
+        :migration_file_name => 'create_rates'
+      
+      # style
+      m.directory 'public/images/ajaxful_rating'
+      m.file 'images/star.png', 'public/images/ajaxful_rating/star.png'
+      m.file 'images/star_small.png', 'public/images/ajaxful_rating/star_small.png'
+      m.file 'style.css', 'public/stylesheets/ajaxful_rating.css'
+    end
+  end
+  
+  protected
+  
+  def banner
+    "Usage: #{$0} ajaxful_rating UserModelName"
+  end
+end

data/generators/ajaxful_rating/templates/migration.rb

@@ -0,0 +1,19 @@
+class CreateRates < ActiveRecord::Migration
+  def self.up
+    create_table :rates do |t|
+      t.references :<%= file_name %>
+      t.references :rateable, :polymorphic => true
+      t.integer :stars
+      t.string :dimension
+
+      t.timestamps
+    end
+    
+    add_index :rates, :<%= file_name %>_id
+    add_index :rates, :rateable_id
+  end
+
+  def self.down
+    drop_table :rates
+  end
+end

data/generators/ajaxful_rating/templates/model.rb

@@ -0,0 +1,6 @@
+class Rate < ActiveRecord::Base
+  belongs_to :<%= file_name %>
+  belongs_to :rateable, :polymorphic => true
+  
+  attr_accessible :rate, :dimension
+end

data/generators/ajaxful_rating/templates/style.css

@@ -0,0 +1,84 @@
+/*
+* Style by Rogie http://www.komodomedia.com/blog/2007/01/css-star-rating-redux/
+*/
+
+.ajaxful-rating,
+.ajaxful-rating a:hover,
+.ajaxful-rating a:active,
+.ajaxful-rating a:focus,
+.ajaxful-rating .current-rating{
+    background: url(/images/ajaxful_rating/star.png) left -1000px repeat-x;
+}
+.ajaxful-rating{
+    position: relative;
+    /*width: 125px; this is setted dynamically */
+    height: 25px;
+    overflow: hidden;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    background-position: left top;
+}
+.ajaxful-rating li{ display: inline; }
+.ajaxful-rating a,
+.ajaxful-rating span,
+.ajaxful-rating .current-rating{
+    position: absolute;
+    top: 0;
+    left: 0;
+    text-indent: -1000em;
+    height: 25px;
+    line-height: 25px;
+    outline: none;
+    overflow: hidden;
+    border: none;
+}
+.ajaxful-rating a:hover,
+.ajaxful-rating a:active,
+.ajaxful-rating a:focus{
+    background-position: left bottom;
+}
+
+/* This section is generated dynamically.
+Just add a call to the helper method 'ajaxful_rating_style' within
+the head tags in your main layout 
+.ajaxful-rating .stars-1{
+width: 20%;
+z-index: 6;
+}
+.ajaxful-rating .stars-2{
+width: 40%;
+z-index: 5;
+}
+.ajaxful-rating .stars-3{
+width: 60%;
+z-index: 4;
+}
+.ajaxful-rating .stars-4{
+width: 80%;
+z-index: 3;
+}
+.ajaxful-rating .stars-5{
+width: 100%;
+z-index: 2;
+}
+*/
+.ajaxful-rating .current-rating{
+    z-index: 1;
+    background-position: left center;
+}
+
+/* smaller star */
+.small-star{
+    /*width: 50px; this is setted dynamically */
+    height: 10px;
+}
+.small-star,
+.small-star a:hover,
+.small-star a:active,
+.small-star a:focus,
+.small-star .current-rating{
+    background-image: url(/images/ajaxful_rating/star_small.png);
+    line-height: 10px;
+    height: 10px;
+}

data/init.rb

@@ -0,0 +1 @@
+require 'ajaxful_rating'

data/lib/ajaxful_rating.rb

@@ -0,0 +1,2 @@
+require 'ajaxful_rating_model'
+require 'ajaxful_rating_helper'

data/lib/ajaxful_rating_helper.rb

@@ -0,0 +1,174 @@
+module AjaxfulRating # :nodoc:
+  module Helper
+    class MissingRateRoute < StandardError
+      def to_s
+        "Add :member => {:rate => :post} to your routes, or specify a custom url in the options."
+      end
+    end
+  
+    # Generates the stars list to submit a rate.
+    # 
+    # It accepts the next options:
+    # * <tt>:class</tt> CSS class for the ul. Default is 'ajaxful-rating'.
+    # * <tt>:link_class_prefix</tt> Prefix for the li a CSS class. Default is 'stars'.
+    # * <tt>:small_stars</tt> Set this param to true to display smaller images. Default is false.
+    # * <tt>:small_star_class</tt> CSS class for the list when using small images. Default is 'small-stars'.
+    # * <tt>:html</tt> Hash of options to customise the ul tag.
+    # * <tt>:remote_options</tt> Hash of options for the link_to_remote function.
+    # Default is {:method => :post, :url => rate_rateablemodel_path(rateable)}.
+    # * <tt>:wrap</tt> Whether the star list is wrapped within a div tag or not. This is useful when page updating. Default is true.
+    # 
+    # Example:
+    #   <%= ratings_for @article %>
+    #   # => Will produce something like:
+    #   <ul class="ajaxful-rating">
+    #     <li class="current-rating" style="width: 60%;">Currently 3/5 stars</li>
+    #     <li><%= link_to_remote 1, :url => rate_article_path(@article, :stars => 1), :method => :post, :html => {:class => 'stars-1', :title => '1 star out of 5'} %></li>
+    #     <li><%= link_to_remote 2, :url => rate_article_path(@article, :stars => 2), :method => :post, :html => {:class => 'stars-2', :title => '2 stars out of 5'} %></li>
+    #     <li><%= link_to_remote 3, :url => rate_article_path(@article, :stars => 3), :method => :post, :html => {:class => 'stars-3', :title => '3 stars out of 5'} %></li>
+    #     <li><%= link_to_remote 4, :url => rate_article_path(@article, :stars => 4), :method => :post, :html => {:class => 'stars-4', :title => '4 stars out of 5'} %></li>
+    #     <li><%= link_to_remote 5, :url => rate_article_path(@article, :stars => 5), :method => :post, :html => {:class => 'stars-5', :title => '5 stars out of 5'} %></li>
+    #   </ul>
+    #   
+    # It will try to use the method <tt>current_user</tt> as the user instance. You can specify a custom instance in the second parameter
+    # or pass <tt>:static</tt> to leave the list of stars static.
+    # 
+    # Example:
+    #   <%= ratings_for @article, @user, :small_stars => true %>
+    #   # => Will use @user instead <tt>current_user</tt>
+    #   
+    #   <%= ratings_for @article, :static, :small_stars => true %>
+    #   # => Will produce a static list of stars showing the current rating average for @article.
+    #   
+    # The user passed here will *not* be the one who submits the rate. It will be used only for the display behavior of the stars.
+    # Like for example, if there is a user logged in or if the current logged in user is able to submit a rate depending on the
+    # configuration (accepts update of rates, etc).
+    # 
+    # So to actually set the user who will rate the model you need to do it in your controller:
+    # 
+    #   # controller
+    #   def rate
+    #     @article = Article.find(params[:id])
+    #     @article.rate(params[:stars], current_user) # or any user instance
+    #     # update page, etc.
+    #   end
+    # 
+    # I18n:
+    # 
+    # You can translate the title of the images (the tool tip that shows when the mouse is over) and the 'Currently x/x stars'
+    # string by setting these keys on your translation hash:
+    # 
+    #   ajaxful_rating:
+    #     stars:
+    #       current_average: "Current rating: {{average}}/{{max}}"
+    #       title:
+    #         one: 1 star out of {{total}}
+    #         other: "{{count}} stars out of {{total}}"
+    def ratings_for(rateable, *args)
+      user = extract_options(rateable, *args)
+      ajaxful_styles << %Q(
+      .#{options[:class]} { width: #{rateable.class.max_rate_value * 25}px; }
+      .#{options[:small_star_class]} { width: #{rateable.class.max_rate_value * 10}px; }
+      )
+      width = (rateable.rate_average(true, options[:dimension]) / rateable.class.max_rate_value.to_f) * 100
+      ul = content_tag(:ul, options[:html]) do
+        Range.new(1, rateable.class.max_rate_value).collect do |i|
+          build_star rateable, user, i
+        end.insert(0, content_tag(:li, current_average(rateable),
+            :class => 'current-rating', :style => "width:#{width}%"))
+      end
+      if options[:wrap]
+        content_tag(:div, ul, :id => "ajaxful-rating-#{!options[:dimension].blank? ?
+          "#{options[:dimension]}-" : ''}#{rateable.class.name.downcase}-#{rateable.id}")
+      else
+        ul
+      end
+    end
+  
+    # Call this method <strong>within head tags</strong> of the main layout to yield the dynamic styles.
+    # It will include the necessary stlyesheet and output the dynamic CSS.
+    #
+    # Example:
+    #   <head>
+    #     <%= ajaxful_rating_style %>
+    #   </head>
+    def ajaxful_rating_style
+      stylesheet_link_tag('ajaxful_rating') + content_tag(:style, ajaxful_styles,
+        :type => 'text/css') unless ajaxful_styles.blank?
+    end
+  
+    private
+  
+    # Builds a star
+    def build_star(rateable, user, i)
+      a_class = "#{options[:link_class_prefix]}-#{i}"
+      ajaxful_styles << %Q(
+        .#{options[:class]} .#{a_class}{
+            width: #{(i / rateable.class.max_rate_value.to_f) * 100}%;
+            z-index: #{rateable.class.max_rate_value + 2 - i};
+        }
+      )
+      rated = rateable.rated_by?(user, options[:dimension]) if user
+      star = if user && ((rated && rateable.class.options[:allow_update]) || !rated)
+        link_to_remote(i, build_remote_options({:class => a_class, :title => pluralize_title(i, rateable.class.max_rate_value)}, i))
+      else
+        content_tag(:span, i, :class => a_class, :title => current_average(rateable))
+      end
+      content_tag(:li, star)
+    end
+  
+    # Default options for the helper.
+    def options
+      @options ||= {
+        :wrap => true,
+        :class => 'ajaxful-rating',
+        :link_class_prefix => :stars,
+        :small_stars => false,
+        :small_star_class => 'small-star',
+        :html => {},
+        :remote_options => {:method => :post}
+      }
+    end
+  
+    # Builds the proper title for the star.
+    def pluralize_title(current, max)
+      (current == 1) ? I18n.t('ajaxful_rating.stars.title.one', :max => max, :default => "1 star out of {{max}}") :
+        I18n.t('ajaxful_rating.stars.title.other', :count => current, :max => max, :default => "{{count}} stars out of {{max}}")
+    end
+    
+    # Returns the current average string.
+    def current_average(rateable)
+      I18n.t('ajaxful_rating.stars.current_average', :average => rateable.rate_average(true, options[:dimension]),
+        :max => rateable.class.max_rate_value, :default => "Current rating: {{average}}/{{max}}")
+    end
+  
+    # Temporary instance to hold dynamic styles.
+    def ajaxful_styles
+      @ajaxful_styles ||= ''
+    end
+  
+    # Builds the default options for the link_to_remote function.
+    def build_remote_options(html, i)
+      options[:remote_options].reverse_merge(:html => html).merge(
+        :url => "#{options[:remote_options][:url]}?#{{:stars => i, :dimension => options[:dimension]}.to_query}")
+    end
+  
+    # Extracts the hash options and returns the user instance.
+    def extract_options(rateable, *args)
+      user = if args.first.class.name == rateable.class.user_class_name.classify
+        args.shift
+      elsif args.first != :static
+        current_user if respond_to?(:current_user)
+      end
+      options.merge!(args.last) if !args.empty? && args.last.is_a?(Hash)
+      options[:remote_options][:url] ||= respond_to?(url = "rate_#{rateable.class.name.downcase}_path") ?
+        send(url, rateable) : raise(MissingRateRoute)
+      options[:html].reverse_merge!(:class => "#{options[:class]} #{options[:small_star_class] if options[:small_stars]}")
+      user
+    end
+  end
+end
+
+class ActionView::Base
+  include AjaxfulRating::Helper
+end

data/lib/ajaxful_rating_model.rb

@@ -0,0 +1,223 @@
+module AjaxfulRating # :nodoc:
+  class AlreadyRatedError < StandardError
+    def to_s
+      "Model has already been rated by this user. To allow update of ratings pass :allow_update => true to the ajaxful_rateable call."
+    end
+  end
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    attr_reader :options
+
+    # Extends the model to be easy ajaxly rateable.
+    #
+    # Options:
+    # * <tt>:stars</tt> Max number of stars that can be submitted.
+    # * <tt>:allow_update</tt> Set to true if you want users to be able to update their votes.
+    # * <tt>:cache_column</tt> Name of the column for storing the cached rating average.
+    #
+    # Example:
+    #   class Article < ActiveRecord::Base
+    #     ajaxful_rateable :stars => 10, :cache_column => :custom_column
+    #   end
+    def ajaxful_rateable(options = {})
+      has_many :rates_without_dimension, :as => :rateable, :class_name => 'Rate',
+        :dependent => :destroy, :conditions => {:dimension => nil}
+
+      
+      options[:dimensions].each do |dimension|
+        has_many "#{dimension}_rates", :dependent => :destroy,
+          :conditions => {:dimension => dimension.to_s}, :class_name => 'Rate', :as => :rateable
+      end if options[:dimensions].is_a?(Array)
+
+      @options = options.reverse_merge(
+        :stars => 5,
+        :allow_update => true,
+        :cache_column => :rating_average
+      )
+      include AjaxfulRating::InstanceMethods
+      extend AjaxfulRating::SingletonMethods
+    end
+
+    # Makes the association between user and Rate model.
+    def ajaxful_rater(options = {})
+      has_many :rates, options
+    end
+
+    # Maximum value accepted when rating the model. Default is 5.
+    #
+    # Change it by passing the :stars option to +ajaxful_rateable+
+    #
+    #   ajaxful_rateable :stars => 10
+    def max_rate_value
+      options[:stars]
+    end
+  end
+
+  # Instance methods for the rateable object.
+  module InstanceMethods
+
+    # Submits a new rate. Accepts a hash of tipical Ajax request.
+    #
+    # Example:
+    #   # Articles Controller
+    #   def rate
+    #     @article = Article.find(params[:id])
+    #     @article.rate(params[:stars], current_user, params[:dimension])
+    #     # some page update here ...
+    #   end
+    def rate(stars, user, dimension = nil)
+      return false if (stars.to_i > self.class.max_rate_value)
+      raise AlreadyRatedError if (!self.class.options[:allow_update] && rated_by?(user, dimension))
+
+      rate = (self.class.options[:allow_update] && rated_by?(user, dimension)) ?
+        rate_by(user, dimension) : rates(dimension).build
+      rate.stars = stars
+      if user.respond_to?(:rates)
+        user.rates << rate
+      else
+        rate.send "#{self.class.user_class_name}_id=", user.id
+      end if rate.new_record?
+      rate.save!
+      self.update_cached_average(dimension)
+    end
+
+    # Returns an array with all users that have rated this object.
+    def raters
+      eval(self.class.user_class_name.classify).find_by_sql(
+        ["SELECT DISTINCT u.* FROM #{self.class.user_class_name.pluralize} u INNER JOIN rates r ON " +
+            "u.[id] = r.[#{self.class.user_class_name}_id] WHERE r.[rateable_id] = ? AND r.[rateable_type] = ?",
+          id, self.class.name]
+      )
+    end
+
+    # Finds the rate made by the user if he/she has already voted.
+    def rate_by(user, dimension = nil)
+      filter = "find_by_#{self.class.user_class_name}_id"
+      rates(dimension).send filter, user
+    end
+
+    # Return true if the user has rated the object, otherwise false
+    def rated_by?(user, dimension = nil)
+      !rate_by(user, dimension).nil?
+    end
+
+    # Instance's total rates.
+    def total_rates(dimension = nil)
+      rates(dimension).size
+    end
+
+    # Total sum of the rates.
+    def rates_sum(dimension = nil)
+      rates(dimension).sum(:stars)
+    end
+
+    # Rating average for the object.
+    #
+    # Pass false as param to force the calculation if you are caching it.
+    def rate_average(cached = true, dimension = nil)
+      avg = if cached && self.class.caching_average?(dimension)
+        send(caching_column_name(dimension)).to_f
+      else
+        self.rates_sum(dimension).to_f / self.total_rates(dimension).to_f
+      end
+      avg.nan? ? 0.0 : avg
+    end
+
+    # Overrides the default +rates+ method and returns the propper array
+    # for the dimension passed.
+    #
+    # It may works as an alias for +dimension_rates+ methods.
+    def rates(dimension = nil)
+      unless dimension.blank?
+        send("#{dimension}_rates")
+      else
+        rates_without_dimension
+      end
+    end
+
+    # Returns the name of the cache column for the passed dimension.
+    def caching_column_name(dimension = nil)
+      self.class.caching_column_name(dimension)
+    end
+
+    # Updates the cached average column in the rateable model.
+    def update_cached_average(dimension = nil)
+      if self.class.caching_average?(dimension)
+        rates(:refresh).size if self.respond_to?(:rates_count)
+        send("#{caching_column_name(dimension)}=", self.rate_average(false, dimension))
+        save!
+      end
+    end
+  end
+
+  module SingletonMethods
+
+    # Name of the class for the user model.
+    def user_class_name
+      @@user_class_name ||= Rate.column_names.find do |c|
+        u = c.scan(/(\w+)_id$/).flatten.first
+        break u if u && u != 'rateable'
+      end
+    end
+
+    # Finds all rateable objects rated by the +user+.
+    def find_rated_by(user)
+      find_statement(:user_id, user.id)
+    end
+
+    # Finds all rateable objects rated with +stars+.
+    def find_rated_with(stars)
+      find_statement(:stars, stars)
+    end
+
+    # Finds the rateable object with the highest rate average.
+    def find_most_popular(dimension = nil)
+      all.sort_by { |o| o.rate_average(true, dimension) }.last
+    end
+
+    # Finds the rateable object with the lowest rate average.
+    def find_less_popular(dimension = nil)
+      all.sort_by { |o| o.rate_average(true, dimension) }.first
+    end
+
+    # Finds rateable objects by Rate's attribute.
+    def find_statement(attr_name, attr_value)
+      rateable = self.base_class.name
+      sql = sanitize_sql(["SELECT DISTINCT r2.* FROM rates r1 INNER JOIN " +
+            "#{rateable.constantize.table_name} r2 ON r1.rateable_id = r2.id " +
+            "WHERE (r1.[rateable_type] = ? AND r1.[#{attr_name}] = ?)",
+          rateable, attr_value])
+      find_by_sql(sql)
+    end
+
+    # Indicates if the rateable model is able to cache the rate average.
+    #
+    # Include a column named +rating_average+ in your rateable model with
+    # default null, as decimal:
+    #
+    #   t.decimal :rating_average, :precision => 3, :scale => 1, :default => 0
+    #
+    # To customize the name of the column specify the option <tt>:cache_column</tt> to ajaxful_rateable
+    #
+    #   ajaxful_rateable :cache_column => :my_custom_column
+    #
+    def caching_average?(dimension = nil)
+      column_names.include?(caching_column_name(dimension))
+    end
+
+    # Returns the name of the cache column for the passed dimension.
+    def caching_column_name(dimension = nil)
+      name = options[:cache_column].to_s
+      name += "_#{dimension.to_s.underscore}" unless dimension.blank?
+      name
+    end
+  end
+end
+
+class ActiveRecord::Base
+  include AjaxfulRating
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: edgarjs-ajaxful_rating
+version: !ruby/object:Gem::Version 
+  version: 2.1.0
+platform: ruby
+authors: 
+- Edgar J. Suarez
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-25 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Provides a simple way to add rating functionality to your application.
+email: e@dgar.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGELOG
+- lib/ajaxful_rating.rb
+- lib/ajaxful_rating_helper.rb
+- lib/ajaxful_rating_model.rb
+- README.textile
+files: 
+- CHANGELOG
+- generators/ajaxful_rating/ajaxful_rating_generator.rb
+- generators/ajaxful_rating/templates/images/star.png
+- generators/ajaxful_rating/templates/images/star_small.png
+- generators/ajaxful_rating/templates/migration.rb
+- generators/ajaxful_rating/templates/model.rb
+- generators/ajaxful_rating/templates/style.css
+- generators/ajaxful_rating/USAGE
+- init.rb
+- lib/ajaxful_rating.rb
+- lib/ajaxful_rating_helper.rb
+- lib/ajaxful_rating_model.rb
+- Manifest
+- Rakefile
+- README.textile
+- ajaxful_rating.gemspec
+has_rdoc: false
+homepage: http://github.com/edgarjs/ajaxful-rating
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Ajaxful_rating
+- --main
+- README.textile
+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: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: ajaxful_rating
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 3
+summary: Provides a simple way to add rating functionality to your application.
+test_files: []
+