This page presents the main Rating widget capabilities. You'll find in this page some useful samples that will help you to use this widget.
Default Behavior
By default, the Rating widget allows users to vote. If you don't provide a stop voting mechanism after first vote, the Rating widget will allow you to vote multiple times. The Rating widget appearance is based on "ratingButton" CSS class which will set the star images.
The first sample shows a rating widget with five stars, meaning that the maximum allowed vote is 5 and the minimum is 1. The stars number defines the voting range. When moving the mouse over the Rating stars, the stars are highlighted by changing their color to green. The widget below has the initial value set on 2.6 and this will be reflected when page loads by displaying two and a half stars collored in yellow.
There are two ways to set the initial value for a Rating widget. You can add the "ratingValue" option in the widget constructor and specify a value for this option. The value you pass for this option will be reflected after the Rating widget finishes to load. For example you can use the "ratingValue" option for a Rating widget that is in read only mode.
The second way to set an initial value for the Rating widget is to extract the value from a input field from page. This input field can have on the "value" attribute a value returned from the server or a value specified by the user. It's mandatory for the input element to have an ID specified because its value will be pass as argument for the "ratingValueElement" option and has to be inside the Rating widget container. The "ratingValueElement" option offers a large flexibility for the users to set a dynamic initial value for the Rating widget.
You can use any HTML input element to extract the initial value for Rating widget: hidden input, text input, radio input.
You can create a Rating widget that will not allow you to vote by adding the "readOnly" option in the widget constructor. The widget is disabled and by default the stars have a different color from the case when Rating wiget allows you to vote.
When you try to click on the widget a message appears on the right side of the widget saying that the widget is disabled. You can customize this error message or can remove it if you consider is not necessary for you.
The following sample will show how to add a dynamic counter for your Rating widget. While moving the mouse over the widget, the counter reflects the current hovered value (e.g. 3/10). To enable this behavior for Rating widget you have to add in the widget constructor the "counter" option set on true and inside the widget container add the HTML element that will display the counted value.
You can disable the Rating widget to stop voting after user's first vote. The widget allows single vote until the page is refreshed or re-opened. If the user wants to have a more complex mechanism to stop voting based on server's reponse, he has to create it separate.
To not allow more than one rate, you have to add in the widget construcor the "allowMultipleVoting" option set on false. After first rate the widget goes in read-only state blocking the rating process. You can provide some custom messages for widget to underline the widget state after first vote or when the user tries to vote several times even the widget doesn't allow this.
The Rating widget below allows only one vote until the page is refreshed. After first vote a thank you message appears near the widget and the Rating widget is switched in read-only state changing its appearance. If you try to vote once again, the initial error message is replaced with a new one saying that you already gave your rate and the widget remains in read-only state.
The Rating widget provides an option called "rateHandler" where the user can specify a function to be called when the user makes a rating. If the "saveUrl" option is also present in the widget constructor, the function passed in the "rateHandler" option will be called after the data has been sent on the server specified in "saveURL".
In the next sample the "rateHandler" option calls a function that will pop-up an alert message displaying the rated value. The function will be triggered after the user rates.
Using the observers mechanism on a Rating widget in read-only state you can remove the message informing you that that the widget is disabled. The "removeMessage" function receives as first parameter the widget class name when is in a specific state and the second parameter represents the time when the class will be removed.
In the below sample, the "removeMessage" function recives as parameters: "ratingReadOnlyErrState" as class name to be removed and "2000" miliseconds.
The Rating widget comes with minimum css applied, but if you want you can add some more styling on it. The following example shows how to set a border around the Rating widget and also how to set a background color on the widget after rating.
By putting "tabindex" attribute on the stars placeholders, keyboard navigation is enabled. The default navigation keys are Left/Right and for rating the default key is Enter.
The next sample shows how to change the default navigation keys for the Rating widget. In this sample you can move forwoard/back using PageUp/PageDown keys and you can rate by pressing Space key.