evolutionStarRating jQuery Plugin

Ben Tiedt — Tue, 19 Nov 2019 20:29:22 GMT

Current Revision posted to API Documentation by Ben Tiedt on 11/19/2019 20:29:22

jQuery.fn.evolutionStarRating

This plugin supports rendering a rating value as stars, along with allowing the user to select a new rating.

Usage

$('SELECTOR').evolutionStarRating(options)

where 'SELECTOR' is a span.

Options

value: (number) initial value to render
- default 0
maxRating: (number) number of stars to render
- default 5
imagesPathUrl: (string) path to star images with a trailing slash.
useHalfStars: (bool) whether or not to support halves
- default false
starClass: class to apply to stars
- default 'rating'
overClass: css class to apply to a star when mouse is over it
- default 'active'
readOnlyClass: css class to apply to a star it is read-only
- default 'readonly'
titles: array of string titles to use for stars
- default ['Terrible','Poor','Fair','Average','Good','Excellent']
isReadOnly: (bool) read only status
allowMultipleSelections: (bool) whether to allow multiple selections
starElement: (string) type of element to render default: img
onRate: (function) callback function when a selection is made. is passed selected value.

Methods

val

Returns (and sets if passed a second optional value) the current value of the rating

// get the value
var value = $('SELECTOR').evolutionStarRating('val');

// set the value
$('SELECTOR').evolutionStarRating('val', .5);

readOnly

Returns (and/or sets if passed a second optional Boolean value) the read-only state of the control

// get the readonly status
$('SELECTOR').evolutionStarRating('readOnly')

// set the readonly status
$('SELECTOR').evolutionStarRating('readOnly', true)

Example

Given the following span to contain a rating control:

<span id="ratingControl" title="Rated Good [4 out of 5]."></span>

The following will initialize a star rating control, using defaults for most options

var ratingControl = $('#ratingControl');
ratingControl.evolutionStarRating({
    value: 4,  //  initial value of rating
    isReadOnly: false,
    onRate: function(value) {
        alert(value + ' selected!');

        // Temporarily disable editing of rating during saving
        ratingControl.evolutionStarRating('readOnly', true);

        // ...perform AJAX-based saving of rating here...

        // After a successful save, turn off the read-only state of the control
        ratingControl.evolutionStarRating('readOnly', false);
    }
});