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

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

Index

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

NameDefaultDescription
html’&#9733;’the html content of stars
size5the number of stars in the line
valuenulldefault value
updatenullan element to be assigned to
disabledfalseif it should be instantly disabled
disableOnVotefalseif it should be disabled when the user picks a value
urlnullan url to send results with AJAX
param‘rate’the value param name
Xhrnulladditional 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.

NameDescription
hoverwhen a user hovers some star with a mouse
changewhen a user changes the rater value
sendwhen an xhr request with rating was sent

top ↑API Reference

All the Rater class instances have the following simple public API

NameDescription
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');
}