ajaxful_rating_jquery 2.2.9

data/CHANGELOG

@@ -0,0 +1,54 @@
+== 2.2.9 Sept 30, 2010
+* Released as a separate ajaxful_rating_jquery gem.
+
+== 2.2.8.1 Jul 02, 2010
+* Call html_safe only when it's available.
+
+== 2.2.8 Jun 14, 2010
+* Fix html for <li> marking it as html_safe when using rails_xss plugin
+
+== 2.2.7 Jun 12, 2010
+* Fix generated html marking it as html_safe when using rails_xss plugin
+
+== 2.2.6 May 27, 2010
+* Fix wrapper_dom_id with false values for keys
+
+== 2.2.5 May 21, 2010
+* Fix wrapper_dom_id with empty values
+
+== 2.2.4 April 15, 2010
+* Fix wrapper_dom_id join options
+
+== 2.2.3 March 10, 2010
+* Fix validation of current_user to show linked stars
+
+== 2.2.2 March 9, 2010
+* Fix bug for jRuby
+* Fixed user self relational model to be rater and rateable.
+
+== 2.2.1 March 8, 2010
+* Changed :force_dynamic for its opposite :force_static.
+* Fixed I18n texts.
+* Fixed missed quotes for Rate belongs_to association with User class
+* Detailed wrapper DOM id with passed hash.
+
+== 2.2.0 March 7, 2010
+* Improved model methods and options.
+* Works now with inherited models.
+* Removed HTML and CSS options for helper for sake of simpleness.
+* Renamed helper option :small_stars to :small.
+* Changed whole helper approach. It should work the same as before.
+  (Except for the renamed and removed options)
+* Removed :force_dynamic, you should exclude the helper from cache since it uses
+  authorization.
+* Fixed opened bugs so far.
+
+== 2.1.5 January 28, 2010
+* Renamed options method name to avoid collapse.
+* Removed CSS duplication.
+
+== 2.1.4 January 25, 2010
+* Added option for showing current_user's rate instead of global average
+
+== 2.1.0 July 25, 2009
+* AjaxfulRating is now available as a gem

data/Manifest

@@ -0,0 +1,20 @@
+CHANGELOG
+Manifest
+README.textile
+Rakefile
+generators/ajaxful_rating/USAGE
+generators/ajaxful_rating/ajaxful_rating_generator.rb
+generators/ajaxful_rating/templates/images/star.png
+generators/ajaxful_rating/templates/images/star_medium.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
+init.rb
+lib/ajaxful_rating_jquery.rb
+lib/axr/css_builder.rb
+lib/axr/errors.rb
+lib/axr/helpers.rb
+lib/axr/locale.rb
+lib/axr/model.rb
+lib/axr/stars_builder.rb

data/README.textile

