Object.Event

Control.Rating

Unobtrusive CSS based rating widget for Prototype.js

Tutorial
API
Resources

Introduction

Control.Rating attaches to any div, span or table cell on your page in one line of code to create a fully customizable CSS based ratings widget. Each control can optionally post an Ajax request when it's value is set, or can interact with text inputs or select elements that are already on your page. It uses four (customizable) class names to determine each link's state:

rating_off
rating_half
rating_on
rating_selected

Note that you'll need to implement your own styles. Feel free to take the CSS and background image from this page as an example.

Example	Options
	{}
	{value: 2.4}
	{value: 4, rated: true}
	{value: 6, rated: false, max:9}
	{value: 6, rated: false, min: 3, max: 12, multiple: true, reverse: true}
	{input: 'rating_seven_input', multiple: true}
	{input: 'rating_eight_select', multiple: true}

Example Code

<div id="rating_one" class="rating_container"></div>
<div id="rating_two" class="rating_container"></div>
<script>
    var rating_one = new Control.Rating('rating_one');
    var rating_two = new Control.Rating('rating_two',{
        max: 6,
        updateUrl: 'http://my_ajax_handler',
        afterChange: function(value){
            alert(value);
        }
    });
    rating_two.setValue(2);
</script>

How to Read the API Table

Anything in the method and property lists that ends with "()" is a method, and anything that doesn't is a property. All events are specifiable in the options hash, or via "observe()" if Object.Event has been included on the page before Control.Rating was. In a method signature, each argument is separated by a comma, if the words are lower case it refers to the data type and gives a hint to what it is used for, if there is an upper case word it refers to the class of object that must be used. Arguments with [square brackets] around them are optional.

Class Methods and Properties

Return	Name	Description
array	instances	All created Control.Rating instances.
false \|\| Control.Rating	findByElementId()	Find any Control.Rating instance who's container has an id.

Instance Methods and Properties

Return	Name	Description
Control.Rating	initialize(mixed element_id [,options Hash])	element_id can be a string id or Element object.
void	setValue(int value [,boolean rated [,boolean prevent_callbacks]])	Set the value of the ratings widget and redraw it. Setting force_selected to true will draw the input as if it has been rated, but will not mark it as rated in the options hash. Setting prevent_callbacks to true will prevent the afterChange event and optional Ajax request from firing.
void	disable()	Removes all event handlers from the links.
Element	container
int	value

Options

Type	Name	Default	Description
float	value	null	Default value, gets set into the value property of the instance and discarded from the options hash. Anything that is not a whole number (i.e. 3.1) results in a the 'half' class name being assigned.
int	min	1	Minimum value.
int	max	5	Maximum value.
boolean	rated	false	Has the widget already been rated.
mixed	input	false	false or string id, or Element object of a hidden, text or select input.
boolean	reverse	false	Display the links in reverse order.
boolean	capture	true	Stop the click event on each rating to propagate.
boolean	multiple	false	Can the user rate multiple times.
Hash	classNames	{off: 'rating_off', half: 'rating_half', on: 'rating_on', selected: 'rating_selected'}	Hash of state dependent class names.
mixed	updateUrl	false	false or string URL to post an Ajax request to when the value changes.
string	updateParameterName	'value'	The name of the POST key that will contain the value.
function	afterChange	function(){}	Called after the value changes.

RSS Changelog

Is available at http://livepipe.net/projects/control_rating/changelog.rss

Downloads & SVN

The Control Suite subversion repository is available at: svn://livepipe.net/control_suite/

Other Resources

Have you written a post or article about Control.Tabs? Please contact me!

LivePipe™