User Guide

Overview

The wijrating widget generates a customizable star rating widget automatically. The widget is based on a set of select options, or radio inputs, or div elements with widget options.

The image below illustrates the main elements of the wijdialog widget:

NOTE: This documentation pertains to the latest Wijmo release. Please check the Version Histories for an outline of new features, improvements, and changes to the Wijmo widgets.

Markup and Scripting

Markup for a wijrating looks similar to this:

<select id="ratingSelect">
<option value="1">Below Average</option>
<option value="2">Average</option>
<option selected="selected" value="3">Above Average</option>
<option value="4">Awesome</option>
<option value="5">Epic</option>
 </select>

OR

<div id="ratingRadio">
	<label for="input1a">
		Below Average</label>
	<input type="radio" id="input1a" value="1" name="rating" />
	<label for="input2a">
		Average</label>
	<input type="radio" checked="checked" id="input2a" value="2" name="rating" />
	<label for="input3a">
		Above Average</label>
	<input type="radio" id="input3a" value="3" name="rating" />
	<label for="input4a">
		Awesome</label>
	<input type="radio" id="input4a" value="4" name="rating" />
	<label for="input5a">
		Epic</label>
	<input type="radio" id="input5a" value="5" name="rating" />
</div>

OR

<div id="ratingDiv">
</div>

The following script initializes the wijrating widget:

