WinJS.UI.Rating object

Article
01/26/2017

Lets the user rate something by clicking an icon that represents a rating. The Rating control can display three types of ratings: an average rating, a tentative rating, and the user's rating.

Syntax

<div data-win-control="WinJS.UI.Rating"></div>

var object = new WinJS.UI.Rating(element, options);

Members

The Rating object has these types of members:

Constructors
Events
Methods
Properties

Constructors

The Rating object has these constructors.

Constructor	Description
Rating Constructor	Creates a new Rating.

Events

The Rating object has these events.

Event	Description
oncancel Event	Raised when the user finishes interacting with the rating control without committing a tentative rating.
onchange Event	Raised when the user commits a change to the userRating.
onpreviewchange Event	Raised when the user is choosing a new tentative Rating.

Methods

The Rating object has these methods.

Method	Description
addEventListener Method	Registers an event handler for the specified event.
dispose	Releases resources held by this Rating. Call this method when the Rating is no longer needed. After calling this method, the Rating becomes unusable.
removeEventListener Method	Removes an event handler that the addEventListener method registered.

Properties

The Rating object has these properties.

Property	Access type	Description
averageRating Property	Read/write	Gets or sets the average rating.
disabled	Read/write	Gets or sets whether the control is disabled. When the control is disabled, the user can't specify a new user rating or modify an existing rating.
element Property	Read-only	Gets the DOM element that hosts the Rating.
enableClear Property	Read/write	Gets or sets whether control lets the user clear the rating.
maxRating Property	Read/write	Gets or sets the maximum possible rating value.
tooltipStrings Property	Read/write	Gets or sets a set of descriptions to show for rating values in the tooltip.
userRating Property	Read/write	Gets or sets the user's rating.

Remarks

Styling the Rating control

CSS classes

To customize the Rating, you can define your own styles for these Cascading Style Sheets (CSS) classes (defined by the Windows Library for JavaScript style sheets):

CSS class	Description
win-average	Styles the Rating control when it's displaying the average rating.
win-disabled	Styles the Rating control when it's disabled.
win-empty	Styles the Rating control's empty stars.
win-full	Styles the Rating control's full stars.
win-rating	Styles the entire Rating.
win-star	Styles the Rating control's stars.
win-tentative	Styles the Rating control when it's displaying a tentative rating.
win-user	Styles the Rating control when it's displaying the user's rating.

CSS combinations

Here are some common CSS selector combinations that you can use to style the Rating.

Selector name	Description
Average empty stars	Selector: `.win-star.win-average.win-empty` Styles empty stars when the Rating control shows the average rating.
Average full stars	Selector: `.win-star.win-average.win-full` Styles full stars when the Rating control shows the average rating.
Disabled empty stars	Selector: `.win-star.win-disabled.win-empty` Styles empty stars when the Rating control is disabled.
Disabled full stars	Selector: `.win-star.win-disabled.win-full` Styles full stars when the Rating control is disabled.
Tentative empty stars	Selector: `.win-star.win-tentative.win-empty` Styles empty stars when the Rating control shows the tentative rating.
Tentative full stars	Selector: `.win-star.win-tentative.win-full` Styles full stars when the Rating control shows the tentative rating.
User empty stars	Selector: `.win-star.win-user.win-empty` Styles empty stars when the Rating control shows the user's rating.
User full stars	Selector: `.win-star.win-user.win-full` Styles full stars when the Rating control shows the user's rating.

Here's an example of how to use the "user full stars" combination:

.win-star.win-user.win-full  {
   background-color: red; 
}

Examples

To create a Rating control, create a div element and set the data-win-control property to "WinJS.UI.Rating". Here's an example of how to create a basic rating control.

<div id="ratingControl" data-win-control="WinJS.UI.Rating"></div>

The averageRating property specifies the average rating of the item being rated. (How you determine the average rating for that item is up to you.) If you set the averageRating property, the Rating control displays it until the user selects their own rating. The following example sets the averageRating to 3.4.

<div id="ratingControl" data-win-control="WinJS.UI.Rating"
    data-win-options="{averageRating : 3.4}"></div>

The maxRating property specifies the maximum possible rating. The maximum is 5. The next example sets the maxRating to 7; when the control is displayed, it shows 7 stars instead of 5.

<div id="ratingControl" data-win-control="WinJS.UI.Rating"
    data-win-options="{averageRating : 3.4, maxRating : 7}"></div>

For additional examples, see Quickstart: Adding ratings.

Requirements

Minimum WinJS version	WinJS 1.0
Namespace	WinJS.UI

Partager via