Ignite UI™ API Documentation

ui.igRating

The igRating control is an HTML 5 capable jQuery widget. The control supports various display and style options along with continuous selection and precision options. Further information regarding the classes, options, events, methods and themes of this API are available under the associated tabs above.

The following code snippet demonstrates how to initialize the igRating control.

Click here for more information on how to get started using this API. For details on how to reference the required scripts and themes for the igRating control read, Using JavaScript Resources in Ignite UI and Styling and Theming Ignite UI.

Code Sample

<!doctype html>
<html>
<head>
    <!-- Infragistics Combined CSS -->
    <link href="css/themes/infragistics/infragistics.theme.css" rel="stylesheet" type="text/css" />
    <link href="css/structure/infragistics.css" rel="stylesheet" type="text/css" />
    <!-- jQuery Core -->
    <script src="js/jquery.js" type="text/javascript"></script>
    <!-- jQuery UI -->
    <script src="js/jquery-ui.js" type="text/javascript"></script>
    <!-- Infragistics Combined Scripts -->
    <script src="js/infragistics.core.js" type="text/javascript"></script>
    <script src="js/infragistics.lob.js" type="text/javascript"></script>
    <script type="text/javascript">
    $(function () {
        $("#rating").igRating({
            voteCount: 7,
            value: 0.4,
            vertical: true,
            swapDirection: true
        });
    });
    </script>
</head>
<body>
    <div id="rating"></div>
</body>
</html>

Related Samples

cssVotes

Type:: object
Default:: null

Gets/Sets custom css votes.
That object should be 2-dimentional array or object with indexes, where every item of first level represents settings for a vote at that index.
Second level of an item is settings for a vote and it should contain classes for a specific state of vote.
Item at index [0] on second level is used for css class of vote in normal state.
Item at index [1] on second level is used for css class of vote in selected state.
Item at index [2] on second level is used for css class of vote in hover state.
Examples:
{ 1: { 0: "normalCss", 1: "selectedCss", 2: "hoverCss"} }
will customize only second vote with normalCss for normal state, hoverCss for hover state and selectedCss for selected state.
[[null, 's1', 'h1'], [null, 's2', 'h2'], [null, 's3', 'h3']]
will customize selected and hover states for first 3 votes with classes h# and s#.

Code Sample

//Initialize
$(".selector").igRating({
    cssVotes : customCss
});
 
//Get
var css = $(".selector").igRating("option", "cssVotes");
 
//Set
$(".selector").igRating("option", "cssVotes", customCss);
 
customCss = [
    ["selected0", "selected1", "selected2"],
    ["normal0", "normal1", "normal2"],
    ["hovered0", "hovered1", "hovered2"]
];
 
<style type="text/css">
.normal0 { ... }
.normal1 { ... }
.normal2 { ... }
.selected0 { ... }
.selected1 { ... }
.selected2 { ... }
.hovered0 { ... }
.hovered1 { ... }
.hovered2 { ... }
</style>

focusable

Type:

bool

Default:

true

Gets if igRating can have focus. Change of that option is not supported after igRating was created.
Value true: can get focus and process key events.
Value false: cannot get focus.

Code Sample

//Initialize
$(".selector").igRating({
focusable : false
});

//Get
var focusable = $(".selector").igRating("option", "focusable");
language
Inherited

Type:

string

Default:

"en"

Set/Get the locale language setting for the widget.

Code Sample

//Initialize
$(".selector").igRating({
language: "ja"
});

// Get
var language = $(".selector").igRating("option", "language");

// Set
$(".selector").igRating("option", "language", "ja");
locale
Inherited

Type:

object

Default:

null

Set/Get the locale setting for the widget.

Code Sample

//Initialize
$(".selector").igRating({
locale: {}
});

// Get
var locale = $(".selector").igRating("option", "locale");

// Set
$(".selector").igRating("option", "locale", {});
precision

Type:

enumeration

Default:

whole
Gets/Sets precision. Precision of value and valueHover.
Members
- exact
- Type:string
- Value corresponds location of mouse.
- half
- Type:string
- Value is rounded to the half of vote.
- whole
- Type:string
- Value is rounded to the number of votes.
Code Sample

