WinJS.UI.Rating object

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

See also

Quickstart: Adding ratings