What is rating.jquery

rating.jquery is a jQuery plugin which turns an old input into a nice rating element! But why bother explaining when you can see for yourself!

Installation

There are some dependencies you need in order to use rating.jquery:

• jQuery
• FontAwesome

jQuery is mandatory because rating.jquery is a jQuery extension! FontAwesome is a special kind of font which enables you to easily include a bunch of icons in your page, thus rating.jquery can use any icon from FontAwesome, giving you quite a lot of configuration options!

So, you need to include 2 CSS files

<link href="http://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
<link rel="stylesheet" href="css/rating-min.css">

Now that you included the required CSS files you also need to include 2 Javascript files, one is jQuery of course, the latter is the minified version of the plugin.

<script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
<script src="js/rating.jquery.min.js"></script>

And that's it! All you have to do now is

$('#myInput').rating();

Note that I used a CDN for FontAwesome and jQuery, you can also use a local version if you so please.

Configuration

rating.jquery was designed to be easy to use and configure, and give you enough options to make it work in most use cases. To configure rating.jquery simply pass a configuration object when calling the rating method.

default

This is the default functionality of rating.jquery

$('#example-default').rating({});

messages

The messages that are shown under the stars can be changed as follows

$('#example-messages').rating({
  messages: [
    'Please rate us',
    '1 star',
    '2 stars',
    '3 stars',
    '4 stars',
    '5 stars'
  ]
});

showLabel

defaults: true

Whether or not the messages under the stars are displayed.

$('#example-show-label').rating({
    showLabel: false
});

inline

defaults: false

If true it will display the stars container as inline-block instead of block. It's designed to be used together with showLabel as false!

Example:

$('#example-inline').rating({
    showLabel: false,
    inline: true
});

color

color defaults: #b08bd7

colorHover defaults: #7d40bc

To customize the color you need to use the color and colorHover properties.

$('#example-color').rating({
  color: '#D96E7B',
  colorHover: '#CF4656'
});

size

defaults: '20px'

You can also change the size of the stars by using the size property.

$('#example-size').rating({
  size: '30px'
});

icon

defaults: 'fa-star'

Because rating.jquery uses FontAwesome for it's icons you can choose any icon you want as well as any color! After all it's just a font.

To change the icon you can pick any icon from FontAwesome and just pass the name to the icon attribute:

$('#example-icon').rating({
  icon: 'fa-tint'
});

validationMessage

defaults: 'Please rate before you continue'

rating.jquery is compatible with HTML5 validation so it's super easy to make sure your input is valid when submitting a form. If you use HTML5 validation and there's an error it shows a nice tooltip using tipi (which is already packed with rating.jquery!). Here's an example, try submitting the form without choosing a rating:

<form action="">
  <input required type="number" id="example-validation">
  <button type="submit">submit</button>
</form>


// Javascript
$('#example-validation').rating({
    inline: true,
    showLabel: false,
    validationMessage: 'Oops! Please rate us!'
});

Note that the input uses HTML5 validation, using the required attribute.

Getting the rating value

To get the rating the user selected simply use the val method.

// Create a new rating
$('#example-get-value').rating({
    inline: true,
    showLabel: false
});

// ...
// Later on we want to get the value
$('#btn-example-get-value').click(function () {
    var val = $('#example-get-value').rating('val');
    alert(val);
});

Note that you can also do $('#example-get-value').val() and get the input's value, the difference though is that it's returned as a string, where rating's val method returns an integer.

OnChange Callback

We can easily bind a callback function to the changed event of the input, that way we can get notified whenever the selection changes.

$('#example-on-change').rating({});
$('#example-on-change').change(function () {
    alert('Value changed! Now it is ' + $(this).rating('val'));
});

Note that rating returns the element, so the example could be rewritten as

$('#example-on-change').rating({}).change(function () {
  alert('Value changed! Now it is ' + $(this).rating('val'));
});

Advanced customization using LESS

If you need even further customization you can modify rating.jquery.less to get that fine-grained tuning. It's only 20~ lines long so it's quite easy to customize to your needs. Once you are done you can simply compile it to rating-min.css and you are done!