//Initialize
$(".selector").igRating({
precision : "half"
});
//Get
var precision = $(".selector").igRating("option", "precision");
//Set
$(".selector").igRating("option", "precision", "half");

precisionZeroVote

Type:: number
Default:: 0.25

Gets/Sets part of vote-size, which is considered as zero value.
It has effect only when precision is set to "half" or "whole".
If user clicks between edge of the first vote and (sizeOfVote * precisionZeroVote), then value is set to 0.
Same is applied for mouseover as well.

Code Sample

//Initialize
$(".selector").igRating({
    precisionZeroVote : 0.5
});
 
//Get
var precisionZero = $(".selector").igRating("option", "precisionZeroVote");
 
//Set
$(".selector").igRating("option", "precisionZeroVote", 0.5);

regional
Inherited

Type:

enumeration

Default:

defaults

Set/Get the regional setting for the widget.

Code Sample

//Initialize
$(".selector").igRating({
regional: "ja"
});
// Get
var regional = $(".selector").igRating("option", "regional");
// Set
$(".selector").igRating("option", "regional", "ja");

roundedDecimalPlaces

Type:: number
Default:: 3

Gets/Sets number of decimal places used to round value and value-hover.
Negative value will disable that option and value will not be rounded.
Notes:
If precision is "whole" or "half" and roundedDecimalPlaces is set in range of 0..2, then 3 is used.
If valueAsPercent is enabled and roundedDecimalPlaces is set to 0, then 1 is used.
If it is larger than 15, then 15 is used.

Code Sample

//Initialize
$(".selector").igRating({
    roundedDecimalPlaces : 2
});
 
//Get
var decimalPlaces = $(".selector").igRating("option", "roundedDecimalPlaces");
 
//Set
$(".selector").igRating("option", "roundedDecimalPlaces", 2);

swapDirection

Type:

bool

Default:

false

Gets the direction of selected and hovered votes. Change of that option is not supported after igRating was created.
Value true: from left to right or from top to bottom.
Value false: from right to left or from bottom to left.

Code Sample

//Initialize
$(".selector").igRating({
swapDirection : true
});

//Get
var swap = $(".selector").igRating("option", "swapDirection");

theme

Type:: string
Default:: null

Gets/Sets selector for css classes.
That option allows replacing all default css styles by custom values.
Application should provide css classes for all members defined in the css options with "theme" selector.

Code Sample

//Initialize
$(".selector").igRating({
    theme : "redmond"
});
 
//Get
var theme = $(".selector").igRating("option", "theme");
 
//Set
$(".selector").igRating("option", "theme", "redmond");
 
//CSS theme definition
.redmond .ui-igrating { ... }
.redmond .ui-igrating-active { ... }
.redmond .ui-igrating-hover { ... }
.redmond .ui-igrating-vote { ... }
.redmond .ui-igrating-voteselected { ... }
.redmond .ui-igrating-votehover { ... }
.redmond .ui-igrating-votedisabled { ... }
.redmond .ui-igrating-votedisabledselected { ... }

validatorOptions

Type:: object
Default:: null

Gets/Sets object which contains options supported by igValidator.
Note that for onblur validation depends on the focusable option.

Code Sample

//Initialize
$(".selector").igRating({
    validatorOptions : {
        onblur: true
    }
});
 
//Get
var validatorOptions = $(".selector").igRating("option", "validatorOptions");
 
//Set
$(".selector").igRating("option", "validatorOptions", {onblur: true});

value

Type:

enumeration

Default:

null

Gets/Sets value (selected votes or percent). If the value is of type string, it should be suitable for parsing to number. According to valueAsPercent options the value is used as number of selected votes or as a percent of the votes.

Code Sample

//Initialize
$(".selector").igRating({
value : 3
});
//Get
var value = $(".selector").igRating("option", "value");
//Set
$(".selector").igRating("option", "value", 3);

valueAsPercent

Type:: bool
Default:: true

