jQuery Plugins: Multiple File Upload, Star Rating, NEW: CKEditor (old: FCKEditor), Codepress, XML to JSON

# jQuery Star Rating Plugin

v3.13

Find another jQuery plugin:

- Intro
- Demos
- API
- Database Integration
- Background
- Download
- Support
- License

## 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

Test 1 - A blank form

Rating 1: (N/M/Y) Rating 2: (10 - 50) Rating 3: (1 - 7) | Rating 4: (1 - 5) Rating 5: (1 - 5) Rating 6 (readonly): (1 - 5)

Test results:
Results will be displayed here

Test 2 - With defaults ('checked')

Rating 1: (N/M/Y, default M) Rating 2: (10 - 50, default 30) Rating 3: (1 - 7, default 4) | Rating 4: (1 - 5, default 1) Rating 5: (1 - 5, default 5) Rating 6 (readonly): (1 - 5, default 3)

Test results:
Results will be displayed here

Test 3-A - With callback

Rating 1: (1 - 3, default 2)

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

Test results:
Results will be displayed here

Test 3-B - With hover effects

Rating 1: (1 - 3, default 2)
Hover tips will appear in here

    $('.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 || '');
      }
    });

Test results:
Results will be displayed here

Test 4 - Half Stars and Split Stars

Rating 1: (N/M/Y/?)

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

Rating 2: (10 - 60)

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

Rating 3: (0-5.0, default 3.5)

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

Rating 4: (1-6, default 5)

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

Rating 5: (1-20, default 11)

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

Rating 6 (readonly): (1-20, default 13)

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

Test results:
Results will be displayed here

## 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)

By index: eg.: $('input').rating('select',3)
By value: eg.: $('input').rating('select','C')

### $().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)

eg.: $('input').rating('readOnly',true)
eg.: $('input').rating('readOnly',false) or simply $('input').rating('readOnly');

### $().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)

eg.: $('input').rating('disable')
eg.: $('input').rating('enable');

## 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

Related: | Metadata plugin - Used to retrieve inline configuration from class variable Form plugin - Used to submit forms via ajax

## 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

Attribution link: | © Fyneworks.com
HTML Code: |

## 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.

Star Rating Plugin by Fyneworks.com is licensed under the MIT License and the GPL License. | Tested with jQuery 1.4 on IE6, IE7, IE8, FF, Chrome, Opera and Safari