Quickstart: adding ratings (HTML)

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Use the Rating control to let the user rate something by clicking an icon that represents a rating. This quickstart shows you how to add a the rating control to your Windows app using JavaScript.

Prerequisites

We assume that you can create a basic Windows app using JavaScript that uses Windows Library for JavaScript controls. For instructions on getting started with WinJS controls, see Quickstart: adding WinJS controls and styles.

Create a ratings control

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>

Note  For the control to be instantiated, your page must include the WinJS JavaScript files and you must call the WinJS.UI.processAll function in your code behind. For more info, see Quickstart: Adding WinJs controls and styles.

Setting the average rating and max rating

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 default 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>

Obtaining the user's rating

When the user picks a rating, it triggers the change event. You can obtain the user's rating by getting the value of the userRating property.

This example uses the start page's activated event handler to add a change event handler to the Rating control. (For more information about the best place to attach events, see Quickstart: Adding controls and handling events.)

(function () {
    "use strict";

    var app = WinJS.Application;

    // This function responds to all application activations.
    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
            // TODO: Initialize your application here.
            WinJS.UI.processAll()
            .done(function () {

                // Get the rating control
                var ratingControl = document.getElementById("ratingControl").winControl;

                ratingControl.addEventListener("change", changeRating);
            });
        }
    };

    app.start();
})();

The example event handler function, changeRating, retrieves the user rating and stores it.

    function changeRating(ev) {
        var ratingControl = ev.target.winControl;
        if (ratingControl) {

            if (ratingControl.userRating != 0) {

                // Put your code here to save user rating and re-calculate average rating.
                WinJS.Application.sessionState.userRating = ratingControl.userRating;

                var appData = Windows.Storage.ApplicationData.current;
                var roamingValues = appData.roamingSettings.values;

                // Write a setting
                roamingValues.insert("userRating", ratingControl.userRating);
            } else {

                // Put your code here to delete user rating.
            }
        }
    }

The next example modifies the activated event handler shown earlier so that it retrieves the stored user rating and uses it to set the Rating control.

(function () {
    "use strict";

    var app = WinJS.Application;

    // This function responds to all application activations.
    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
            // TODO: Initialize your application here.
            WinJS.UI.processAll()
            .done(function () {

                // Get the rating control
                var ratingControl = document.getElementById("ratingControl").winControl;

                // Retrieve stored state info 
                var appData = Windows.Storage.ApplicationData.current;
                var roamingValues = appData.roamingSettings.values;

                // Read a setting
                var currentRating = parseFloat(roamingValues.lookup("userRating"));

                if (currentRating > 0) {
                    ratingControl.userRating = currentRating;
                }

                ratingControl.addEventListener("change", changeRating);
            });
        }
    };

    function changeRating(ev) {
        var ratingControl = ev.target.winControl;
        if (ratingControl) {

            if (ratingControl.userRating != 0) {

                // Put your code here to save user rating and re-calculate average rating.
                WinJS.Application.sessionState.userRating = ratingControl.userRating;

                var appData = Windows.Storage.ApplicationData.current;
                var roamingValues = appData.roamingSettings.values;

                // Write a setting
                roamingValues.insert("userRating", ratingControl.userRating);
            } else {

                // Put your code here to delete user rating.
            }
        }
    }

    app.start();
})();

Summary and next steps

You learned how to create a Rating control and how to store and retrieve its userRating. Next, learn about how to best use the rating control by reading the Guidelines and checklist for rating controls.

Related topics

WinJS.UI.Rating