jq-rating (1.0.3)

jQuery plugin to display "stars" (or something else) based ratings

Demo

You can find some demos here : http://esleducation.github.io/jq-rating/

Install

You can simply download or clone the repo, or install using bower like this

bower install jq-rating

Get Started

First, you need to include the scripts and css in your page

<link href="jq-rating.css" rel="styletheet" type="text/css" />
<!-- optional font-awesome to have access to icons -->
<link href="font-awesome.css" rel="styletheet" type="text/css" />

<script src="jquery.js"></script>
<script src="jq-rating.js"></script>

Then you just have to init the plugin as you do with all others jQuery plugins

<span data-jq-rating></span>

<!-- or if you need to specify where each elements are goiing to stand -->
<span data-jq-rating>
    <span data-jq-rating-stars></span><!-- display the stars here -->
    <span data-jq-rating-grade></span><!-- display the grade (value) here -->
</span>

jQuery(function($) {

    // init the plugin on all "data-jq-rating" elements
    $('[data-jq-rating]').jqRating();

});

See the index.html file for full sample

Options

There are all the options available

• value : the actual rating value
• basedOn : the max rating value
• starsCount : how many "stars" you want
• updateOn : when you want that the value is updated (click | hover)
• iconClass : the class to use for icons (default : fa fa-star)
• editable : define if the rating is editable or not
• levelsClasses : array of levels that will be applied on container with pattern : jq-rating--{level}
• onChange : callback when the value change (params : value, api)not after the stars

Each of these options can be passed to the plugin options, or can be put directly on the element like this

<span data-jq-rating
        data-jq-rating-{option-with-dash-as-separator}="{value}"
        data-jq-rating-stars-count="12"
        data-jq-rating-icon-class="fa fa-user">
  </span>

Attributes

jq-rating provide some attributes that you can use to display informations where you want in your html

• data-jq-rating-stars : This attribute tell where to inject the stard
• data-jq-rating-grade : This tell where to inject the value. Can be applied also on input or textarea

If the attribute data-jq-rating-stars is not present, the stard will be injected directly on the element on witch the plugin is instanciated

Classes

These are the diferent classes that are applied

• jq-rating : The container
  • jq-rating--level-xlow : Applied on the container when the rating level is extra-low
  • jq-rating--level-low : Applied on the container when the rating level is low
  • jq-rating--level-medium : Applied on the container when the rating level is medium
  • jq-rating--level-high : Applied on the container when the rating level is high
  • jq-rating--level-xhigh : Applied on the container when the rating level is exta-high
  • jq-rating--editable : Applied on the container when the rating is editable
• jq-rating-group : The group of stars
  • jq-rating-group--hover : The group of stars that will be active (the width of this element will be set by the plugin)
  • jq-rating-group--interaction : The group of stars used only for interaction. This group shares the --hover class but a color:transparent; is set on each stars in this group
• jq-rating-star : The star that contain a "i" tag
  • jq-rating-star--active : Applies on the stars that are active

Updating a form input

It can be usefull to be able to update a form input with the value of an editable rating. This is how you can do this

<form name="myForm" action="#" method="POST">

   <span data-jq-rating
      data-jq-rating-value="4.5">
      <span data-jq-rating-stars></span>
      <input type="text" data-jq-rating-grade />
   </span>

</form>

The attribute data-jq-rating-grade will take car of updating the field value accordingly. This works in two ways, mean that if you update the field, the rating will update itself.