What is this?
The Star Rating widget is a plugin for the jQuery javascript library that creates a non-obstrusive star rating control based on a set of radio buttons or select option.
What it does?
- It turns a collection of radio boxes / select options 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.
- It gives you the full access to each instance of "stars" created on the page, with an easy to use syntax provided by the jQuery UI core library. See Examples tab for more info.
Quick example with RADIO boxes:
Quick example with SELECT options:
Sample markup:
All examples here contains the markup shown below. The wrapper is used as a scope in Stars() constructor to extract all the radio buttons (select options) and remain it's name and value as a hidden input. Note that all other elements from the wrapper will stay intact.
- <form>
- Rating: <span id="stars-cap"></span>
- <div id="stars-wrapper1">
- <input type="radio" name="newrate" value="1" title="Very poor" />
- <input type="radio" name="newrate" value="2" title="Poor" />
- <input type="radio" name="newrate" value="3" title="Not that bad" />
- <input type="radio" name="newrate" value="4" title="Fair" />
- <input type="radio" name="newrate" value="5" title="Average" checked="checked" />
- <input type="radio" name="newrate" value="6" title="Almost good" />
- <input type="radio" name="newrate" value="7" title="Good" />
- <input type="radio" name="newrate" value="8" title="Very good" />
- <input type="radio" name="newrate" value="9" title="Excellent" />
- <input type="radio" name="newrate" value="10" title="Perfect" />
- </div>
- </form>
- or -
- <form>
- Rating: <span id="stars-cap"></span>
- <div id="stars-wrapper2">
- <select name="selrate">
- <option value="1">Very poor</option>
- <option value="2">Not that bad</option>
- <option value="3">Average</option>
- <option value="4" selected="selected">Good</option>
- <option value="5">Perfect</option>
- </select>
- </div>
- </form>
Usage:
Turning RADIO buttons into star rating type:
- $("#stars-wrapper1").stars();
Turning SELECT box into star rating type:
- $("#stars-wrapper2").stars({
- inputType: "select"
- });
Disabe Stars. Note, it's also possible to pass disabled="disabled" parameter through HTML code instead!
- $("#stars-wrapper1").stars({
- disabled: true
- });
Adding an "onHover" caption element:
- $("#stars-wrapper1").stars({
- captionEl: $("#stars-cap")
- });
Split Stars:
- $("#stars-wrapper1").stars({
- split: 2
- });
Only one vote, please!
- $("#stars-wrapper1").stars({
- oneVoteOnly: true
- });
Select the Stars by ID or Value. Note, to remove selection use "-1" for ID or "cancelValue" for Value
- $("#stars-wrapper1").stars({
- cancelValue: 99 // PS. Omit this line if your cancelValue is 0 (default)
- });
- // and later...
- $("#stars-wrapper1").stars("selectID", -1); // remove selection
- $("#stars-wrapper1").stars("selectID", 0); // select first Star
- $("#stars-wrapper1").stars("select", 99); // remove selection
- $("#stars-wrapper1").stars("select", 1); // select first Star (see element Value in HTML source)
Callback:
I think this is the most common example, where you have two Star controls.
The first one represents an Average rating and is disabled by default,
while the second one is enabled, allowing the user to vote for an item.
In this example I will simply pass the selected value from right to left control, although in "real life",
you will have to submit selected value to the server and then use returned data to set the Stars accordingly.
The callback is fired each time an element is clicked and it has three arguments: Stars instance,
string representing clicked element ("star" or "cancel") and the Value assigned to the clicked element.
- $("#stars-wrapper2").stars({ // already disabled via markup
- inputType: "select",
- split: 2,
- captionEl: $("#stars-wrapper2-cap")
- });
- $("#stars-wrapper1").stars({
- split: 2,
- captionEl: $("#stars-wrapper1-cap"),
- callback: function(ui, type, value){
- $("#stars-wrapper2").stars("select", value);
- $("#stars-wrapper2-red").html(value==ui.options.cancelValue ? "Rating removed" : "Rating saved! ("+value+")").stop().css("opacity", 1).fadeIn(30);
- setTimeout(function(){ $("#stars-wrapper2-red").fadeOut(1000) }, 2000);
- }
- });
More precise "Average" display:
I've been pointed correctly that in previous example, the "Average rating" is rounded to the number of INPUTs only.
Frankly speaking, it wasn't my intention to add support for "Average rating" in this widget,
although I will show you yet another way how to obtain such functionality. This technique is based on two, overlaping DIVs.
NOTE: I removed all the useless stuff from this example - just to show you the rough idea, so it may work a little bit different from what you can see on this page.
Also, the rating counter will automatically reset after 20 votes.
- <!-- example CSS declarations -->
- <style type="text/css">
- .stars-off, .stars-on {
- position: relative;
- height: 16px;
- background: url(jquery.ui.stars.gif) repeat-x 0 -32px;
- }
- .stars-on {
- position: absolute;
- background-position: 0 -48px;
- }
- </style>
- <!-- example DOM -->
- Average: <span id="fake-stars-cap"></span>
- <div id="fake-stars-off" class="stars-off" style="width:160px"><div id="fake-stars-on" class="stars-on"></div></div>
- $("#stars-wrapper1").stars({
- cancelShow: false,
- captionEl: $("#stars-cap"),
- callback: function(ui, type, value)
- {
- $.getJSON("ratings.php", {rate: value}, function(json)
- {
- $("#fake-stars-on").width(Math.round( $("#fake-stars-off").width() / ui.options.items * parseFloat(json.avg) ));
- $("#fake-stars-cap").text(json.avg + " (" + json.votes + ")");
- });
- }
- });
How to retrieve Stars instance (outside of callback function):
Let's say you can't use the callback function, but still need to access the particular Stars instance.
The answer is the jQuery's internal $.data() function.
- $("#stars-wrapper1").stars();
- // Retrieve instance
- var ui = $("#stars-wrapper1").data("stars");
- // Read options
- var currID = ui.options.checked; // Get current ID
- var currValue = ui.options.value; // Get current Value
- var currTitle = ui.options.title; // Get current Title
- var cancValue = ui.options.cancelValue; // Get Cancel value
- // Remove Cancel button
- ui.$cancel.remove();
- // PS. The instance can be also retreived at creation time:
- var ui = $("#stars-wrapper1").stars();
Changelog
- v 3.0 (Apr 20, 2010)
- added support for jQuery 1.4.2 and jQuery UI 1.8
Thanks again for all your kind emails :) - files renamed to follow UI naming convention
- added support for jQuery 1.4.2 and jQuery UI 1.8
- v 2.1 (Jun 9, 2009)
- added Event parameter to callback function
- integration of a "Not Applicable" field
- added support for FORM Reset event
- v 2.0 (May 5, 2009)
- added support for jQuery 1.3.2 and jQuery UI 1.7.1
- v 1.1 (Aug 8, 2008)
- fixed initialization of hidden input value
- v 1.0 (Jul 17, 2008)
- first public release
Contact / Find me
- Email: orkans@gmail.com
- Twitter: orkans
- DeviantART: orkanorkan