Gets/Sets percent or vote number to measure value and value-hover.
Value true: value is measured as percent (from 0 to 1).
Value false: value is measured in number of voted (from 0 to voteCount).

Code Sample

//Initialize
$(".selector").igRating({
    valueAsPercent : false
});
 
//Get
var isPercent = $(".selector").igRating("option", "valueAsPercent");
 
//Set
$(".selector").igRating("option", "valueAsPercent", false);

valueHover

Type:

enumeration

Default:

null

Gets/Sets value-hover (hovered votes or percent of hovered votes). The default is same as value. If the value is of type string, it should be suitable for parsing to number. According to valueAsPercent options the valueHover is used as number of hovered votes or as a percent of the hovered votes.

Code Sample

//Initialize
$(".selector").igRating({
valueHover : 2
});
//Get
var hoverVal = $(".selector").igRating("option", "valueHover");
//Set
$(".selector").igRating("option", "valueHover", 2);
vertical

Type:

bool

Default:

false

Gets a vertical or horizontal orientation for the votes.
Change of that option is not supported after igRating was created.

Code Sample

$(".selector").igRating({
vertical : true
});

//Get
var isVertical = $(".selector").igRating("option", "vertical");
voteCount

Type:

number

Default:

5

Gets/Sets number of votes.

Code Sample

//Initialize
$(".selector").igRating({
voteCount : 3
});

//Get
var count = $(".selector").igRating("option", "voteCount");

//Set
$(".selector").igRating("option", "voteCount", 3);
voteHeight

Type:

number

Default:

0

Gets/Sets custom height of a vote in pixels. In case of 0 the run time style value is used.

Code Sample

//Initialize
$(".selector").igRating({
voteHeight : 38
});

//Get
var height = $(".selector").igRating("option", "voteHeight");

//Set
$(".selector").igRating("option", "voteHeight", 38);
voteWidth

Type:

number

Default:

0

Gets/Sets custom width of a vote in pixels. In case of 0 the run time style value is used.

Code Sample

//Initialize
$(".selector").igRating({
voteWidth : 64
});

//Get
var width = $(".selector").igRating("option", "voteWidth");

//Set
$(".selector").igRating("option", "voteWidth", 64);

For more information on how to interact with the Ignite UI controls' events, refer to
Using Events in Ignite UI.

Note: Calling API methods programmatically does not raise events related to their operation unless specifically stated otherwise by the corresponding API documentation; those events are only raised by their respective user interaction.

Show Details

hoverChange

Cancellable:: true

Fired before hover value is changed.
If the application returns false, then the action is canceled and the value remains unchanged.

evt
Type: Event

JQuery event object.
ui
Type: Object

Code Sample

//Bind after initialization
$(document).on("igratinghoverchange", ".selector", function (evt, ui) {
    //return the triggered event
    evt;
 
    //the value before the igRating was hovered
    ui.oldValue;
    //the current hover value
    ui.value;
});
 
//Initialize
$(".selector").igRating({
    hoverChange : function(evt, ui) {...}
});

valueChange

Cancellable:: true

Fired before (selected) value is changed.
If the application returns false, then the action is canceled and the value remains unchanged.

evt
Type: Event

JQuery event object.
ui
Type: Object

Code Sample

//Bind after initialization
$(document).on("igratingvaluechange", ".selector", function (evt, ui) {
    //return the triggered event
    evt;
 
    //gets old value of the igRating widget
    ui.oldValue;
    //gets the current selected value of the igRating widget
    ui.value;
});
 
//Initialize
$(".selector").igRating({
    valueChange : function(evt, ui) {...}
});

Show Details

changeGlobalLanguage
Inherited

.igRating( "changeGlobalLanguage" );
Changes the widget language to global language. Global language is the value in $.ig.util.language.
Code Sample

$(".selector").igRating("changeGlobalLanguage");
changeGlobalRegional
Inherited

.igRating( "changeGlobalRegional" );
Changes the widget regional settins to global regional settings. Global regional settings are container in $.ig.util.regional.
Code Sample

$(".selector").igRating("changeGlobalRegional");
changeLocale
Inherited

