jQuery Star Rating Plugin

What is this?

The Star Rating Plugin is a plugin for the jQuery Javascript library that creates a non-obstrusive star rating control based on a set of radio input boxes.

What does it do?

• It turns a collection of radio boxes into a neat star-rating control.
• It creates the interface based on standard form elements, which means the basic functionality will still be available even if Javascript is disabled.
• NEW (12-Mar-08): In read only mode (using the 'readOnly' option or disabled property), the plugin is a neat way of displaying star-like values without any additional code

How do I use it?

Just add the star class to your radio boxes

<input name="star1" type="radio" class="star"/>
<input name="star1" type="radio" class="star"/>
<input name="star1" type="radio" class="star"/>
<input name="star1" type="radio" class="star"/>
<input name="star1" type="radio" class="star"/>

Use the checked property to specify the initial/default value of the control

<input name="star2" type="radio" class="star"/>
<input name="star2" type="radio" class="star"/>
<input name="star2" type="radio" class="star" checked="checked"/>
<input name="star2" type="radio" class="star"/>
<input name="star2" type="radio" class="star"/>

Use the disabled property to use a control for display purposes only

<input name="star3" type="radio" class="star" disabled="disabled"/>
<input name="star3" type="radio" class="star" disabled="disabled"/>
<input name="star3" type="radio" class="star" disabled="disabled" checked="checked"/>
<input name="star3" type="radio" class="star" disabled="disabled"/>
<input name="star3" type="radio" class="star" disabled="disabled"/>

What about split stars and 'half ratings'???

Use metadata plugin to pass advanced settings to the plugin via the class property.

<input name="adv1" type="radio" class="star {split:4}"/>
<input name="adv1" type="radio" class="star {split:4}"/>
<input name="adv1" type="radio" class="star {split:4}"/>
<input name="adv1" type="radio" class="star {split:4}"/>
<input name="adv1" type="radio" class="star {split:4}" checked="checked"/>
<input name="adv1" type="radio" class="star {split:4}"/>
<input name="adv1" type="radio" class="star {split:4}"/>
<input name="adv1" type="radio" class="star {split:4}"/>

Use custom selector

$(function(){ // wait for document to load
 $('input.wow').rating();
});

<input name="adv2" type="radio" class="wow {split:4}"/>
<input name="adv2" type="radio" class="wow {split:4}"/>
<input name="adv2" type="radio" class="wow {split:4}"/>
<input name="adv2" type="radio" class="wow {split:4}"/>
<input name="adv2" type="radio" class="wow {split:4}" checked="checked"/>
<input name="adv2" type="radio" class="wow {split:4}"/>
<input name="adv2" type="radio" class="wow {split:4}"/>
<input name="adv2" type="radio" class="wow {split:4}"/>

Test Suite

$('.auto-submit-star').rating({
  callback: function(value, link){
    alert(value);
  }
});

$('.hover-star').rating({
  focus: function(value, link){
    var tip = $('#hover-test');
    tip[0].data = tip[0].data || tip.html();
    tip.html(link.title || 'value: '+value);
  },
  blur: function(value, link){
    var tip = $('#hover-test');
    $('#hover-test').html(tip[0].data || '');
  }
});

<input class="star {half:true}"

<input class="star {split:3}"

<input class="star {split:2}"

<input class="star {split:2}"

<input class="star {split:4}"

<input class="star {split:4}"

API

NEW to v3

API methods can be invoked this this:

$(selector).rating(
 'method', // method name
 [] // method arguments (not required)
);

$().rating('select', index / value)

