mega

Starbox – Rating stars for prototype

 


0
Posted January 29, 2013 by Bandish Patel


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

    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

    How do I save the results to a database?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.

    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 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’)

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

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

    How can I use the custom events?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'));
    });

    License

    Permission to use Starbox on your domain is required and can be obtained by paying a small fee. For non-commercial domains this will allow you to use Starbox under a Creative Commons by-nc-nd License. When you get permission for a commercial domain you may use Starbox under the terms of theCreative Commons by-nd License.

    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]
    Show extra changelog entries

Bandish Patel

 


0 Comments



Be the first to comment!


Leave a Response


(required)

Powered By Indic IME