type: widget

release: 0.0

status: in planning

documentation: url || N/A

demo: url || N/A

 

 

---

 

1 - Description:

 

A star rating widget is used to display and collect user input on their rating of an object. Typically, these contain a 5 star scale and a "do not like" option, but these can have any number of steps. The visual design for the icons should be flexible so a developer can swap stars for another icon (ex. fork icons for rating recipes or heart icons for rating people). The stars can have two different styles/colors to to display default information (like Netflix's predicted rating for you) and the user's actual input.

 

There are a few jQuery plug-ins for this already that we could consider including for this:

http://dev.jquery.com/~john/plugins/rating/

http://www.fyneworks.com/jquery/star-rating/

http://php.scripts.psu.edu/rja171/widgets/rating.php

http://www.komodomedia.com/blog/2007/01/css-star-rating-redux/

http://sandbox.wilstuckey.com/jquery-ratings/

 

Orkan made a rating plugin based on jquery ui :

http://www.uneek.eu/layout/jquery.rating.js

 

---

 

2 - Visual Design:

 

 

---

 

 

3 - Functional Specifications/Requirements:

     The markup and its interpretation

     This plugin should used a select tag as initial markup. Each options  tags would be transform into a star with corresponding value (see below for example).

     A select tag degrades well on browsers with javascript disabled or unavailable.

     If the select tag has a disabled attribute then the plugin should automatically received editable=false option at initialisation.

 

     Option tag with "0" as value if present should be treated as a special one and rendered as a cancel symbol instead of a star.

     If an option has a selected="selected" attribute then the plugin should take it's initial value from the one corresponding to the selected option.

 

     Plugin Options

     - editable (bool): should reflect the disabled state of the original select element. If false no interaction ha to be possible without scripting, else clicking a star must set the      corresponding select > option selected.

     - autosubmit (bool): If true then a user click on a star (or cancel button) should submit the parent form.

     - hidden (jquery selector): should point to other elements that have to be hide when the star rating is rendered. (exemple hidding the corresponding submit button of the orignial select)

     - beforeclick (callback): may be an optional event to trigger to let user block the change.

     - beforesubmit (callback): may be an optional event to trigger to let user stop submitting the form (with option autosubmit=true).

 

---

 

4 - Markup & Style:

 

     4.1 Initial markup examples

 

     <select name="myrating" id="starRating">

     <option value="0">0</option>

     <option>1</option>

     <option selected="selected">2</option>

     <option>3</option>

     <option>4</option>

 

     4.2 Recommended transformed HTML markup

 

     <div id="rating_rating" class="ui-rating">

          <a id="rating_star_rating_0" class="ui-rating-star ui-rating-cancel-empty" href="#"> </a>

          <a id="rating_star_rating_1" class="ui-rating-star ui-rating-full" href="#"> </a>

          <a id="rating_star_rating_2" class="ui-rating-star ui-rating-full" href="#"> </a>

          <a id="rating_star_rating_3" class="ui-rating-star ui-rating-empty" href="#"> </a>

          <a id="rating_star_rating_4" class="ui-rating-star ui-rating-empty" href="#"> </a>

     </div>    

 

     4.3 Accessibility recommendation

 

    (Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices) 

 

     4.4 CSS & Theme

using a background image like this here's a sample of possible css rules:  

.ui-rating .ui-rating-star{

    width:16px;

    height:16px;

    font-size:2px;

    float:left;

    text-decoration:none;

    vertical-align:bottom;

    background-image:url(star.gif);

    background-repeat:no-repeat;

}

.ui-rating-full  {

    background-position:left top;

}

.ui-rating-half  {

    background-position:left -16px;

}

.ui-rating-empty {

    background-position:left -32px;

}

.ui-rating-cancel-empty {

    background-position:left -64px;

}

.ui-rating-cancel-full {

    background-position:left -80px;

}

.ui-rating-hover {

    background-position:left -48px;

}

.ui-rating-cancel-empty.ui-rating-hover{

    background-position:left -80px;

}

 

 

    (Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.) 

 

---

 

5 - Latest version of plugin:

 

 

 

 

---

 

6 - Open issues being discussed

 

(Use this area to place things that we're hashing out like featuresand options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)

 

---