ips.ui.rating

Description

The Rating widget takes a group of radio controls with numerical values, and replaces them with clickable stars so that users can indicate a rating value.

Example

@todo

Usage

To use the rating widget, your HTML should contain the following structure:

<span data-ipsRating>
	<input type="radio" name="ratingValue" id="ratingValue_1" value="1"> <label for="ratingValue_1">1</label>
	<input type="radio" name="ratingValue" id="ratingValue_2" value="2"> <label for="ratingValue_2">2</label>			
	<input type="radio" name="ratingValue" id="ratingValue_3" value="3"> <label for="ratingValue_3">3</label>			
	<input type="radio" name="ratingValue" id="ratingValue_4" value="4"> <label for="ratingValue_4">4</label>			
	<input type="radio" name="ratingValue" id="ratingValue_5" value="5"> <label for="ratingValue_5">5</label>
</span>

The field name attributes, IDs and labels are not fixed; they can be anything. The radio values, however, should be numeric and in ascending order.

Any number of stars is supported - simply include the correct number of radio controls with the relevant values.

Options

url
(String; optional)

If a URL is provided, it will be called via AJAX when the user clicks a star to choose a rating. The rating parameter will contain the selected value.

changeRate
(Boolean; optional; default true)

Specifies whether the user can choose a new rating, if they have already rated the item.

canRate
(Boolean; optional; default true)

Determines whether the user can select a rating in the widget.

size
(Boolean; optional)

If specified, applies an additional ipsRating_ size class to the rating stars to control their size. Supported values: small, large, veryLarge.

Events emitted by ips.ui.rating

Events are emitted on the rating wrapper.

ratingSaved

Triggered when the user selects a rating. If the url option is used, this will be triggered after the URL is successfully pinged. It will not be triggered if the URL fails.

Event data:

• value
  Numeric value of the chosen rating

ratingFailed

Triggered when the url option is used and pinging the provided URL fails.

Event data:

• value
  Numeric value of the chosen rating