WinJS.UI.Rating object
.png)
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 |
|---|---|---|
Read/write |
Gets or sets the average rating. |
|
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. |
|
Read-only |
Gets the DOM element that hosts the Rating. |
|
Read/write |
Gets or sets whether control lets the user clear the rating. |
|
Read/write |
Gets or sets the maximum possible rating value. |
|
Read/write |
Gets or sets a set of descriptions to show for rating values in the tooltip. |
|
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: Styles empty stars when the Rating control shows the average rating. |
Average full stars |
Selector: Styles full stars when the Rating control shows the average rating. |
Disabled empty stars |
Selector: Styles empty stars when the Rating control is disabled. |
Disabled full stars |
Selector: Styles full stars when the Rating control is disabled. |
Tentative empty stars |
Selector: Styles empty stars when the Rating control shows the tentative rating. |
Tentative full stars |
Selector: Styles full stars when the Rating control shows the tentative rating. |
User empty stars |
Selector: Styles empty stars when the Rating control shows the user's rating. |
User full stars |
Selector: 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 |