RateIt

# RateIt plugin

## Prerequisites

In order to use RateIt you'll need:

- jQuery 1.6.0 or newer.
- jquery.rateit.min.js, rateit.css, delete.gif, star.gif - Download RateIt
- Place a reference to the rateit.css stylesheet into the page head.
- Place a script reference to jquery.rateit.js before your </body> tag.

## Options

Go to the RateIt project homepage to view the documentation.

## Examples

- ### 1a) Basic usage

                  <div class="rateit">
                  </div>

- ### 1a) Basic usage (inline element)

                  <span class="rateit">
                  </span>

- ### 2a) Progressive enhancement (using input[type=range])

                  <input type="range" min="0" max="7" value="0" step="0.5" id="backing2">
                  <div class="rateit" data-rateit-backingfld="#backing2"></div>

- ### 2b) Progressive enhancement (using select)

                  <select id="backing2b">
                      <option value="0">Bad</option>
                      <option value="1" selected="selected">OK</option>
                      <option value="2">Great</option>
                      <option value="3">Excellent</option>
                  </select>
                  <div class="rateit" data-rateit-backingfld="#backing2b"></div>

- ### 2c) Progressive enhancement (using select), and overriding min value

                  <select id="backing2c">
                      <option value="1">Bad</option>
                      <option value="2">OK</option>
                      <option value="3">Great</option>
                      <option value="4">Excellent</option>
                  </select>
                  <div class="rateit" data-rateit-backingfld="#backing2c" data-rateit-min="0"></div>

- ### 3) Readonly and preset value

                      <div class="rateit" data-rateit-value="2.5" data-rateit-ispreset="true" data-rateit-readonly="true"></div>

- ### 4) More settings

                  <input type="range" value="4" step="0.25" id="backing4">
                  <div class="rateit" data-rateit-backingfld="#backing4" data-rateit-resetable="false"  data-rateit-ispreset="true"
                      data-rateit-min="0" data-rateit-max="10">
                  </div>

- ### 5) Javascript interaction

                  <div class="rateit" id="rateit5" data-rateit-min="2">
                  </div>
                  <div>
                      <span id="value5"></span>
                      <span id="hover5"></span>
                  </div>

                  <script type="text/javascript">
                      $("#rateit5").bind('rated', function (event, value) { $('#value5').text('You\'ve rated it: ' + value); });
                      $("#rateit5").bind('reset', function () { $('#value5').text('Rating reset'); });
                      $("#rateit5").bind('over', function (event, value) { $('#hover5').text('Hovering over: ' + value); });
                  </script>

- ### 6) Javascript invocation

                  <input type="hidden" id="backing6">
                  <div id="rateit6">
                  </div>

                  <script type="text/javascript">
                      $(function () { $('#rateit6').rateit({ max: 20, step: 2, backingfld: '#backing6' }); });
                  </script>

- ### 7a) Styling

  You can change the styles of the plugin in a two ways.

  - You can change change the star.gif and delete.gif pictures (and perhaps the default starwidth, and starheight values in the javascript file). This will change the style everywhere.
  - You can change individual items, by adding a stylesheet with a few rules.
  Here I've opted for the second option.

  #### Inline code

                  <div class="rateit bigstars" data-rateit-starwidth="32" data-rateit-starheight="32"></div>

  #### Style sheet

                  div.bigstars div.rateit-range
                  {
                      background: url(star-white32.png);
                      height: 32px;
                  }

                  div.bigstars div.rateit-hover
                  {
                      background: url(star-gold32.png);
                  }

                  div.bigstars div.rateit-selected
                  {
                      background: url(star-red32.png);
                  }

                  div.bigstars div.rateit-reset
                  {
                      background: url(star-black32.png);
                      width: 32px;
                      height: 32px;
                  }

                  div.bigstars div.rateit-reset:hover
                  {
                      background: url(star-white32.png);
                  }

- ### 7b) More styling

  Here we use one big image (actually 3), with different dimensions. Not very pretty, but it conveys the message I hope.

  #### Inline code

      <div class="rateit antenna" data-rateit-starwidth="11" data-rateit-starheight="25"></div>

  #### Style sheet

      div.antenna div.rateit-range
      {
          background: url(antenna-black.png) no-repeat;
          height: 25px;
      }

      div.antenna div.rateit-hover
      {
          background: url(antenna-yellow.png) no-repeat;
      }

      div.antenna div.rateit-selected
      {
          background: url(antenna-red.png) no-repeat;
      }

