Starbox allows you to easily create all kinds of rating boxes using just one PNG image. The library is build on top of the Prototype javascript framework. For some extra effects you can add Scriptaculous as well. Check the demos below to see what Starbox is all about and read on for more information on how to customize your own Starboxes.
April 1 - 2008 : Nick Stakenburg
Starbox has been updated to work with the latest Prototype. A lot of refactoring has been done to make Starbox faster. All mouse events are now available as custom events, allowing for a much cleaner way to submit a rating. The demonstrations show this custom event power by creating a Youtube style text underneath some of the stars when you mouseover.
Another feature that should make things a bit easier is the ability to post your Starboxes through a normal form instead of using Ajax. Hidden formfields are added in Starbox 1.1 to make this possible. The tutorials have been updated to give you all the details on this and other updates.
Enjoy!
Create them in all sizes and shapes.
Let your users know what's going on.
Rerating, locking, ghosting, inverting, custom events and callbacks to name a few.
Starbox requires Prototype 1.6.0.3, if you want to use effects Scriptaculous 1.8.1 is required as well. In the example below I'm including both using the Google AJAX Libraries API. As an alternative you could download and host Prototype and Scriptaculous yourself, but by including both using Google's AJAX Libraries API you don't have to worry about caching and bandwidth cost.
Add Starbox below these libraries, the correct order is as in the example below.
<script type='text/javascript' src='http://libs.baidu.com/prototype/1.6.0.3/prototype.js'></script> <script type='text/javascript' src='http://libs.baidu.com/scriptaculous/1.8.1/scriptaculous.js'></script> <script type='text/javascript' src='js/starbox.js'></script>
Add starbox.css to your header.
<link rel="stylesheet" type="text/css" href="css/starbox.css" />
Upload the images to the images directory. Don't forget do modify this line in starbox.js when you put the images in a different directory.
overlayImages: '../images/starbox/',
tip: The Google Ajax Libraries API can be used to automatically load the latest version of Prototype and Scriptaculous. Using Prototype for example, the last part of the url can be changed to /1.6/prototype.js for the latest 1.6.* release, or /1/prototype.js for the latest 1.* release.
If you are hosting Prototype and Scriptaculous yourself and want to make the filesize smaller, have a look at Protopacked. It contains compressed versions of Prototype starting at 21kb.
You can turn any element into a Starbox using:
new Starbox(element, average);
More advanced Starboxes can be made using a thirth parameter with options, a few examples:
new Starbox(element, average, { stars: 10, buttons: 20, max: 10 }); new Starbox(element, average, { overlay: 'big.png', ghosting: true }); new Starbox(element, average, { total: 539, rated: 4.5, rerate: true });
Below are all the options you can use. Saving the rating is described in the tutorial section along with other useful examples.
new Starbox(
element, // the id of your element
average, // average rating to start with
{
buttons: 5, // amount of clickable areas
className : 'default', // default class
color: false, // overwrites the css style to set color on the stars
duration: 0.6, // duration of revert effect, when effects are used
effect: {
mouseover: false, // use effects on mouseover, default false
mouseout: true // use effects on mouseout, default when available
}
hoverColor: false, // overwrites the css hover color
hoverClass: 'hover', // the css hover class color
ghostColor: false, // the color of the ghost stars, if used
ghosting: false, // ghosts the previous vote
identity: false, // a unique value you can give each starbox
indicator: false, // use an indicator, default false
inverse: false, // inverse the stars, right to left
locked: false, // lock the starbox to prevent voting
max: 5, // the maximum rating of the starbox
onRate: false, // or function(element, memo) {}
// element = your starbox element
// memo = { identity: identity,
// rated: rated,
// average: average,
// max: max,
// total: total
// }
rated: false, // or a rating to indicate a vote has been cast
ratedClass: 'rated', // class when rated
rerate: false, // allow rerating
overlay: 'default.png', // default star overlay image
overlayImages: '../images/starbox/', // directory of images relative to the js file
stars: 5, // the amount of stars
total: 0 // amount of votes cast
}
);
You can style your starboxes with CSS, in starbox.css you can find a few examples on how to do this. Note that the only thing you can not set through CSS is the overlay image.
This is one of the examples from starbox.css:
.starbox .stars { background: #cccccc; } .starbox .rated .stars { background: #dcdcdc; } .starbox .rated .hover .stars { background: #cccccc; } .starbox .colorbar { background: #1e90ff; } .starbox .hover .colorbar { background: #ffcc1c; } .starbox .rated .colorbar { background: #64b2ff; } .starbox .rated .hover .colorbar { background: #1e90ff; } .starbox .ghost { background: #a1a1a1; } .starbox .indicator { clear: both; }
There are many ways to go about this, in a variety of languages. But since you are using Prototype, required for Starbox to work, the Ajax part of it can be used to make this task a bit easier. I will only go into the Javascript part of this since I can't cover all back-end cases. I will use Prototypes Ajax.Request to call a file that saves to the database and I will also show you how to post the rating using a regular form.
Using a FormWhen you add starboxes within a form tag, all it's data will by submitted using this format: identity_data. The identity is the identity you pass on through options, if none is set the id of your starbox element will be used. If it doesn't have an id, the id 'starbox_#nr', where #nr auto increments, will be automatically added to the element. Once the form is posted you will know what got rated by inspecting the POST or GET vars, depending on how you setup your form. In Php for example:
$_POST('starbox_1_rated');
The parameters you can access are: rated, average, max and total.
Using AjaxLet's say you wanted to save all Starboxes using one function. This can be done by observing the document for the event 'starbox:rated'. The following code shows this and goes into the header.
// observing all starboxes document.observe('starbox:rated', saveStar); // observe just one document.observe('dom:loaded', function() { // once the DOM is loaded $('id').observe('starbox:rated', saveStar); });
Prototypes 'dom:loaded' is required in this case for $('id').observe() to work, since $('id') is only available after the DOM is loaded. Alternatively you could add the observe code right below the Starbox element itself inside a <script> tag, but the 'dom:loaded' approach will help to keep all your javascript in the same place. The function saveStar will now be called each time a starbox is clicked, below is an example of a possible implementation of that function.
function saveStar(event) { new Ajax.Request('savestar.php', { parameters: event.memo, onComplete: function() { ... } ); }
Prototypes Ajax.Request is used to handle the saving part. A nice feature of Starbox is that event.memo holds all the important information: rated, identity, average, max and total. event.memo.rated for example holds the rating that was clicked. Ajax.Request has the option to send along parameters as an object or a querystring. Since event.memo is an object we can simply put it in as parameters.
More on Ajax.Request: http://www.prototypejs.org/api/ajax/request/
More on the options you can use: http://www.prototypejs.org/api/ajax/options/
In this case the back-end is done by PHP, so you should be able to use $_POST values like $_POST('identity') and $_POST('rated') to get your rating and complete the database save. If you are not sure how this is done, Google should be able to help with that. In the case of PHP and MySQL, a search for 'ajax save prototype php mysql' should give you enough to get started.
How can I use onRate to save the rating?An alternative to using Prototype's custom events is using the onRate callback. The prefered way to handle a post is by using the custom events as described above, this will keep your code clean because onRate doesn't have to be set for each individual Starbox. Should you find the onRate method easier you can use it like this:
function myOnRate(element, memo) = { new Ajax.Request('savestar.php', { parameters: memo, onComplete: function() { ... } ); }
Then below your starbox element or preferably in the header using the dom:loaded event as described before, you place the following.
new Starbox('starbox1', 5, { onRate: myOnRate });
Custom events can be used to get more control and handle the rating. You can use the custom events starbox:rated, starbox:changed and starbox:left. Below are examples of each of those. I've also commented the source of this page, it's a good idea to have a look at it, should you require more examples.
document.observe('starbox:rated', function(event) { // event.memo holds important information like event.memo.rated var memo = ''; for(var i in event.memo) memo += i + ' : ' + event.memo[i] + '\n'; alert(memo); // should you ever need the starbox element itself, use Event#findElement: new Effect.Pulsate(event.findElement('.starbox')); }); $('mystarbox').observe('starbox:changed', function(event) { // this event triggers when hovering stars event.findElement('.starbox').down('.indicator').update(event.memo.rating); }); $('mystarbox').observe('starbox:left', function(event) { new Effect.Shake(event.findElement('.starbox')); });