Intro

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.

Starbox 1.1

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!

Latest version: 1.1.1 05-08-08 - download

Demos

Installation

Download and include Prototype 1.6.0.2 in your header. Also add Scriptaculous 1.8.1 if you want to use the effects. To make the filesize smaller, have a look at Protopacked. It contains compressed versions of Prototype and Scriptaculous. You can have the required files, Prototype and effects.js, starting at 28kb. After both are included, add Starbox.

<script type='text/javascript' src='js/prototype.js'></script>
<script type='text/javascript' src='js/scriptaculous.js?load=effects'></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/',

How to use

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

Styling

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; }

Tutorials

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.

When 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.

Let'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.

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

Download

Download : Starbox 1.1.1

Note: When updating, make sure to replace all files.

Changelog

Showing the latest changelog entries

*1.1.1* (August 5-2008)

* Image path can now be an absolute url starting with 'http(s)://' or '/'.

*1.1.0* (April 1-2008)

* Added hidden input fields, that get submitted with a regular form post.
  Now you can sumbmit a serie of starboxes at once using these input fields.

* Fixed a bug where the mouseout even was checked for twice.


*1.0.0 - 1.0.1* (March 28-2008)

* Added example code and demonstrations to show custom event usage.

* Simplified rating using event.memo, besides using onRate you can now 
  use event.memo.rating etc. on the starbox:rated custom event.

* More custom events added:
  starbox:changed will trigger on hovering stars
  starbox:left will trigger when you leave the starbox

* Fixed a bug to get valid XHTML markup

* Mouseleave event used instead of mouseout

* Refactoring for speed

* Allowed renaming starbox.js, as long as the format stays starbox(..).js(?..)


*0.3.0.4* (December 17-2007)

* Fix IE sourceIndex bug on mouseleave


*0.3.0.2* (December 13-2007)

* Fixed info.identity

* Added info.rerated


*0.3 - 0.3.0.1*  (December 11-2007)

* Fixed mouseout event for Opera

* Made it possible to rerate Starboxes.

* Added rated and rerate options. rated indicates your previously
  cast vote and rerate allows you to change this vote.

* info.rating became info.rated, this breaks backwards compatibility
  but is the prefered name in combination with rerating, since
  info.rated better indicates what and if there was voted

* Better demonstrations including callbacks

* Effect on ghost when available

* Added custom event 'starbox:rated'

* Improved the CSS model to make the styling easier.
  Status can be styled using: .hover, .rated, .locked
  .indicator and .ghost are added inside .starbox

* Added ghosting option, a colorbar tracking the average

* Added buildQueue, Starboxes are now build in sets to speed up initial load
  Starboxes with the same overlay image become a set and wait together
  for their image to be cached, this minimized calls to the server

* Refactoring: improved events, mouseleave instead of mouseout and some cleanup
  to the build process.


*0.2* (November 2007)

* Added image caching

* Rewrite to Prototype 1.6

Contact

Use the Starbox Forum for support related questions, feedback, feature requests and bug reports.

For anything non-support related you can contact me at nick@nickstakenburg.com. Please use the forum to get support.

rating, stars, prototype, scriptaculous, ajax, javascript, web2.0 Creative Commons by-nc-nd License