jQuery Starbox clone
Switch branches/tags
Nothing to show
Clone or download
sabberworm Update jstarbox.css
Prevent a case of rounding error where the bar would sometimes visibly surpass the button width if the mouse pans slowly out the back…
Latest commit 21acb8a Sep 5, 2016
Permalink
Failed to load latest commit information.
css Update jstarbox.css Sep 5, 2016
images made image name consistent, Jan 20, 2011
Readme.md Update Readme.md Nov 10, 2014
jstarbox.js Merge commit '94e508d' Jan 25, 2011

Readme.md

jQuery Starbox clone

This is an implementation of rating stars on top of jQuery. It follows the philosophy of the Prototype/Scriptaculous Starbox plugin but is not quite as sophisticated. It does not currently work well on IE 6!

But there are some great things about it: it is quite small, does not produce massive amounts of inline styles and is mostly compatible with existing css for the Prototype Starbox. Just try it!

Usage

Have an empty element ready. Include the js and css files and you’re good to go:

$(element).starbox({
	average: 0.42,
	changeable: 'once',
	autoUpdateAverage: true,
	ghosting: true
});

Theming

Have your own css file included after the jstarbox.css file and override the following styles:

/* Image(s) */
.starbox .stars .star_holder .star {
	background-image: url('../path/to/jstarbox/images/5-small.png'); /* or any other image */
	width: 17px; /* make sure to use your image’s dimensions here */
	height: 17px;
}

/* Colours */
.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; }

jStarbox will also assign a class “star-#” (starting at 0) to each star used so you can use this to assign different images to the individual stars.

Config

The value always ranges from 0.0 to 1.0.

There are several configuration options:

average (float 0…1)

The option “average” sets the initial/fixed value of the jStarbox. It is called “average” because that’s what the original Starbox calls it. It represents the “stuck” value of the Starbox; the one the stars return to when stopped hovering.
Default: 0.5

stars (unsigned integer)

This sets how many stars will be shown.
Default: 5

buttons (unsigned integer | false)

This sets how many clickable areas there will be. It is usually the same as the number of stars or double that (half-star ratings). You can also set this to false to allow any value between 0 and 1 as a rating.
Default: 5

ghosting (boolean)

Whether to show a ghost of “average” value when hovering.
Default: false

changeable (boolean | string)

Whether the user is allowed to hover over the rating and change it. Can also be set to "once" to deny rating after the first time. Note that this will only actually change the value if it’s returned from the starbox-value-changed event handler or if “autoUpdateAverage” is true.
Default: true

autoUpdateAverage (boolean)

Whether to automatically update the “average” with the new value after the user is done rating without the need for the starbox-value-changed event.
Default: false

Methods

Methods can be called using jQuery(element).starbox("methodName", arguments…).

destroy()

Clears the element that was used to create the starbox and removes all used event handlers.

getValue()

Returns the currently displayed value. Note that this is not always the current average: when hovering over the element, the current value can be different. To get the current “average”, use .starbox("getOption", "average").

setValue(value)

Sets the current value (see above). Can be useful for animation/display/show purposes. Use .starbox("setOption", "average", value) to set the current average.

getOption(name)

Returns an option of the options hash. Can also be used to get the current “stuck” value, the current average.

setOption(name, value)

Can be used to set options after initialisation. All configuration options can be re-set after initialisation.

markAsRated()

This will add the rated class so that this starbox will appear as rated. The rated class is added automatically when using autoUpdateAverage.

Events

Add event handlers using jQuery(element).bind('event-name', function(event, value) {…}).

starbox-value-changed

The “starbox-value-changed” event is fired after the user has clicked to rate. The handler is given the rated value as the first parameter after the event. Return a value here to set it as the new average.

This handler is a great choice to make an Ajax call. Note however, that most Ajax calls are asynchronous so you won’t be able to use the result directly to return from the handler. You can, however, set a new average later:

element.starbox({
	average: 0.33,
	changeable: 'once'
}).bind('starbox-value-changed', function(event, value) {
	jQuery.getJSON('/my/action', {rating: value}, function(data) {
		if(!data.error) {
			element.starbox('setOption', 'average', data.result);
		}
	});
});

starbox-value-moved

Is triggered whenever the user has moved the mouse cursor. This does not always represent a change in the visible value though this behaviour might change in the future.

Curiousities

License

jStarbox is freely distributable under the terms of an MIT-style license.

Rounding

There is no rounding of the initial average. If you want a nice full-star (or half-star) value, round it yourself first (you know how to do that!).

Images

The philosophy follows that of the original Starbox which means it uses semi-transparent images under whose it displays bars with the same height and an arbitrary length (representing the rating). These bars are relatively easily stylable using background colors (or even images). The only drawback (I can think of) is that Starboxes don’t work on non-unicolor backgrounds (at least not if you don’t exactly know which part of the background they’re going to land on) and require new images for non-white unicolor backgrounds.