@@ -0,0 +1,237 @@
+h1. Ajaxful Rating
+
+Provides a simple way to add rating functionality to your application. This fork uses jQuery instead of prototype and uses unobtrusive javascript. Currently, it only supports Rails 2.3.x.
+
+!http://s3.amazonaws.com/ember/v9SvvO3rdSkA40e1sXBf8JgpuaWCC0uB_o.png!
+
+h2. Repository
+
+Find it at "github.com/kamui/ajaxful_rating_jquery":http://github.com/kamui/ajaxful_rating_jquery
+
+The original repository is located at "github.com/edgarjs/ajaxful-rating":http://github.com/edgarjs/ajaxful-rating
+
+h2. Demo
+
+I don't have a working demo up of my form but you can see the original version's demo app at "http://github.com/edgarjs/ajaxful-rating_demo_app":http://github.com/edgarjs/ajaxful-rating_demo_app
+Just migrate and run...
+
+Or view it live: "http://axr.heroku.com":http://axr.heroku.com
+
+*******************************************************************
+
+h2. Instructions
+
+h3. Install
+
+To install the gem run the next command:
+
+  @gem install ajaxful_rating_jquery@
+  
+You can configure it in your environment.rb file also:
+
+  @config.gem "ajaxful_rating_jquery"@
+
+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 necessary images, styles, etc.
+
+Example:
+_I suppose you have generated already an authenticated model..._
+
+<pre>
+script/generate authenticated user sessions
+script/generate ajaxful_rating user
+</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>
+class Car < ActiveRecord::Base
+  ajaxful_rateable :stars => 10, :dimensions => [:speed, :beauty, :price]
+end
+</pre>
+
+Then you need to add a call @ajaxful_rater@ in the user model to make your @User@ model able to rate objects.
+
+<pre>
+class User < ActiveRecord::Base
+  ajaxful_rater
+end
+</pre>
+
+Finally, as a mere recommendation 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>
+#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 %>
+</pre>
+
+Or you can specify a custom user instance by passing it as parameter.
+
+<pre>
+<%= ratings_for @article, @user %>
+</pre>
+
+By default ratings_for will display the average user rating. If you would like it to
+display the rating for the current_user, then set the :show_user_rating parameter to true.
+For example:
+
+<pre>
+# To display the rating for the current user (current_user):
+<%= ratings_for @article, :show_user_rating => true %>
+
+# To change the size of the stars you can also specify an optional :size value. If none is set it uses the large size, otherwise you can specify medium or small:
+<%= ratings_for @article, :size => "medium" %>
+
+# To display the rating for the user specified by @user:
+<%= ratings_for @article, @user, :show_user_rating => true %>
+</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>
+<%= ratings_for @article, :url => your_rate_path(@article) %>
+</pre>
+
++h3. Important!
+
+*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 jQ--uery.*
+
+It's also important to note that this call MUST be within your head tags in your layout, as for now it seems to doesn't work with the @content_for@ tag.
+
+<pre>
+  #within the head tags of your layout...
+  <%= javascript_include_tag "http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js" %>
+  <%= ajaxful_rating_style %>
+  <%= ajaxful_rating_script %>
+</pre>
+    
+When a user submits a rating it will call the action in your controller, for
+example (if you added the @rate@ route):
+
+<pre>
+  def rate
+    @car = Car.find(params[:id])
+    @car.rate(params[:stars], current_user, params[:dimension])
+    average = @product.rate_average(true, params[:dimension])
+    width = (average / @car.class.max_stars.to_f) * 100
+    render :json => {:id => @car.wrapper_dom_id(params), :average => average, :width => width}
+  end
+</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>
+class Car < ActiveRecord::Base
+  ajaxful_rateable :dimensions => [:speed, :beauty, :price]
+end
+</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>
+routes.rb:
+map.namespace :admin do |admin|
+  admin.resources :articles, :member => {:rate => :post}
+end
+
+views/admin/articles/show.html.erb
+<%= ratings_for @article, :url => rate_admin_article_path(@article) %>
+</pre>
+
+h3. Cache
+
+To cache the model's rating average add a column named @rating_average@ to your model table:
+
+<pre>
+class AddRatingAverageToArticles < ActiveRecord::Migration
+  def self.up
+    add_column :articles, :rating_average, :decimal, :default => 0, :precision => 6, :scale => 2
+  end
+
+  def self.down
+    remove_column :articles, :rating_average
+  end
+end
+</pre>
+
+If you want to customize the name of the cache column just pass it in the options hash:
+
+<pre>
+class Article < ActiveRecord::Base
+  ajaxful_rateable :cache_column => :my_cached_rating
+end
+</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. Feedback
+
+If you find bugs please open a ticket at "http://github.com/kamui/ajaxful_rating_jquery/issues":http://github.com/kamui/ajaxful_rating_jquery/issues
+
+I'll really appreciate your feedback, please contact me at kamuigt[at]gmail[dot]com
+
+h2. Credits
+
+The original developer of ajaxify_rating, "Edgar J. Suarez":http://github.com/edgarjs
+
+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,15 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('ajaxful_rating_jquery', '2.2.9') do |p|
+  p.summary        = "Add star rating functionality to your Rails 2.3.x application. Requires jQuery."
+  p.description    = "Provides a simple way to add rating functionality to your application. This is a fork of ajaxful_ratings that works with jQuery instead of Prototype and uses unobtrusive javascript instead of link_to_remote."
+  p.url            = "http://github.com/kamui/ajaxful_rating_jquery"
+  p.author         = "Jack Chu, Edgar J. Suarez"
+  p.email          = "kamuigt@gmail.com"
+  p.ignore_pattern = ["tmp/*", "script/*"]
+  p.development_dependencies = []
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/ajaxful_rating_jquery.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{ajaxful_rating_jquery}
+  s.version = "2.2.9"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jack Chu, Edgar J. Suarez"]
+  s.date = %q{2010-09-30}
+  s.description = %q{Provides a simple way to add rating functionality to your application. This is a fork of ajaxful_ratings that works with jQuery instead of Prototype and uses unobtrusive javascript instead of link_to_remote.}
+  s.email = %q{kamuigt@gmail.com}
+  s.extra_rdoc_files = ["CHANGELOG", "README.textile", "lib/ajaxful_rating_jquery.rb", "lib/axr/css_builder.rb", "lib/axr/errors.rb", "lib/axr/helpers.rb", "lib/axr/locale.rb", "lib/axr/model.rb", "lib/axr/stars_builder.rb"]
+  s.files = ["CHANGELOG", "Manifest", "README.textile", "Rakefile", "generators/ajaxful_rating/USAGE", "generators/ajaxful_rating/ajaxful_rating_generator.rb", "generators/ajaxful_rating/templates/images/star.png", "generators/ajaxful_rating/templates/images/star_medium.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", "init.rb", "lib/ajaxful_rating_jquery.rb", "lib/axr/css_builder.rb", "lib/axr/errors.rb", "lib/axr/helpers.rb", "lib/axr/locale.rb", "lib/axr/model.rb", "lib/axr/stars_builder.rb", "ajaxful_rating_jquery.gemspec"]
+  s.homepage = %q{http://github.com/kamui/ajaxful_rating_jquery}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Ajaxful_rating_jquery", "--main", "README.textile"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{ajaxful_rating_jquery}
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Add star rating functionality to your Rails 2.3.x application. Requires jQuery.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= 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,31 @@
+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_medium.png', 'public/images/ajaxful_rating/star_medium.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,18 @@
+class CreateRates < ActiveRecord::Migration
+  def self.up
+    create_table :rates do |t|
+      t.belongs_to :rater
+      t.belongs_to :rateable, :polymorphic => true
+      t.integer :stars, :null => false
+      t.string :dimension
+      t.timestamps
+    end
+    
+    add_index :rates, :rater_id
+    add_index :rates, [:rateable_id, :rateable_type]
+  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 :rater, :class_name => "<%= file_name.classify %>"
+  belongs_to :rateable, :polymorphic => true
+  
+  attr_accessible :rate, :dimension
+end

data/generators/ajaxful_rating/templates/style.css

@@ -0,0 +1,99 @@
+/*
+* 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 .show-value{
+    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 .show-value{
+    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 .show-value{
+    z-index: 1;
+    background-position: left center;
+}
+
+/* medium star */
+.ajaxful-rating.medium{
+    /*width: 54px; this is setted dynamically */
+    height: 18px;
+}
+.ajaxful-rating.medium,
+.ajaxful-rating.medium a:hover,
+.ajaxful-rating.medium a:active,
+.ajaxful-rating.medium a:focus,
+.ajaxful-rating.medium .show-value{
+    background-image: url(/images/ajaxful_rating/star_medium.png);
+    line-height: 18px;
+    height: 18px;
+}
+
+/* smaller star */
+.ajaxful-rating.small{
+    /*width: 50px; this is setted dynamically */
+    height: 10px;
+}
+.ajaxful-rating.small,
+.ajaxful-rating.small a:hover,
+.ajaxful-rating.small a:active,
+.ajaxful-rating.small a:focus,
+.ajaxful-rating.small .show-value{
+    background-image: url(/images/ajaxful_rating/star_small.png);
+    line-height: 10px;
+    height: 10px;
+}

data/init.rb

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

data/lib/ajaxful_rating_jquery.rb

@@ -0,0 +1,6 @@
+require 'axr/locale'
+require 'axr/errors'
+require 'axr/model'
+require 'axr/css_builder'
+require 'axr/stars_builder'
+require 'axr/helpers'

data/lib/axr/css_builder.rb

@@ -0,0 +1,30 @@
+module AjaxfulRating # :nodoc:
+  class CSSBuilder
+    attr_reader :rules
+    
+    def initialize
+      @rules = {}
+    end
+    
+    def rule(selector, attrs)        
+      @rules[selector] = self.class.stringify_properties(attrs) unless @rules.has_key?(selector)
+    end
+    
+    def to_css
+      css = ''
+      @rules.each do |key, value|
+        css << "#{key} {#{value}}\n"
+      end
+      css
+    end
+    
+    def self.stringify_properties(properties)
+      css = ''
+      properties.each do |key, value|
+        value = value.is_a?(Fixnum) || value.is_a?(Float) ? "#{value}px" : value
+        css << "#{key.to_s.underscore.dasherize}: #{value}; "
+      end
+      css
+    end
+  end
+end

data/lib/axr/errors.rb

@@ -0,0 +1,27 @@
+module AjaxfulRating # :nodoc:
+  module Errors
+    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
+    
+    class MissingRateRoute < StandardError
+      def to_s
+        "Add a member route to your routes file for rate with :post method. Or specify a custom url in the options."
+      end
+    end
+    
+    class NoUserSpecified < StandardError
+      def to_s
+        "You need to specify a user instance or create a helper with the name current_user."
+      end
+    end
+    
+    class MissingStarsCSSBuilder < StandardError
+      def to_s
+        "Add a call to ajaxful_rating_style within the head of your layout."
+      end
+    end
+  end
+end

data/lib/axr/helpers.rb

@@ -0,0 +1,150 @@
+module AjaxfulRating # :nodoc:
+  module Helpers
+    include AjaxfulRating::Errors
+    
+    # Outputs the required css file, and the dynamic CSS generated for the
+    # current page.
+    def ajaxful_rating_style
+      @axr_css ||= CSSBuilder.new
+      stylesheet_link_tag('ajaxful_rating') +
+        content_tag(:style, @axr_css.to_css, :type => "text/css")
+    end
+    
+    def ajaxful_rating_script
+      if protect_against_forgery?
+        authenticity_script = %{
+          csrf_param = "authenticity_token";
+          csrf_token = #{form_authenticity_token.inspect};
+
+          // Always send the authenticity_token with ajax
+          $(document).ajaxSend(function(event, request, settings) {
+            if ( settings.type == 'post' ) {
+              settings.data = (settings.data ? settings.data + "&" : "")
+                + encodeURIComponent( csrf_param ) + "=" + encodeURIComponent( csrf_token );
+            }
+          });
+        }
+      end
+
+      %{<script>
+        #{authenticity_script}
+
+        $(document).ready(function(){
+          $('.ajaxful-rating a').bind('click',function(event){
+            event.preventDefault();
+            $.ajax({
+              type: $(this).attr('data-method'),
+              url: $(this).attr('href'),
+              data: {
+                      stars: $(this).attr('data-stars'),
+                      dimension: $(this).attr('data-dimension'),
+                      size: $(this).attr('data-size'),
+                      show_user_rating: $(this).attr('data-show_user_rating')
+                    },
+              success: function(response){
+                $('#' + response.id + ' .show-value').css('width', response.width + '%');
+              }
+            });
+          });
+        });
+      </script>}
+    end
+    
+    def ajaxful_rating_script_prototype
+      %{
+        $$('.ajaxful-rating a').observe('click', rateProduct);
+        
+        function rateProduct(event) {
+          var element = event.element();
+
+          new Ajax.Request(element.readAttribute('data-url'), {
+            method: element.readAttribute('data-method'),
+            parameters: {
+              data-stars: element.readAttribute('data-stars'),
+              data-dimension: element.readAttribute('data-dimension'),
+              data-size: element.readAttribute('data-size'),
+              data-show_user_rating: element.readAttribute('data-show_user_rating')
+            },
+            onSuccess: function(transport, json){
+              alert(json ? Object.inspect(json) : "no JSON object");
+            }
+          });
+        }
+      }
+    end
+    
+    # Generates the stars list to submit a rate.
+    # 
+    # It accepts the next options:
+    # * <tt>:size</tt> Set this param to medium or small to display medium/small images. Default is false.
+    # 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.
+    # * <tt>:show_user_rating</tt> Set to true if you want to display only the current user's rating, instead of the global average.
+    # * <tt>:dimension</tt> The dimension to show the ratings for.
+    # * <tt>:force_static</tt> Force static stars even when you're passing a user instance.
+    # 
+    # Example:
+    #   <%= ratings_for @article, :wrap => false %> # => Will produce something like:
+    #   <ul class="ajaxful-rating">
+    #     <li class="current-rating" style="width: 60%;">3</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, :size => 'small' %>
+    #   # => Will use @user instead <tt>current_user</tt>
+    #   
+    #   <%= ratings_for @article, :static, :size => 'medium' %>
+    #   # => 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
+    # 
+    # By default ratings_for will render the average rating for all users. If however you would like to display the rating for a single user, then set the :show_user_rating option to true.
+    # For example:
+    #
+    #   <%= ratings_for @article, :show_user_rating => true %>
+    # Or
+    #   <%= ratings_for @article, @user, :show_user_rating => true %>
+    #
+    # 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:
+    #     helper:
+    #       global_average: "Global rating average: {{value}} out of {{max}}"
+    #       user_rating: "Your rating: {{value}} out of {{max}}"
+    #       hover: "Rate {{value}} out of {{max}}"    def ratings_for(*args)
+    def ratings_for(*args)
+      @axr_css ||= CSSBuilder.new
+      options = args.extract_options!.symbolize_keys.slice(:size, :url, :method,
+        :wrap, :show_user_rating, :dimension, :force_static, :current_user)
+      rateable = args.shift
+      user = args.shift || (respond_to?(:current_user) ? current_user : raise(NoUserSpecified))
+      StarsBuilder.new(rateable, user, self, @axr_css, options).render
+    end
+  end
+end
+
+class ActionView::Base # :nodoc:
+  include AjaxfulRating::Helpers
+end

data/lib/axr/locale.rb

@@ -0,0 +1,30 @@
+module AjaxfulRating # :nodoc:
+  
+  # Customize messages by adding I18n keys:
+  #
+  #   ajaxful_rating:
+  #     helper:
+  #       global_average: "Global rating average: {{value}} out of {{max}}"
+  #       user_rating: "Your rating: {{value}} out of {{max}}"
+  #       hover: "Rate {{value}} out of {{max}}"
+  module Locale
+    
+    DEFAULTS = {
+      :user_rating => "Your rating: {{value}} out of {{max}}",
+      :global_average => "Global rating average: {{value}} out of {{max}}",
+      :hover => "Rate {{value}} out of {{max}}"
+    }
+    
+    def i18n(key, value = nil)
+      key = if key == :current
+        options[:show_user_rating] ? :user_rating : :global_average
+      else
+        key.to_sym
+      end
+      default = DEFAULTS[key]
+      key = "ajaxful_rating.helper.#{key}"
+      I18n.t(key, :value => (value || show_value),
+        :max => rateable.class.max_stars, :default => default)
+    end
+  end
+end

data/lib/axr/model.rb

@@ -0,0 +1,264 @@
+module AjaxfulRating # :nodoc:
+  include AjaxfulRating::Errors
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    # 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}
+      has_many :raters_without_dimension, :through => :rates_without_dimension, :source => :rater
+      
+      options[:dimensions].each do |dimension|
+        has_many "#{dimension}_rates", :dependent => :destroy,
+          :conditions => {:dimension => dimension.to_s}, :class_name => 'Rate', :as => :rateable
+        has_many "#{dimension}_raters", :through => "#{dimension}_rates", :source => :rater
+      end if options[:dimensions].is_a?(Array)
+
+      class << self
+        def axr_config
+          @axr_config ||= {
+            :stars => 5,
+            :allow_update => true,
+            :cache_column => :rating_average
+          }
+        end
+        
+        alias_method :ajaxful_rating_options, :axr_config
+      end
+      
+      axr_config.update(options)
+      
+      include AjaxfulRating::InstanceMethods
+      extend AjaxfulRating::SingletonMethods
+    end
+
+    # Makes the association between user and Rate model.
+    def ajaxful_rater(options = {})
+      has_many :ratings_given, options.merge(:class_name => "Rate", :foreign_key => :rater_id)
+    end
+  end
+
+  # Instance methods for the rateable object.
+  module InstanceMethods
+    
+    # Proxy for axr_config singleton method.
+    def axr_config
+      self.class.axr_config
+    end
+
+    # 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_stars)
+      raise AlreadyRatedError if (!self.class.axr_config[:allow_update] && rated_by?(user, dimension))
+
+      rate = if self.class.axr_config[:allow_update] && rated_by?(user, dimension)
+        rate_by(user, dimension)
+      else
+        returning rates(dimension).build do |r|
+          r.rater = user
+        end
+      end
+      rate.stars = stars
+      rate.save!
+      self.update_cached_average(dimension)
+    end
+    
+    # Builds the DOM id attribute for the wrapper in view.
+    def wrapper_dom_id(options = {})
+      options = options.symbolize_keys.slice(:size, :dimension)
+      options = options.select { |k, v| v.present? or (v == false) }.map do |k, v|
+        if k == :dimension
+          v.to_s
+        else
+          v.to_s == 'true' ? k.to_s : "no-#{k}"
+        end
+      end
+      options.unshift("ajaxful_rating")
+      ApplicationController.helpers.dom_id(self, options.sort.join('_'))
+    end
+
+    # Returns an array with the users that have rated this object for the
+    # passed dimension.
+    #
+    # It may works as an alias for +dimension_raters+ methods.
+    def raters(dimension = nil)
+      sql = "SELECT DISTINCT u.* FROM #{self.class.user_class.table_name} u "\
+        "INNER JOIN rates r ON u.id = r.rater_id WHERE "
+      
+      sql << self.class.send(:sanitize_sql_for_conditions, {
+        :rateable_id => id,
+        :rateable_type => self.class.base_class.name,
+        :dimension => (dimension.to_s if dimension)
+      }, 'r')
+      
+      self.class.user_class.find_by_sql(sql)
+    end
+
+    # Finds the rate made by the user if he/she has already voted.
+    def rate_by(user, dimension = nil)
+      rates(dimension).find_by_rater_id(user.id)
+    end
+
+    # Return true if the user has rated the object, otherwise false
+    def rated_by?(user, dimension = nil)
+      !rate_by(user, dimension).nil?
+    end
+    
+    # Returns whether or not the user can rate this object.
+    # Based on if the user has already rated the object or the
+    # :allow_update option is enabled.
+    def can_rate_by?(user, dimension = nil)
+      !rated_by?(user, dimension) || self.class.axr_config[:allow_update]
+    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)
+        update_attribute caching_column_name(dimension), self.rate_average(false, dimension)
+      end
+    end
+  end
+
+  module SingletonMethods
+    
+    # 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_stars
+      axr_config[:stars]
+    end
+
+    # Name of the class for the user model.
+    def user_class_name
+      Rate.reflect_on_association(:rater).options[:class_name]
+    end
+    
+    # Gets the user's class
+    def user_class
+      user_class_name.constantize
+    end
+
+    # Finds all rateable objects rated by the +user+.
+    def find_rated_by(user, dimension = nil)
+      find_statement(:rater_id, user.id, dimension)
+    end
+
+    # Finds all rateable objects rated with +stars+.
+    def find_rated_with(stars, dimension = nil)
+      find_statement(:stars, stars, dimension)
+    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, dimension = nil)
+      sql = "SELECT DISTINCT r2.* FROM rates r1 INNER JOIN "\
+        "#{self.base_class.table_name} r2 ON r1.rateable_id = r2.id WHERE "
+      
+      sql << sanitize_sql_for_conditions({
+        :rateable_type => self.base_class.name,
+        attr_name => attr_value,
+        :dimension => (dimension.to_s if dimension)
+      }, 'r1')
+      
+      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 = axr_config[:cache_column].to_s
+      name += "_#{dimension.to_s.underscore}" unless dimension.blank?
+      name
+    end
+  end
+end
+
+class ActiveRecord::Base
+  include AjaxfulRating
+end