- ### 7c) SVG icons

  Since SVG can be set as a background image (either through setting the URL to an svg file or by using the Data URI scheme), we can use it as an image inside our RateIt plugin.
  This could allow us even to create the image on the fly, by rendering the SVG server-side, or by building the SVG in javascript and setting it as the source by using the Data URI scheme.

  #### Inline code

      <div class="rateit svg" data-rateit-starwidth="15" data-rateit-starheight="15"></div>

  #### Style sheet

  In the CSS file I've chosen to embed the SVG image using the Data URI scheme.

      div.svg div.rateit-range {
        background: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxzdmcgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB3aWR0aD0iMTVweCIgaGVpZ2h0PSIxNXB4Ij4NCiAgPHRleHQgeD0iMCIgeT0iMTUiIGZpbGw9ImJsYWNrIiBmb250LXNpemU9IjE4Ij7inKY8L3RleHQ+DQo8L3N2Zz4=') /*star-normal.svg*/;
        *background: url(star-normal.svg); /* For IE 6 and 7 */
      }
      div.svg div.rateit-hover {
        background: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxzdmcgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB3aWR0aD0iMTUiIGhlaWdodD0iMTUiPg0KICA8dGV4dCB4PSIwIiB5PSIxNSIgZmlsbD0ieWVsbG93IiBmb250LXNpemU9IjE4Ij7inKY8L3RleHQ+DQo8L3N2Zz4=') /*star-hover.svg*/;
        *background: url(star-hover.svg); /* For IE 6 and 7 */
      }
      div.svg div.rateit-selected {
        background: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxzdmcgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB3aWR0aD0iMTUiIGhlaWdodD0iMTUiPg0KICA8dGV4dCB4PSIwIiB5PSIxNSIgZmlsbD0icmVkIiBmb250LXNpemU9IjE4Ij7inKY8L3RleHQ+DQo8L3N2Zz4=') /*star-selected.svg*/;
        *background: url(star-selected.svg); /* For IE 6 and 7 */
      }
      div.svg div.rateit-preset {
        background: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxzdmcgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB3aWR0aD0iMTAwJSIgaGVpZ2h0PSIxMDAlIj4NCiAgPHRleHQgeD0iMCIgeT0iMTUiIGZpbGw9ImJsYWNrIiBmb250LXNpemU9IjE1Ij7inKY8L3RleHQ+DQo8L3N2Zz4=') /*star-preset.svg*/;
        *background: url(star-preset.svg); /* For IE 6 and 7 */
      }

  #### SVG file

  This SVG file shows a simple Black four-pointed star unicode glyph

      <?xml version="1.0" encoding="UTF-8" ?>
      <svg xmlns="http://www.w3.org/2000/svg" width="15px" height="15px">
        <text x="0" y="15" fill="black" font-size="18">✦</text>
      </svg>

- ### 8) RTL support

  Now we are in RTL mode. No changes needed to make this work.

- ### 9) Setting and Getting values

  All properties can also be set on the fly. Here are a few examples:

      	            <div class="rateit" id="rateit9">
                      </div>
                      <div>
                          <button onclick="alert($('#rateit9').rateit('value'))">Get value</button>
                          <button onclick="$('#rateit9').rateit('value', prompt('Input numerical value'))">Set value</button>
                      </div>
                      <div>
                          <button onclick="alert($('#rateit9').rateit('max'))">Get max value</button>
                          <button onclick="$('#rateit9').rateit('max', prompt('Input numerical value'))">Set max value</button>
                      </div>
                      <div>
                          <button onclick="alert($('#rateit9').rateit('step'))">Get step size</button>
                          <button onclick="$('#rateit9').rateit('step', prompt('Input numerical value'))">Set step size</button>
                      </div>
                      <div>
                          <button onclick="alert($('#rateit9').rateit('readonly'))">Get readonly value</button>
                          <button onclick="$('#rateit9').rateit('readonly',!$('#rateit9').rateit('readonly'))">Toggle readonly</button>
                      </div>
                      <div>
                          <button onclick="alert($('#rateit9').rateit('ispreset'))">Get ispreset value</button>
                          <button onclick="$('#rateit9').rateit('ispreset',!$('#rateit9').rateit('ispreset'))">Toggle ispreset</button>
                      </div>
                      <div>
                          <button onclick="$('#rateit9').rateit('reset')">Reset</button>
                      </div>

