Default
You need just to have a div to build the Raty.
<div></div>
$('div').raty();
Score
Used when we want to start with a saved rating.
$('div').raty({ score: 3 });
Score callback
If you need to start you score depending of a dynamic value, you can to use callback for it.
You can pass any value for it, not necessarily a data- value. You can use a field value for example.
<div data-score="1"></div>
$('div').raty({
score: function() {
return $(this).attr('data-score');
}
});
Score Name
Changes the name of the hidden score field.
$('div').raty({ scoreName: 'entity[score]' });
Number
Changes the number of stars.
$('div').raty({ number: 10 });
Number callback
You can receive the number of stars dynamic using callback to set it.
<div data-number="3"></div>
$('div').raty({
number: function() {
return $(this).attr('data-number');
}
});
Number Max
Change the maximum of start that can be created.
$('div').raty({
numberMax : 5,
number : 100
});
Read Only
You can prevent users to vote. It can be applied with or without score and all stars will receives the hint corresponding of the selected star.
Stop the mouse over the stars to see:
$('div').raty({ readOnly: true, score: 3 });
Read Only callback
You can decide if the rating will be readOnly dynamically returning true of false on callback.
$('div').raty({
readOnly: function() {
return 'true becomes readOnly' == 'true becomes readOnly';
}
});
No Rated Message
If readOnly is enabled and there is no score, the hint "Not rated yet!" will be shown for all stars. But you can change it.
Stop the mouse over the star to see:
$('div').raty({
readOnly : true,
noRatedMsg : "I'am readOnly and I haven't rated yet!"
});
Half Show
You can represent a float score as a half star icon.
This options is just to show the half star. If you want enable the vote with half star on mouseover, please check the option half.
The round options showed belows is just for the icon, the score keeps as float always.
Enabled
The round rules are:
- Down: score <= x.25 the star will be rounded down;
- Half: score >= x.26 and <= x.75 the star will be a half star;
- Up: score >= x.76 the star will be rounded up.
$('div').raty({ score: 3.26 });
Disabled
The rules becomes:
- Down: score < x.6 the star will be rounded down;
- Up: score >= x.6 the star will be rounded up;
$('div').raty({
halfShow : false,
score : 3.26
});
Round
You can customize the round values of the halfShow option.
We changed the default interval [x.25 .. x.76], now x.26 will round down instead of to be a half star.
Remember that the full attribute is used only when halfShow is disabled.
You can specify just the attribute you want to change and keeps the others as default.
$('div').raty({
round : { down: .26, full: .6, up: .76 },
score : 3.26
});
Half
Enables the half star mouseover to be possible vote with half values.
If you want to vote with more precison than half value, please check the option precision.
$('#star').raty({ half: true });
Star Half
Changes the name of the half star.
$('div').raty({
half : true,
starHalf : 'fa fa-fw fa-star-half'
});
Click
Callback to handle the score and the click event on click action.
You can mension the Raty element (DOM) itself using this.
$('div').raty({
click: function(score, evt) {
alert('ID: ' + $(this).attr('id') + "\nscore: " + score + "\nevent: " + evt);
}
});
Hints
Changes the hint for each star by it position on array.
If you pass null, the score value of this star will be the hint.
If you pass undefined, this position will be ignored and receive the default hint.
$('div').raty({ hints: ['a', null, '', undefined, '*_*']});
Star Off and Star On
Changes the name of the star on and star off.
$('div').raty({
starOff : 'fa fa-fw fa-bell-o',
starOn : 'fa fa-fw fa-bell'
});
Cancel
Add a cancel button on the left side of the stars to cacel the score.
Inside the click callback the argument code receives the value null when we click on cancel button.
$('div').raty({ cancel: true });
Cancel Hint
Like the stars, the cancel button have a hint too, and you can change it.
Stop the mouse over the cancel button to see:
$('div').raty({
cancel : true,
cancelHint : 'My cancel hint!'
});
Cancel Place
Changes the cancel button to the right side.
$('div').raty({
cancel : true,
cancelPlace : 'right'
});
Cancel off and Cancel On
Changes the on and off icon of the cancel button.
$('div').raty({
cancel : true,
cancelOff : 'fa fa-fw fa-minus-square-o',
cancelOn : 'fa fa-fw fa-minus-square'
});
Icon Range
It's an array of objects where each one represents a custom icon.
The range attribute is until wich position the icon will be displayed.
The on attribute is the active icon.
The off attribute is the inactive icon.
$('div').raty({
iconRange: [
{ range: 1, on: 'fa fa-fw fa-cloud', off: 'fa fa-fw fa-circle-o' },
{ range: 2, on: 'fa fa-fw fa-cloud-download', off: 'fa fa-fw fa-circle-o' },
{ range: 3, on: 'fa fa-fw fa-cloud-upload', off: 'fa fa-fw fa-circle-o' },
{ range: 4, on: 'fa fa-fw fa-circle', off: 'fa fa-fw fa-circle-o' },
{ range: 5, on: 'fa fa-fw fa-cogs', off: 'fa fa-fw fa-circle-o' }
]
});
You can use an interval of the same icon jumping some number.
The range attribute must be in an ascending order.
If the value on or off is omitted then the attribute starOn and starOff will be used.
$('div').raty({
starOff : 'fa fa-fw fa-circle-o',
iconRange : [
{ range : 1, on: 'fa fa-fw fa-cloud' },
{ range : 3, on: 'fa fa-fw fa-cloud-upload' },
{ range : 5, on: 'fa fa-fw fa-cogs' }
]
});
Now we have all off icons as fa fa-fw fa-circle-o, icons 1 and 2 as fa fa-fw fa-cloud, icon 3 as fa fa-fw fa-cloud-upload and icons 4 and 5 as fa fa-fw fa-cogs.
Size
The size of the icons are controlled by the css property font-size as all icons are text. The plugin tries to calculate the font size automatically, but should that fail, you can provide a size (in pixels) with the size option.
It does not change the icon size, just the calculation used to find the half position.
$('div').raty({
half : true,
size : 24
});
Width
By default Raty does not set a width on its container. But if for some reason the width does not fit the layout, you can change it manually.
$('div').raty({ width: 150 });
Target
Some place to display the hints or the cancelHint.
$('div').raty({
cancel : true,
target : '#hint'
});
Your target can be a div.
<div id="hint"></div>
Your target can be a text field.
<input id="hint" type="text" />
Your target can be a textarea.
<textarea id="hint"></textarea>
Your target can be a select.
<select id="hint">
<option value="">--</option>
<option value="bad">bad</option>
<option value="poor">poor</option>
<option value="regular">regular</option>
<option value="good">good</option>
<option value="gorgeous">gorgeous</option>
</select>
Target Type
You have the option hint or score to chosse.
You can choose to see the score instead the hints using the value score.
For the cancel button the value is empty.
$('div').raty({
cancel : true,
target : '#hint',
targetType : 'number'
});
Target Keep
If you want to keep the score into the hint box after you do the rating, turn on this option.
$('div').raty({
cancel : true,
target : '#hint',
targetKeep : true
});
Target Text
Normally all target is keeped blank if you don't use the targetKeep option.
If you want a default content you can use this option.
$('div').raty({
target : '#hint',
targetText : '--'
});
Target Format
You can choose a template to be merged with your hints and displayed on target.
$('div').raty({
target : '#hint',
targetFormat : 'Rating: {score}'
});
Mouseover
You can handle the action on mouseover.
The arguments is the same of the click callback.
The options target, targetFormat, targetKeep, targetText and targetType are abstractions of this callback. You can do it by yourself.
$('div').raty({
mouseover: function(score, evt) {
alert('ID: ' + $(this).attr('id') + "\nscore: " + score + "\nevent: " + evt);
}
});
Mouseout
You can handle the action on mouseout.
The arguments is the same of the mouseover callback.
$('div').raty({
mouseout: function(score, evt) {
alert('ID: ' + $(this).attr('id') + "\nscore: " + score + "\nevent: " + evt);
}
});