.igRating( "changeLocale", $container:object );
Changes the all locales contained into a specified container to the language specified in options.language
Note that this method is for rare scenarios, use language or locale option setter.
- $container
- Type:object
- Optional parameter - if not set it would use the element of the widget as $container.
Code Sample

$(".selector").igRating("changeLocale");
destroy

.igRating( "destroy" );

Return Type:

object

Return Type Description:

Returns reference to this igRating.
Destroys igRating widget.
Code Sample

$(".selector").igRating("destroy");
focus

.igRating( "focus" );

Return Type:

object

Return Type Description:

Returns reference to this igRating.
Sets focus to igRating. That has effect only when options.focusable is enabled.
Code Sample

$(".selector").igRating("focus");
hasFocus

.igRating( "hasFocus" );

Return Type:

bool

Return Type Description:

Returns true if igRating has focus.
Checks if igRating has focus.
Code Sample

var focused = $(".selector").igRating("hasFocus");
validate

.igRating( "validate" );

Return Type:

bool

Return Type Description:

True if all checks have passed. Can be null in case validation is not enabled.
Triggers validation.
Code Sample

$(".selector").igRating("validate");

validator

.igRating( "validator", [destroy:bool] );
Return Type:: object
Return Type Description:: Returns reference to igValidator or null.

Gets reference to igValidator used by igRating.

destroy
Type:bool
Optional
Request to destroy validator.

Code Sample

//get igValidator widget that is used by the igRating
var validator = $(".selector").igRating("validator");
 
//destroy the igValidator widget that is used by the igRating
$(".selector").igRating("validator", "destroy");

value

.igRating( "value", val:number );

Return Type:

enumeration

Return Type Description:

Can return 'number|object'. If parameter is not 'number', then exact value rendered with selected css is returned. Otherwise, reference to igRating is returned.
Gets/Sets (selected) value.
- val
- Type:number
- New value which is rendered with selected css.
Code Sample

//Get
var value = $(".selector").igRating("value");

//Set
$(".selector").igRating("value", 4);
valueHover

.igRating( "valueHover", [val:number] );

Return Type:

enumeration

Return Type Description:

Can return 'number|object'. If parameter is not "number", then last value which was rendered with hover css is returned. Otherwise, reference to igRating is returned.
Gets/Sets hover value.
- val
- Type:number
- Optional
- New value which will be rendered with hover css when rating gets mouse.
Code Sample

//Get
var value = $(".selector").igRating("valueHover");

//Set
$(".selector").igRating("valueHover", 5);

ui-igrating-active

Class applied to the DIV container element when igRating has focus. Default value is 'ui-igrating-active'.
ui-igrating-hover ui-state-hover

Classes applied to the container of hover votes. Default value is 'ui-igrating-hover ui-state-hover'.
ui-igrating ui-state-default ui-widget-content

Classes applied to the DIV container element. Default value is 'ui-igrating ui-state-default ui-widget-content'.
ui-igrating-selected ui-state-highlight

Classes applied to the container of hover votes. Default value is 'ui-igrating-selected ui-state-highlight'.
ui-igrating-vote ui-icon ui-icon-star

Classes applied to the SPAN element of a vote. Default value is 'ui-igrating-vote ui-icon ui-icon-star'.
ui-igrating-votedisabled ui-state-disabled

Classes applied to the SPAN element of a vote in disabled state. Default value is 'ui-igrating-votedisabled ui-state-disabled'.
ui-igrating-votedisabledselected ui-state-disabled

Classes applied to the SPAN element of a vote in selected state when igRating is disabled. Default value is 'ui-igrating-votedisabledselected ui-state-disabled'.
ui-igrating-votehover

Class applied to the SPAN element of a vote in hover state. Default value is 'ui-igrating-votehover'.
ui-igrating-voteselected

Class applied to the SPAN element of a vote in selected state. Default value is 'ui-igrating-voteselected'.

Ignite UI for jQuery | API Reference

ui.igRating

Code Sample

Related Samples

Related Topics

Dependencies

Inherits