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.

Demos

Installation

Starbox requires Prototype 1.7, if you want to use effects Scriptaculous 1.8.3 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='https://ajax.googleapis.com/ajax/libs/prototype/1/prototype.js'></script>
<script type='text/javascript' 
src='https://ajax.googleapis.com/ajax/libs/scriptaculous/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.7/prototype.js for the latest 1.7.* release, or /1/prototype.js for the latest 1.* release.

How to use

You can turn any element into a Starbox using on of the following below the element:

new Starbox(element or id, average);

// for example
<div id="example_1"><!-- starbox will be inserted here --></div>
<script type='text/javascript'>
  new Starbox('example_1', 5);
</script>

More advanced Starboxes can be made using a thirth parameter with options, a few examples:

new Starbox('elementID', 5, { stars: 10, buttons: 20, max: 10 });
new Starbox('elementID', 5, { overlay: 'big.png', ghosting: true });
new Starbox('elementID', 5, { 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(
  'elementID',                            // the id of your element
  5,                                      // 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 Prototype's 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 variables on the server side. In Php for example:

$rated = $_POST('starbox_1_rated');

Parameters you can access are: rated, average, max and total. So the average would be available as $_POST('starbox_1_average')

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'. First a save function is required to call when a star is clicked. Below is a possible implementation of such a function.

function saveStar(event) {
  new Ajax.Request('savestar.php', {
    parameters: event.memo,
    onComplete: function(xhr) {
      // optional callback
    }
  });
}

Prototype's Ajax.Request is used to handle the saving part. A useful 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 as a querystring. Since event.memo is an object we can simply put it in as parameters as shown in the saveStar function above.

Now we need to know when the 'starbox:rated' event was fired and call the saveStar function. There are two ways to listen for the custom event, both are shown below.

// observing all starboxes
document.observe('starbox:rated', saveStar);

// observe just one
document.observe('dom:loaded', function() { // once the DOM is loaded
  $('element_id').observe('starbox:rated', saveStar);
});

Prototypes 'dom:loaded' is required in this case for $('element_id').observe to work, since the element with the 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, I recommend to put this in your header.

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 then onRate doesn't have to be set for each individual Starbox. But 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(xhr) {
      // optional callback
    }
  });
}

Then below your starbox element you place the following:

<script type='text/javascript'>
  new Starbox('starbox1', 5, { onRate: myOnRate });
</script>

Instead of placing the javascript underneath the element you can also place it in your header and wrap it with dom:loaded as described in the examples above. This makes sure the code works even though the element you reference is not yet parsed.

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

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

Changelog

Showing the latest changelog entries

*1.3.0* (July 01-2011)

* Fixed a bug that prevented Starboxes from being created after DOM load.
  [carcus88]

*1.2.2* (January 11-2011)

* Added a temporary fix to make Prototype's dom:loaded work with LABjs.
  https://github.com/sstephenson/prototype/pull/14
  [getify, brian, savetheclocktower]


*1.2.1* (November 17-2010)

* Upgrade to Prototype 1.7 and Scriptaculous 1.8.3 in preparation for IE9.


*1.2* (May 17-2009)

* Required Prototype is now 1.6.0.3, required Scriptaculous 1.8.2.

* Changed the loader to not require the script to be in the header.


*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, © 2008-2010 Nick Stakenburg