Use this method to set the value (and display) of the star rating control via javascript. It accepts the index of the star you want to select (0 based) or its value (which must be passed as a string.

Example: (values A/B/C/D/E)

$().rating('readOnly', true / false)

Use this method to set the value (and display) of the star rating control via javascript. It accepts the index of the star you want to select (0 based) or its value (which must be passed as a string.

Example: (values 1,2,3...10)

$().rating('disable') / $().rating('enable')

These methods bahve almost exactly as the readOnly method, however they also control whether or not the select value is submitted with the form.

Example: (values 1,2,3...10)

Database Integration

I'm sorry to say that for the time being, it is up to you to create the server-side code that will process the form submission, store it somewhere (like a database) and do stuff with it - such as displaying averages and stop users from voting more than once.

However, here are a few alternatives if you don't feel like getting down and dirty with some good old coding:
http://www.yvoschaap.com/index.php/weblog/css_star_rater_ajax_version/

and
part 1: http://www.komodomedia.com/blog/2005/08/creating-a-star-rater-using-css/
part 2: http://slim.climaxdesigns.com/tutorial.php?section=slim&id=2
part 3: http://slim.climaxdesigns.com/tutorial.php?section=slim&id=3
part 4: http://slim.climaxdesigns.com/tutorial.php?section=slim&id=9

Background Information

As far as I know, this is how it goes...

• It all started with Will Stuckey's jQuery Star Rating Super Interface!
• The original then became the inspiration for Ritesh Agrawal's Simple Star Rating System, which allows for a GMail like star/un-star toggle.
• This was followed by several spin-offs... (one of which is the Half-star rating plugin)
• Then someone at PHPLetter.com modified the plugin to overcome the issues - then plugin was now based on standard form elements, meaning the interface would still work with Javascript disabled making it beautifully downgradable.
• Then I came along and noticed a fundamental flaw with the latter: there could only be one star rating control per page. The rest of the story is what you will see below...
• NEW (12-Mar-08): Then Keith Wood added some very nice functionality to the plugin: option to disable the cancel button, option to make the plugin readOnly and ability to accept any value (other than whole numbers)
• NEW (20-Mar-08): Now supports half-star, third-star, quater-star, etc... Not additional code required. No additional images required.
• NEW (31-Mar-08): Two new events, hover/blur (arguments: [value, linkElement])

Download

This project (and all related files) can also be accessed via its Google Code Project Page.

Full Package:	v3.13 star-rating.zip
	Stay up-to-date! Major updates will be announced on Twitter: @fyneworks
Core Files:	These are the individual required files (already included in the zip package above) jquery.rating.js (packed version: jquery.rating.pack.js) jQuery.Rating.css delete.gif star.gif
jQuery:	jquery-latest.js (see jQuery.com)

Related Downloads

SVN Repository

If you're a major geek or if you really really want to stay up-to-date with with future updates of this plugin, go ahead and plug yourself to the SVN Repository on the official Google Code Project Page.

SVN Checkout:	SVN Checkout Instructions
Browse Online:	Browse Source

Alternative Download - From this website

Just in case it's the end of the world and the Google Code site becomes unavailable, the project files can also be downloaded form this site.
However, please note that this site is updated periodically whereas the Google Code project is kept up-to-date almost instantaneously. If you'd like the very latest version of this plugin you are advised to use the links above and download the files from Google Code - this will ensure the files you download have the very latest features and bug fixes.

Full Package:	v3.13 star-rating.zip
	Stay up-to-date! Major updates will be announced on Twitter: @fyneworks
Core Files:	These are the individual required files (already included in the zip package above) jquery.rating.js (packed version: jquery.rating.pack.js) jQuery.Rating.css delete.gif star.gif
jQuery:	jquery-latest.js (see jQuery.com)

Support

Quick Support Links: Help me! | Report a bug | Suggest new feature

Support for this plugin is available through the jQuery Mailing List. This is a very active list to which many jQuery developers and users subscribe.
Access to the jQuery Mailing List is also available through Nabble Forums and the jQuery Google Group.

WARNING: Support will not be provided via the jQuery Plugins website. If you need help, please direct your questions to the jQuery Mailing List or report an issue on the official Google Code Project Page.

Official Links

• jQuery Plugin Project Page
• Google Code Project Page

Credit

• Diego A. - Author, London SEO Consultant
• Keith Wood - The brain behind v2.1
• Dean Edwards - Author of JS Packer used to compress the plugin
• Will Stuckey, Ritesh Agrawal and everyone else who worked in the previous versions of the plugin - I'm not so good with research...

Attribute this work

License Info

Star Rating Plugin by Fyneworks.com is licensed under the MIT License and the GPL License.

Copyright © 2008 Fyneworks.com Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.