<script id="scriptInit" type="text/javascript">
        $(document).ready(function () {
            $('#ratingSelect').wijrating();
            $('#ratingRadio').wijrating();
            $('#ratingDiv').wijrating({ value: 4 });
            
    </script>

And of the markup samples and the script featured here results in the following:

Quick Start

In this quick start, you will learn how to add the Rating widget to an HTML project. You will also learn how to customize the Rating widget so you can see a few of its unique features.

To begin, create an .html page and add links to the dependencies to your project. To do this, just link to the content delivery network (CDN) file for each project:

<!--jQuery References-->
<script src="http://code.jquery.com/jquery-1.9.1.min.js" type="text/javascript"></script>
<script src="http://code.jquery.com/ui/1.10.1/jquery-ui.min.js" type="text/javascript"></script>
 
<!--Theme-->
<link href="http://cdn.wijmo.com/themes/aristo/jquery-wijmo.css" rel="stylesheet" type="text/css" />
 
<!--Wijmo Widgets CSS-->
<link href="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.css" rel="stylesheet" type="text/css" />
 
<!--Wijmo Widgets JavaScript-->
<script src="http://cdn.wijmo.com/jquery.wijmo-open.all.3.20131.1.min.js" type="text/javascript"></script>
<script src="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.js" type="text/javascript"></script>

You can reference the latest dependencies from the CDN at http://wijmo.com/downloads/#wijmo-cdn.

To begin creating and customizing the wijrating widget, you can place the following markup within the body of the .html document:

<div id="ratingRadio">
<label for="input1a">
Below Average</label>
<input type="radio" id="input1a" value="1" name="rating" />
<label for="input2a">
Average</label>
<input type="radio" checked="checked" id="input2a" value="2" name="rating" />
<label for="input3a">
Above Average</label>
<input type="radio" id="input3a" value="3" name="rating" />
<label for="input4a">
Awesome</label>
<input type="radio" id="input4a" value="4" name="rating" />
<label for="input5a">
Epic</label>
<input type="radio" id="input5a" value="5" name="rating" />
</div>

To initialize the widget, you need to add some jQuery script.

<script id="scriptInit" type="text/javascript">
     $(document).ready(function () {
         $("#ratingRadio").wijrating();
     });
</script>

If you run your application now, the rating widget will resemble the following image:

How To

Customize Icons

It's easy to change the appearance of the wijrating widget. You can quickly customize the icons and the animation used while rating.

For this section, we'll customize the icons using the thumbs up or down icon set and the bar rating icon set.

Begin with the following markup in the body of the .html file:

<div id="ratingthumbs">
 </div>

<div id="ratingbar">
</div>

Insert the following script into the head of your document:

<script id="scriptInit" type="text/javascript">
     $(document).ready(function () {
         $('#ratingthumbs').wijrating({
             count: 2,
             ratingMode: "single",
             iconWidth: 16,
             iconHeight: 16,
             icons: {
                 iconsClass: ['wijmo-wijrating-normal-thumbdown', 'wijmo-wijrating-normal-thumbup'],
                 hoverIconsClass: ['wijmo-wijrating-hover-thumbdown', 'wijmo-wijrating-hover-thumbup'],
                 ratedIconsClass: ['wijmo-wijrating-rated-thumbdown', 'wijmo-wijrating-rated-thumbup'] 
                }
         });
         $('#ratingbar').wijrating({
             iconWidth: 11,
             iconHeight: 61,
             icons: { 
                 iconsClass: ['wijmo-wijrating-normal-bar-11', 'wijmo-wijrating-normal-bar-21', 'wijmo-wijrating-normal-bar-31', 'wijmo-wijrating-normal-bar-41', 'wijmo-wijrating-normal-bar-51', 'wijmo-wijrating-normal-bar-61'],
                 hoverIconsClass: ['wijmo-wijrating-hover-bar-11', 'wijmo-wijrating-hover-bar-21', 'wijmo-wijrating-hover-bar-31', 'wijmo-wijrating-hover-bar-41', 'wijmo-wijrating-hover-bar-51', 'wijmo-wijrating-hover-bar-61'],
                 ratedIconsClass: ['wijmo-wijrating-rated-bar-11', 'wijmo-wijrating-rated-bar-21', 'wijmo-wijrating-rated-bar-31', 'wijmo-wijrating-rated-bar-41', 'wijmo-wijrating-rated-bar-51', 'wijmo-wijrating-rated-bar-61'] 
                 } 
         });
     });             
    </script>

The two resulting rating widgets will resemble the following image:

Change Icon Size

You can also change the size of the stars in the rating widget using the following script:

<script id="scriptInit" type="text/javascript">
     $(document).ready(function () {
         $('#rating32stars').wijrating({
             split: 2,
             iconHeight: 32,
             iconWidth: 32,
             icons: {
                 iconsClass: 'wijmo-wijrating-normal-32',
                 hoverIconsClass: 'wijmo-wijrating-hover-32', 
                 ratedIconsClass: 'wijmo-wijrating-rated-32'
             }
         });
     });             
    </script>

The stars that result resemble the following image:

Add Animation

The following jQuery script will animate the rating widget on rating:

<script id="scriptInit" type="text/javascript">
     $(document).ready(function () {
         $('#rating32stars').wijrating({
            animation: {
                animated: "slide",
                easing: "linear",
                duration: 500,
                delay: 250
            },
             split: 2
         });
     });             
    </script>

These animation options are available for the widget:

blind	highlight
bounce	puff
clip	pulsate
drop	scale
explode	shake
fade	size
fold	slide

Now you can set up a Wijmo application, add the appropriate HTML markup and script to your application to create and call your widget, and change the appearance of your widget using jQuery script.

Concepts

Adaptive for Mobile Use

This widget is an adaptive widget in v3. If you are running v2.3.x, it is not adaptive. You can download v3 2013 1 here: Downloads Page.

An adaptive widget is different from a jQuery UI widget in that you can use it in both mobile and non-mobile web applications. To use it in non-mobile applications, just use the regular help. To use it in mobile applications:

Use jQuery Mobile instead of jQuery UI references
Do not initialize the widget in script (unless you need to for complex widgets like charts)
Use the data-role attribute to create the widget in markup

These steps are demonstrated in the Adaptive Widgets for jQuery Mobile topic.

API

Options

animation

An option that controls aspects of the widget's animation, such as the animation effect and easing.

Type: Object

Default: null

animated

The animated sub-property defines the animation effect for the rating widget.

delay

The delay sub-property defines the length of the delay in milliseconds.

duration

The duration sub-property defines the length of the animation effect in milliseconds.

easing

A value that indicates the easing for the animation. For more information, please see jQuery UI

The following easing effects are available:

"linear"

"easeIn"

"easeOut"

"backIn"

"backOut"

"elastic"

"bounce"

Code Example:

 $(".selector").wijrating("option", "animation", {animated: "fade", duration:1000})

count

A value that determines the number of stars to display.

Type: Number

Default: 5

Code Example:

$(".selector").wijrating("option", "count", 10)

direction

The direction option determines the direction in which items are rated.

Type: String

Default: "normal"

Remarks: Options are "normal" and "reversed". The "normal" represents rating from left to right or top to bottom.

Code Example:

 $(".selector").wijrating("option", "direction", "reversed")

disabled

A value that determines whether or not to disable the rating widget.

Type:Boolean

Default: False

Code Example:

 $(".selector").wijrating("option", "disabled", true)

hint

A value that controls the hint information shown when hovering over the rating star.

Type: Object

Default: {disabled: false, content: null}

disabled

An option that determines whether or not to show the hint.

Type: Boolean

Default: false

content

An option that determines the values that will be shown when a star is hovered over.

Type: Array

Default: null

Remarks:If the content is null and disabled is false, then the hint will show the value of each star.

Code Example:

 $(".selector").wijrating("option", "hint", {disabled: true})

iconHeight

An option that determines the height of the icon. All icons should have the same height.

Type: Number

Default: 16

Code Example:

$(".selector").wijrating("option", "iconHeight", 32)

icons

A value that indicates the settings for customized rating icons.

Type: Object

Default: {iconsUrl: null, hoverIconsUrl: null, ratedIconsUrl: null}

Code Example:

 $(".selector").wijrating("option", "icons")

iconsClass

A string or an array value that indicates the urls of icons.

Type: String or Array

Default: null

Remarks:

If the value is a string, then all of the stars will apply the iconsClass. If the value is an array, then each star will apply the related iconsClass value by index.

hoverIconsClass

A string or an array value that indicates the urls of hover icons.

Type: String or Array

Default: null

Remarks: If the value is a string, then all the stars will apply the iconsClass when hovered over. If the value is an array, then each star will apply the related iconsClass value by index when hovered over.

ratedIconsClass

A string or an array value that indicates the urls of rated icons.

Type: String or Array

Default: null

Remarks:If the value is a string, then all the rated stars will apply the iconsClass. If the value is an array, then each rated star will apply the related iconsClass value by index.

iconWidth

An option that determines the width of the icon. All icons should have the same width.

Type: Number

Default: 16

Code Example:

$(".selector").wijrating("option", "iconWidth", 32)

max

An option that defines the maximum value that can be rated using the rating widget.

Type: Number

Default: null

Code Example:

 $(".selector").wijrating("option", "max", 3)

min

An option that defines the minimum value that can be rated using the rating widget.

Type: Number

Default: null

Code Example:

  $(".selector").wijrating("option", "min", 2)

orientation

The orientation option determines the orientation of the rating widget.

Type: String

Default: "horizontal"

Remarks: The available options are "horizontal" or "vertical".

Code Example:

 (".selector").wijrating("option", "orientation", "vertical")

ratingMode

The ratingMode option determines how the widget performs the rating function. The widget can rate things continuously or singly.

Type: String

Default: "continuous"

Remarks: The options are "continuous" and "single". The "single" option represents that only one star can be rated, while "continuous" represents that all the stars from first to the rated one will be rated.

Code Example:

 $(".selector").wijrating("option", "ratingMode", "single")

resetButton

The resetButton option determines the properties of the widget's reset button. The button is used to reset the rated value to 0. If the rating widget is disabled, then the reset button will be hidden.

Type: Object

Default: {disabled: false, hint: "cancel this rating!", position: leftOrTop",customizedClass:"",customizedHoverClass:""}

Code Example:

 
       $(".selector").wijrating("option", "resetButton", {disabled: true})

disabled

An option that determines whether to show the reset button.

Type: Boolean

Default: false

hint

An option that controls the text shown when hovering over the button.

Type: String

Default: "cancel this rating!"

position

The position sub-property defines the resetButton's position in relation to the rating widget. The options are "leftOrTop" or "rightOrBottom".

Type: String

Default: "leftOrTop"

customizedClass

The value that controls the customized class added to the reset button.

Type: String

Default: ""

customizedHoverClass

An option that controls the customized class added to the reset button when a user hovers over it.

Type: String

Default: ""

split

An option that determines the number of sections into which each star will be split.

Type: Number

Default: 1

Code Example:

$(".selector").wijrating("option", "split", 2)

totalValue

An option that determines the total value of the rating widget.

Type: Number

Default: 5

Remarks: For example, in a rating widget with 5 stars the count is 5. A split of 2 means that each star is split into two parts. If the totalValue of the stars is 100, then each part of the split star has a value of 10 and each whole star has a value of 20. The step can be represented by this equation: 100/(5 * 2) = 10 and the value of one star can be represented by this equation: 10*(1 * 2) = 20.

Code Example:

 $(".selector").wijrating("option", "totalValue", 100)

value

An option that determines the rated value of the rating widget.

Type: Number

Default: 0

Code Example:

 $(".selector").wijrating("option", "value", 1)

Events

hover

The hover event fires on mouse hover.

Default: null

Type: Function

Parameters:

e: A jQuery.Event object.

data: An object that contains the value of the hovered object.

Code Example:

 // Supply a function as an option. 
$(".selector").wijrating({hover: function(e, data) { } }); 
// Bind to the event by type: wijratinghover 
$(".selector").bind("wijratinghover", function(e, data) {} );

rated

The rated event fires after the widget is rated.

Default: null

Type: Function

Parameters:

e: A jQuery.Event object.

data: An object that contains the new value.

Code Example:

 // Supply a function as an option. 
$(".selector").wijrating({rated: function(e, data) { } }); 
// Bind to the event by type: wijratingrated 
$(".selector").bind("wijratingrated", function(e, data) {} );

rating

The rating event fires before widget rating. This event can be cancelled with "return false;".

Default: null

Type: Function

Parameters:

e: A jQuery.Event object.

data: An object that contains the new value and old value.

Code Example:

 // Supply a function as an option. 
$(".selector").wijrating({rating: function(e, data) { } }); 
// Bind to the event by type: wijratingrating 
$(".selector").bind("wijratingrating", function(e, data) {} );

reset

The reset event fires when the reset button is clicked.

Default: null

Type: Function

Parameters:

e: A jQuery.Event object.

Code Example:

 // Supply a function as an option. 
$(".selector").wijrating({reset: function(e) { } }); 
// Bind to the event by type: wijratingreset 
$(".selector").bind("wijratingreset", function(e) {} );

Methods

The following methods are included in the wijrating widget:

destroy

The destroy method removes the rating functionality completely and returns the element to its pre-init state.

Code Example:

 $(".selector").wijrating("destroy");

disable

The disable method disables the wijrating widget.

Code Example:

 $(".selector").wijrating("disable");

enable

The enable method enables the wijrating widget.

Code Example:

 $(".selector").wijrating("enable");

option

The option method allows the user to get or set any wijrating option. If no value is specified, the method acts as a getter.

Parameters:

optionName

Represents the name of the option to get or set.

Type: String

value

Represents the value to set.

Type: Object.

Code Example:

 $(".selector").wijrating("option", "count");
$(".selector").wijrating("option", "count", 10);

option

The option method allows the user to set multiple options at once by providing an options object.

Parameters:

options

Represents the options value that should be set.

Type: Object

Code Example:

 $(".selector").wijrating("option", {count: 10, value: 10});

widget

The widget method returns the wijrating element.

Code Example:

 $(".selector").wijrating("widget");

Rating

Contents

User Guide

Overview

Markup and Scripting

Quick Start

How To

Customize Icons

Change Icon Size

Add Animation

Concepts

Adaptive for Mobile Use

API

Options

animation

animated

delay

duration

easing

count

direction

disabled

hint

disabled

content

iconHeight

icons

iconsClass

hoverIconsClass

ratedIconsClass

iconWidth

max

min

orientation

ratingMode

resetButton

disabled

hint

position

customizedClass

customizedHoverClass

split

totalValue

value

Events

hover

rated

rating

reset

Methods

destroy

disable

enable

option

option

widget