socialforge/lib/plugins/seems_rateable-master/README.md

112 lines
3.1 KiB
Markdown
Raw Normal View History

# SeemsRateable
Star rating gem for Rails application using jQuery plugin <a href="http://www.myjqueryplugins.com/jquery-plugin/jrating">jRating</a>
## Demo
<a href="http://rateable.herokuapp.com/">Demo</a> application, requires to sign up before rating
## Instructions
### Installation
Add this line to your application's Gemfile:
gem 'seems_rateable'
And then execute:
$ bundle
Or install it yourself as:
$ gem install seems_rateable
### Generation
$ rails generate seems_rateable:install
Generator creates migration files, javascript files and initializer
### Prepare
Require javascript files by adding this line to application.js
#application.js
//= require_directory ./rateable
Add <code>seems_rateable</code> to routes.rb file
Include stylesheet adding <code><%= seems_rateable_stylesheet %></code> to your layout header
Also make sure you have an existing <code>current_user</code> helper method
Don't forget to run
$ rake db:migrate
To prepare model add <code> seems_rateable </code> to your rateable model file. You can also pass a hash of options to
customize the functionality
<ul>
<li><code>:dimensions</code>Array of dimensions e.g <code>:dimensions => [:quality, :quantity]</code> </li>
<li><code>:allow_update</code>Allowing user to re-rate his own ratings, default set to false e.g <code>:allow_update=> true</code></li>
</ul>
class Post < ActiveRecord::Base
seems_rateable :allow_update => true, :dimensions => [:quality, :length]
end
To access object's rates use <code>rates</code> method, to get dimension rates pass an argument eg :
@object.rates
@object.rates(:quality)
@object.rates(:quantity)
This also applies to cached average rating e.g
@object.average
@object.average(:quality)
@object.average(:quantity)
And to object's raters e.g
@object.raters
@object.raters(:quality)
@object.raters(:quantity)
To track user's given ratings add <code>seems_rateable_rater</code> to your rater model.
If your rater class is not "User"(e.g "Client" or "Customer") change configuration in initializer generated by this engine.
Now you can access user's ratings by <code>@user.ratings_given</code>
### Usage
To display star rating use helper method <code>rating_for</code> in your view
#index.html.erb
rating_for @post
rating_for @post, :dimension => :quality, :class => 'post', :id => 'list'
rating_for @post, :static => true
You can specify these options :
<ul>
<li><code>:dimension</code>The dimension of the object</li>
<li><code>:static</code>Set to true to display static star rating, default false</li>
<li><code>:class</code>Class of the div, default set to 'rateable'</li>
<li><code>:id</code>ID of the div e.g <code>:id => "info"</code>, default nil</li>
</ul>
To edit the javascript options locate rateable.js file in /app/assets/javascripts/rateable/.
The javascript options are explained directly in the file
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request