data/lib/axr/stars_builder.rb

@@ -0,0 +1,112 @@
+module AjaxfulRating # :nodoc:
+  class StarsBuilder # :nodoc:
+    include AjaxfulRating::Locale
+    
+    attr_reader :rateable, :user, :options
+    
+    def initialize(rateable, user_or_static, template, css_builder, options = {})
+      @user = user_or_static unless user_or_static == :static
+      @rateable, @template, @css_builder = rateable, template, css_builder
+      apply_stars_builder_options!(options)
+    end
+    
+    def show_value
+      if options[:show_user_rating]
+        rate = rateable.rate_by(user, options[:dimension]) if user
+        rate ? rate.stars : 0
+      else
+        rateable.rate_average(true, options[:dimension])
+      end
+    end
+    
+    def render
+      options[:wrap] ? wrapper_tag : ratings_tag
+    end
+    
+    private
+    
+    def apply_stars_builder_options!(options)
+      @options = {
+        :url => nil,
+        :method => :post,
+        :wrap => true,
+        :size => nil,
+        :show_user_rating => false,
+        :force_static => false,
+        :current_user => (@template.current_user if @template.respond_to?(:current_user))
+      }.merge(options)
+      
+      @options[:show_user_rating] = @options[:show_user_rating].to_s == 'true'
+      @options[:wrap] = @options[:wrap].to_s == 'true'
+      
+      if @options[:url].nil?
+        rateable_name = ActionController::RecordIdentifier.singular_class_name(rateable)
+        url = "rate_#{rateable_name}_path"
+        if @template.respond_to?(url)
+          @options[:url] = @template.send(url, rateable)
+        else
+          raise(MissingRateRoute)
+        end
+      end
+    end
+    
+    def ratings_tag
+      stars = []
+      width = (show_value / rateable.class.max_stars.to_f) * 100
+      li_class = "axr-#{show_value}-#{rateable.class.max_stars}".gsub('.', '_')
+      @css_builder.rule('.ajaxful-rating', :width => (rateable.class.max_stars * 25))
+      @css_builder.rule('.ajaxful-rating.medium',
+        :width => (rateable.class.max_stars * 18)) if options[:size] == 'medium'
+      @css_builder.rule('.ajaxful-rating.small',
+        :width => (rateable.class.max_stars * 10)) if options[:size] == 'small'
+      
+      stars << @template.content_tag(:li, i18n(:current), :class => "show-value",
+        :style => "width: #{width}%")
+      stars += (1..rateable.class.max_stars).map do |i|
+        star_tag(i)
+      end
+      if options[:size] == 'small'
+        size = ' small'
+      elsif options[:size] == 'medium'
+        size = ' medium'
+      end
+      # When using rails_xss plugin, it needs to render as HTML
+      @template.content_tag(:ul, stars.join.try(:html_safe), :class => "ajaxful-rating#{size}")
+    end
+    
+    def star_tag(value)
+      already_rated = rateable.rated_by?(user, options[:dimension]) if user
+      css_class = "stars-#{value}"
+      @css_builder.rule(".ajaxful-rating .#{css_class}", {
+        :width => "#{(value / rateable.class.max_stars.to_f) * 100}%",
+        :zIndex => (rateable.class.max_stars + 2 - value).to_s
+      })
+      @template.content_tag(:li) do
+        if !options[:force_static] && (user && options[:current_user] == user &&
+          (!already_rated || rateable.axr_config[:allow_update]))
+          link_star_tag(value, css_class)
+        else
+          @template.content_tag(:span, show_value, :class => css_class, :title => i18n(:current))
+        end
+      end
+    end
+    
+    def link_star_tag(value, css_class)
+      html = {
+        :"data-method" => options[:method],
+        :"data-stars" => value,
+        :"data-dimension" => options[:dimension],
+        :"data-size" => options[:size],
+        :"data-show_user_rating" => options[:show_user_rating],
+        :class => css_class,
+        :title => i18n(:hover, value)
+      }
+      @template.link_to(value, options[:url], html)
+    end
+    
+    def wrapper_tag
+      @template.content_tag(:div, ratings_tag, :class => "ajaxful-rating-wrapper",
+        :id => rateable.wrapper_dom_id(options))
+    end
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification 
+name: ajaxful_rating_jquery
+version: !ruby/object:Gem::Version 
+  hash: 21
+  prerelease: false
+  segments: 
+  - 2
+  - 2
+  - 9
+  version: 2.2.9
+platform: ruby
+authors: 
+- Jack Chu, Edgar J. Suarez
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-30 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Provides a simple way to add rating functionality to your application. This is a fork of ajaxful_ratings that works with jQuery instead of Prototype and uses unobtrusive javascript instead of link_to_remote.
+email: kamuigt@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGELOG
+- README.textile
+- lib/ajaxful_rating_jquery.rb
+- lib/axr/css_builder.rb
+- lib/axr/errors.rb
+- lib/axr/helpers.rb
+- lib/axr/locale.rb
+- lib/axr/model.rb
+- lib/axr/stars_builder.rb
+files: 
+- CHANGELOG
+- Manifest
+- README.textile
+- Rakefile
+- generators/ajaxful_rating/USAGE
+- generators/ajaxful_rating/ajaxful_rating_generator.rb
+- generators/ajaxful_rating/templates/images/star.png
+- generators/ajaxful_rating/templates/images/star_medium.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
+- init.rb
+- lib/ajaxful_rating_jquery.rb
+- lib/axr/css_builder.rb
+- lib/axr/errors.rb
+- lib/axr/helpers.rb
+- lib/axr/locale.rb
+- lib/axr/model.rb
+- lib/axr/stars_builder.rb
+- ajaxful_rating_jquery.gemspec
+has_rdoc: true
+homepage: http://github.com/kamui/ajaxful_rating_jquery
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Ajaxful_rating_jquery
+- --main
+- README.textile
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 11
+      segments: 
+      - 1
+      - 2
+      version: "1.2"
+requirements: []
+
+rubyforge_project: ajaxful_rating_jquery
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Add star rating functionality to your Rails 2.3.x application. Requires jQuery.
+test_files: []
+