Class sap.m.RatingIndicatorModule: sap/m/RatingIndicator

extends Control

The rating indicator is used to display a specific number of icons that are used to rate an item. Additionally it is also used to display the average over all ratings.

Structure

  • The rating indicator can use different icons (default: stars) which are defined as URIs in the properties iconHovered, iconSelected and iconUnselected.
  • The rating indicator can display half-values (visualMode = Half) when it is used to show the average. Half-values can't be selected by the user.

Usage

The preferred number of icons is between 5 (default) and 7.

Responsive Behavior

You can display icons in 4 recommended sizes:

  • large - 32px
  • medium(default) - 22px
  • small - 16px
  • XS - 12px

Note: If no icon size is set, the rating indicator will set it according to the content density.
Since: 1.14.

Constructor Summary
new sap.m.RatingIndicator(sId?, mSettings?)Constructor for a new RatingIndicator.
Event Summary
change(oControlEvent)The event is fired when the user has done a rating.
liveChange(oControlEvent)This event is triggered during the dragging period, each time the rating value changes.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.RatingIndicator.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.RatingIndicator with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.RatingIndicator.getMetadata()Returns a metadata object for class sap.m.RatingIndicator.
addAriaDescribedBy(vAriaDescribedBy)Adds some ariaDescribedBy into the association ariaDescribedBy.
addAriaLabelledBy(vAriaLabelledBy)Adds some ariaLabelledBy into the association ariaLabelledBy.
attachChange(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the change event of this sap.m.RatingIndicator.
attachLiveChange(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the liveChange event of this sap.m.RatingIndicator.
bindValue(oBindingInfo)Binds property value to model data.
detachChange(fnFunction, oListener)Detaches event handler fnFunction from the change event of this sap.m.RatingIndicator.
detachLiveChange(fnFunction, oListener)Detaches event handler fnFunction from the liveChange event of this sap.m.RatingIndicator.
fireChange(mParameters?)Fires event change to attached listeners.
fireLiveChange(mParameters?)Fires event liveChange to attached listeners.
getAriaDescribedBy()Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
getAriaLabelledBy()Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
getEnabled()Gets current value of property enabled.
getIconHovered()Gets current value of property iconHovered.
getIconSelected()Gets current value of property iconSelected.
getIconSize()Gets current value of property iconSize.
getIconUnselected()Gets current value of property iconUnselected.
getMaxValue()Gets current value of property maxValue.
getValue()Gets current value of property value.
getVisualMode()Gets current value of property visualMode.
removeAllAriaDescribedBy()Removes all the controls in the association named ariaDescribedBy.
removeAllAriaLabelledBy()Removes all the controls in the association named ariaLabelledBy.
removeAriaDescribedBy(vAriaDescribedBy)Removes an ariaDescribedBy from the association named ariaDescribedBy.
removeAriaLabelledBy(vAriaLabelledBy)Removes an ariaLabelledBy from the association named ariaLabelledBy.
setEnabled(bEnabled)Sets a new value for property enabled.
setIconHovered(sIconHovered)Sets a new value for property iconHovered.
setIconSelected(sIconSelected)Sets a new value for property iconSelected.
setIconSize(sIconSize)Sets the icon size value.
setIconUnselected(sIconUnselected)Sets a new value for property iconUnselected.
setMaxValue(iMaxValue)Sets a new value for property maxValue.
setValue(fValue)Sets the rating value.
setVisualMode(sVisualMode)Sets a new value for property visualMode.
unbindValue()Unbinds property value from model data.
Constructor Detail
new sap.m.RatingIndicator(sId?, mSettings?)

Constructor for a new RatingIndicator.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject for a general description of the syntax of the settings object.

The supported settings are:

  • Properties

  • Associations

  • Events

    • change : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • liveChange : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsId?ID for the new control, generated automatically if no ID is given
objectmSettings?Initial settings for the new control Enables users to rate an item on a numeric scale.
Event Detail
change(oControlEvent)
The event is fired when the user has done a rating.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
intoControlEvent.getParameters.valueThe rated value
liveChange(oControlEvent)
This event is triggered during the dragging period, each time the rating value changes.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
floatoControlEvent.getParameters.valueThe current value of the rating after a live change event.
Method Detail
sap.m.RatingIndicator.extend(sClassName, oClassInfo?, FNMetaImpl?): function

Creates a new subclass of class sap.m.RatingIndicator with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.m.RatingIndicator.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.RatingIndicator.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addAriaDescribedBy(vAriaDescribedBy): sap.m.RatingIndicator
Adds some ariaDescribedBy into the association ariaDescribedBy.
Parameters:
sap.ui.core.ID|sap.ui.core.ControlvAriaDescribedBythe ariaDescribedBy to add; if empty, nothing is inserted
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
addAriaLabelledBy(vAriaLabelledBy): sap.m.RatingIndicator
Adds some ariaLabelledBy into the association ariaLabelledBy.
Parameters:
sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledBythe ariaLabelledBy to add; if empty, nothing is inserted
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
attachChange(oData?, fnFunction, oListener?): sap.m.RatingIndicator

Attaches event handler fnFunction to the change event of this sap.m.RatingIndicator.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.RatingIndicator itself.

The event is fired when the user has done a rating.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.RatingIndicator itself
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
attachLiveChange(oData?, fnFunction, oListener?): sap.m.RatingIndicator

Attaches event handler fnFunction to the liveChange event of this sap.m.RatingIndicator.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.RatingIndicator itself.

This event is triggered during the dragging period, each time the rating value changes.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.RatingIndicator itself
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
bindValue(oBindingInfo): sap.m.RatingIndicator

Binds property value to model data.

See ManagedObject.bindProperty for a detailed description of the possible properties of oBindingInfo

Parameters:
objectoBindingInfoThe binding information
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
detachChange(fnFunction, oListener): sap.m.RatingIndicator

Detaches event handler fnFunction from the change event of this sap.m.RatingIndicator.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
detachLiveChange(fnFunction, oListener): sap.m.RatingIndicator

Detaches event handler fnFunction from the liveChange event of this sap.m.RatingIndicator.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
fireChange(mParameters?): sap.m.RatingIndicator
Fires event change to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
intmParameters.value?The rated value
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
fireLiveChange(mParameters?): sap.m.RatingIndicator
Fires event liveChange to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
floatmParameters.value?The current value of the rating after a live change event.
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
getAccessibilityInfo()
See:
sap.ui.core.Control#getAccessibilityInfo
getAriaDescribedBy(): sap.ui.core.ID[]
Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
Returns:
sap.ui.core.ID[]
getAriaLabelledBy(): sap.ui.core.ID[]
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
Returns:
sap.ui.core.ID[]
getEnabled(): boolean

Gets current value of property enabled.

Value "true" is required to let the user rate with this control. It is recommended to set this parameter to "false" for the "Small" size which is meant for indicating a value only

Default value is true.

Returns:
booleanValue of property enabled
getIconHovered(): sap.ui.core.URI

Gets current value of property iconHovered.

The URI to the icon font icon or image that will be displayed for hovered rating symbols. A star icon will be used if the property is not set

Returns:
sap.ui.core.URIValue of property iconHovered
getIconSelected(): sap.ui.core.URI

Gets current value of property iconSelected.

The URI to the icon font icon or image that will be displayed for selected rating symbols. A star icon will be used if the property is not set

Returns:
sap.ui.core.URIValue of property iconSelected
getIconSize(): sap.ui.core.CSSSize

Gets current value of property iconSize.

The Size of the image or icon to be displayed. The default value depends on the theme. Please be sure that the size is corresponding to a full pixel value as some browsers don't support subpixel calculations. Recommended size is 1.375rem (22px) for normal, 1rem (16px) for small, and 2rem (32px) for large icons correspondingly.

Returns:
sap.ui.core.CSSSizeValue of property iconSize
getIconUnselected(): sap.ui.core.URI

Gets current value of property iconUnselected.

The URI to the icon font icon or image that will be displayed for all unselected rating symbols. A star icon will be used if the property is not set

Returns:
sap.ui.core.URIValue of property iconUnselected
getMaxValue(): int

Gets current value of property maxValue.

The number of displayed rating symbols

Default value is 5.

Returns:
intValue of property maxValue
getValue(): float

Gets current value of property value.

The indicated value of the rating

Default value is 0.

Returns:
floatValue of property value

Gets current value of property visualMode.

Defines how float values are visualized: Full, Half (see enumeration RatingIndicatorVisualMode)

Default value is Half.

Returns:
sap.m.RatingIndicatorVisualModeValue of property visualMode
removeAllAriaDescribedBy(): sap.ui.core.ID[]
Removes all the controls in the association named ariaDescribedBy.
Returns:
sap.ui.core.ID[]An array of the removed elements (might be empty)
removeAllAriaLabelledBy(): sap.ui.core.ID[]
Removes all the controls in the association named ariaLabelledBy.
Returns:
sap.ui.core.ID[]An array of the removed elements (might be empty)
removeAriaDescribedBy(vAriaDescribedBy): sap.ui.core.ID
Removes an ariaDescribedBy from the association named ariaDescribedBy.
Parameters:
int|sap.ui.core.ID|sap.ui.core.ControlvAriaDescribedByThe ariaDescribedBy to be removed or its index or ID
Returns:
sap.ui.core.IDThe removed ariaDescribedBy or null
removeAriaLabelledBy(vAriaLabelledBy): sap.ui.core.ID
Removes an ariaLabelledBy from the association named ariaLabelledBy.
Parameters:
int|sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledByThe ariaLabelledBy to be removed or its index or ID
Returns:
sap.ui.core.IDThe removed ariaLabelledBy or null
setEnabled(bEnabled): sap.m.RatingIndicator

Sets a new value for property enabled.

Value "true" is required to let the user rate with this control. It is recommended to set this parameter to "false" for the "Small" size which is meant for indicating a value only

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Parameters:
booleanbEnabledNew value for property enabled
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
setIconHovered(sIconHovered): sap.m.RatingIndicator

Sets a new value for property iconHovered.

The URI to the icon font icon or image that will be displayed for hovered rating symbols. A star icon will be used if the property is not set

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:
sap.ui.core.URIsIconHoveredNew value for property iconHovered
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
setIconSelected(sIconSelected): sap.m.RatingIndicator

Sets a new value for property iconSelected.

The URI to the icon font icon or image that will be displayed for selected rating symbols. A star icon will be used if the property is not set

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:
sap.ui.core.URIsIconSelectedNew value for property iconSelected
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
setIconSize(sIconSize): sap.m.RatingIndicator
Sets the icon size value. The method is automatically updating the UI components if the control has been rendered before.
Parameters:
sap.ui.core.CSSSizesIconSize
Returns:
sap.m.RatingIndicatorReturns this to facilitate method chaining.
setIconUnselected(sIconUnselected): sap.m.RatingIndicator

Sets a new value for property iconUnselected.

The URI to the icon font icon or image that will be displayed for all unselected rating symbols. A star icon will be used if the property is not set

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:
sap.ui.core.URIsIconUnselectedNew value for property iconUnselected
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
setMaxValue(iMaxValue): sap.m.RatingIndicator

Sets a new value for property maxValue.

The number of displayed rating symbols

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 5.

Parameters:
intiMaxValueNew value for property maxValue
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
setValue(fValue): sap.m.RatingIndicator
Sets the rating value. The method is automatically checking whether the value is in the valid range of 0-maxValue and if it is a valid number. Calling the setter with null or undefined will reset the value to it's default.
Parameters:
floatfValueThe rating value to be set.
Returns:
sap.m.RatingIndicatorReturns this to facilitate method chaining.
setVisualMode(sVisualMode): sap.m.RatingIndicator

Sets a new value for property visualMode.

Defines how float values are visualized: Full, Half (see enumeration RatingIndicatorVisualMode)

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Half.

Parameters:
sap.m.RatingIndicatorVisualModesVisualModeNew value for property visualMode
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining
unbindValue(): sap.m.RatingIndicator
Unbinds property value from model data.
Returns:
sap.m.RatingIndicatorReference to this in order to allow method chaining