Rater

Rater is a standard rating widget for RightJS. It can work as a standalone widget, can automatically send user rates via Xhr requests, or it can work in pair with an input element as a part of a form.

Get the latest version right here

right-rater.js - minified version
right-rater-src.js - source code

All the source code of the project is available under terms of the MIT license

http://github.com/rightjs/rightjs-ui/tree/master/src/rater/

For some standard usage examples see the demo page

top ↑Features List

Can work as a standalone widget
Can work as a part of a form
Can automatically send ratings via Xhr requests
Super easy usage
Comes in a tiny single file (1.5k gzipped)

top ↑Usage Basics

The usage is super easy. Just include one of the files above onto your page. After that you will have a choice, create your rater in script like this

new Rater({url: '/boo'}).insertTo('my-conatiner');

Or you can define your rater element directly inside your page and our script will find it by the rui-rater class name and then automatically initialize it.

<div class="rui-rater" data-rater="{url:'/boo'}">
  <div class="active">&#9733;</div>
  <div class="active">&#9733;</div>
  <div>&#9733;</div>
  <div>&#9733;</div>
  <div>&#9733;</div>
</div>

This also will let you put whatever you want instead of the textual stars.

top ↑Assigned Raters

You also can assign any rater to work with any, say hidden, input elements so it was working as a part of a form. You can do that with the update option or by the assignTo() method

<form ...>
  <input type="hidden" id="the-rating" name="rating" />

  // with auto-initialization feature
  <div class="rui-rater" data-rater="{update:'the-rating}">
    ...
  </div>

  // or in script with options
  new Rater({update: 'the-rating'})
    .insertTo('the-rating', 'after');

  // or like that
  new Rater().insertTo('the-rating', 'after')
    .assignTo('the-rating');
</form>

NOTE: assignments work in both ways, when yo change the rater it will change the input element, and when you change the input element it will change the rater status.

top ↑Remote Raters

Our raters can automatically send Xhr requests when the user clicks any rating on the widget. For this purpose there are three options.

url - the url address where to send the requests
param - the param name for the rating, 'rate' by default
Xhr - additional Xhr request options if you need

So your average remote rater might look like that

new Rater({
  url: '/some/stuff/rating',
  param: 'value',
  Xhr: {
    method: 'put',
    spinner: 'spinner'
  }
});

top ↑Options List

There is a simple list of options you can use with the raters. You can pass them as a hash with the constructor, or set as a JSON hash inside of the data-rater attribute

Name	Default	Description
html	’★’	the html content of stars
size	5	the number of stars in the line
value	null	default value
update	null	an element to be assigned to
disabled	false	if it should be instantly disabled
disableOnVote	false	if it should be disabled when the user picks a value
url	null	an url to send results with AJAX
param	‘rate’	the value param name
Xhr	null	additional Xhr options

top ↑Events List

Our raters work with the following list of events. Every listener will receive two arguments, the current value and a reference to the rater object.

Name	Description
hover	when a user hovers some star with a mouse
change	when a user changes the rater value
send	when an xhr request with rating was sent

top ↑API Reference

All the Rater class instances have the following simple public API

Name	Description
setValue(value)	sets the value
getValue()	returns the value
assignTo(element)	assigns the rater to the element
send()	sends the rating via Xhr
disable()	disables the rater
enable()	enables the rater
disabled()	checks if the rater is disabled

top ↑Style Alterations

The widget structure is simple as that

<div class="rui-rater">
  <div class="active">&#9733;</div>
  <div class="active">&#9733;</div>
  <div>&#9733;</div>
  <div>&#9733;</div>
  <div>&#9733;</div>
</div>

Disabled raters will be assigned with the rui-rater-disabled class

Then as you might noticed, to simplify the things we use utf-8 symbols for the stars, so here’s a simple style snippet if you want to replace them with some images of yours

div.rui-rater div {
  text-indent: -99em;
  background: url('/images/star-off.png') no-repeat center center;
}
div.rui-rater div.active {
  background-image: url('/images/star-on.png');
}

Get it!