- ### 10) Tooltip example

  Using tooltips is easy. Just bind to the hover event, and do your thing. Shown here is the basic tooltip, but of course you can use any tooltip you'd like.

  #### Basic numbers

                  <div class="rateit" id="rateit10">
                  </div>

                  <script type="text/javascript">
                      $("#rateit10").bind('over', function (event,value) { $(this).attr('title', value); });
                  </script>

  #### Custom text

                  <div class="rateit" id="rateit10b" data-rateit-step="1">
                  </div>

                  <script type="text/javascript">
                      var tooltipvalues = ['bad', 'poor', 'ok', 'good', 'super'];
                      $("#rateit10b").bind('over', function (event, value) { $(this).attr('title', tooltipvalues[value-1]); });
                  </script>

- ### 11) AJAX example

  Most times RateIt will be used using some Ajax. There are different ways of implementing it (with/without backing field, using data-* attributes etc.)

  Server response:

  - #### Product X (id: 312)

    RateIt:

  - #### Product Y (id: 423)

    RateIt:

  - #### Product Z (id: 653)

    RateIt:

  #### Client

                 <div id="products">
                    <div style="float:right; width:350px; border:1px solid #ccc; padding:1em;">
                      <strong>Server response:</strong>
                      <ul id="response">

                      </ul>
                      </div>
                      <ul>
                          <li><h4>Product X (id: 312)</h4>
                          RateIt: <div data-productid="312" class="rateit"></div>
                          </li>
                          <li><h4>Product Y (id: 423)</h4>
                          RateIt: <div data-productid="423" class="rateit"></div></li>
                          <li><h4>Product Z (id: 653)</h4>
                          RateIt: <div data-productid="653" class="rateit"></div>
                          </li>
                      </ul>

                  </div>

                  <script type ="text/javascript">
                      //we bind only to the rateit controls within the products div
                      $('#products .rateit').bind('rated reset', function (e) {
                          var ri = $(this);

                          //if the use pressed reset, it will get value: 0 (to be compatible with the HTML range control), we could check if e.type == 'reset', and then set the value to  null .
                          var value = ri.rateit('value');
                          var productID = ri.data('productid'); // if the product id was in some hidden field: ri.closest('li').find('input[name="productid"]').val()

                          //maybe we want to disable voting?
                          ri.rateit('readonly', true);

                          $.ajax({
                              url: 'rateit.aspx', //your server side script
                              data: { id: productID, value: value }, //our data
                              type: 'POST',
                              success: function (data) {
                                  $('#response').append('<li>' + data + '</li>');

                              },
                              error: function (jxhr, msg, err) {
                                  $('#response').append('<li style="color:red">' + msg + '</li>');
                              }
                          });
                      });
                  </script>

  #### Server (ASPX) super simplified

      <%@ Page Language="C#" %>
      <%
          //Get value
          float value = float.Parse(Request.Form["value"]);
          int productID = int.Parse(Request.Form["id"]);

          Response.Write(string.Format("You voted {0} on product: {1}.<br/>Time on server: {2}", value, productID, DateTime.Now.ToString()));

      %>

- ### 12) Resizing

  Sometimes we would like to resize the rating controls (perhaps based on screen size).
  This is as easy as
  a) adding a class to the rateit control, which would change the background image.
  b) modifying the starwidth and starheigth properties.
  The alternative styling is taken from example 7a) styling.

  Pick a size:

                <div class="rateit" id="rateit12"></div>
                <p>Pick a size:
                  <select id="size_12">
                      <option data-class="" data-size="16" selected>normal</option>
                      <option data-class="bigstars" data-size="32">big</option>
                  </select>
                </p>

                <script type="text/javascript">
                  $('#size_12').change(function () {
                    var option = $(this.options[this.selectedIndex]);
                    $('#rateit12').removeClass('bigstars') //remove old class
                                  .addClass(option.data('class'))  //add new class
                                  .rateit('starwidth', option.data('size')) //change width
                                  .rateit('starheight', option.data('size')); //change height

                  });
              </script>

- ### 13) Confirmation before rating or resetting

  Sometimes we would like to ask the user to confirm his/her action, or to show some dialog box before the rating is submitted.
  We can now bind to the "beforerated" and "beforereset" events. Both events occur before the actual rating/resetting. Both events might also be cancelled, by using the `e.preventDefault()` method.

                <div class="rateit" id="rateit3"></div>

                <script type="text/javascript">
                      $('#rateit13').on('beforerated', function (e, value) {
                          if (!confirm('Are you sure you want to rate this item: ' +  value + ' stars?')) {
                              e.preventDefault();
                          }
                      });
                      $('#rateit13').on('beforereset', function (e) {
                          if (!confirm('Are you sure you want to reset the rating?')) {
                              e.preventDefault();
                          }
                      });
                 </script>