deliteful/StarRating
The StarRating
widget displays a rating, usually with stars, that can be edited by touching or clicking the stars.
The StarRating
widget is a form field, which means that when included in an HTML form, its value will be submitted with those of the other form fields, under the name defined by its name
attribute.
Table of Contents
Element Instantiation
Element Configuration
Element Styling
User Interactions
Mixins
Element Events
Enterprise Use
Element Instantiation
See delite/Widget
for full details on how instantiation lifecycle is working.
Declarative Instantiation
<!-- Editable StarRating with: -->
<!-- * a minimum value of 0 -->
<!-- * a maximum value of 7 -->
<!-- * an initial value of 3.5 -->
<!-- * values set by increments of .5 -->
<d-star-rating name="rating" max="7" value="3.5" editHalfValues="true"></d-star-rating>
Programmatic Instantiation
require(["deliteful/StarRating", "requirejs-domready/domReady!"], function (StarRating) {
var starRating = new StarRating({max: 7, value: 3.5, editHalfValues: true});
starRating.placeAt(document.body);
});
Element Configuration
Using StarRating in a Form
The StarRating
widget is a form field, which means that when included in an HTML form, its value will be submitted with those of the other form fields, under the name defined by its name
attribute.
Here is an example of a StarRating
widget included in a form, under the name rating:
<form action="...">
<span id="lb1">Rating:</span><d-star-rating id="input1" name="rating" value="4" aria-labelledby="lb1"></d-star-rating>
<input type="submit">
</form>
Note that is the StarRating
is disabled, its value will not be submited.
Properties
The following properties can be set on a StarRating
instance:
max
: the maximum rating, that is also the number of stars to show.value
: the current value of the Rating.readOnly
: if false, the widget is editable and allows editing the value of the Rating by touching / clicking the starsname
: mandatory if using the star rating widget in a form, in order to have its value submiteddisabled
: if true, the widget is disabled (its value will not be submited if it is included in a form)editHalfValues
: if the Rating is not read only, define if the user is allowed to set half values (0.5, 1.5, ...)allowZero
: if false, the user is not allowed to set the value to 0 (default is true)
Element Styling
Supported themes
This widget provides default styling for the following delite themes:
- bootstrap
- ios
- holodark
CSS Classes
The star characters displayed for an empty star and a full star are font characters. Half stars are created by displaying the first half of a full star character followed by the second half of an empty star character.
The stars displayed can be fully customized by using the following CSS selectors:
.d-star-rating-star-icon {
font-size: 150%;
}
.d-star-rating-empty::before {
content: "\2605"; /* The font character to use to display an empty star */
color: #CCC; /* The color of an empty star */
}
.d-star-rating-full::before {
content: "\2605"; /* The font character to use to display a full star */
color: yellow; /* The color of a full star */
}
It is also possible to use an image stripes to render the stars, using a few more CSS selectors, as demonstrated in the following sample:
User Interactions
If the StarRating
widget properties readOnly
and / or disabled
are not set to true
, the value of the widget can be edited by:
- Touching the stars on a touch screen device;
Clicking the stars when using a mouse. When the stars are hovered by the mouse pointer, the widget highlight the value that will be set if the user click the mouse at the current position, as in the following picture:
Using the
arrow up
,arrow down
,arrow left
andarrow right
keys when the widget has the keyboard focus.
Mixins
No mixin currently available for this widget.
Element Events
This widget emits a change
event when its value is updated following a user action on the widget node. No change
event is emitted if the value is updated programmatically.
Enterprise Use
Accessibility
The StarRating
widget has an ARIA role of slider
.
It is keyboard navigable: unless it is read only, its value can be edited using the arrow keys (see User Interactions).
Limitation when using Apple VoiceOver
When a deliteful/StarRating
widget is selected in Safari while VoiceOver is on:
- The rating value is announced as a percentage instead as a number of stars ;
- VoiceOver announce that the widget value can be adjusted by swiping up or down, but this is not the case. To edit the widget value, you must double tap the widget and keep pressing. When VoiceOver announce that the widget is editable, you can adjust the value by moving left and right.
Globalization
deliteful/StarRating
provide an internationalizable bundle that contains only one message, with the key aria-valuetext
.
This message supports the keyword ${value}
, that is replaced by the current value of the widget to set its aria-valuetext
property every time that the value is updated.
Right to left orientation is supported.
Security
This widget has no specific security concern. Refer to delite/FormValueWidget
documentation for general security advice on this base class.
Browser Support
This widget supports all supported browsers without any degraded behavior.