DzRaty Yii Extension

Wrapper for jQuery Raty, a star rating plugin

Overview

DzRaty is an extension for Yii framework. It is a wrapper for jQuery Raty, a plugin developed by Washington Botelho that generates a customizable star rating.

Installation

Requirements: jQuery and Yii framework 1.0 or above (tested on 1.1.12).

Extract downloaded file to your Yii application extensions folder (default: protected/extensions).

Localization - i18n

DzRaty translates all translatable elements of jQuery Star plugin. You can place your own translation file under DzRaty/messages.

Current version contains translation files for spanish. You could simply duplicate and edit one of them.

Basic Demos

Edit mode

Using with an attribute model. weight is a sample attribute name

$this->widget('ext.DzRaty.DzRaty', array(
	'model' => $model,
	'attribute' => 'weight',
));

Using with a single input element

$this->widget('ext.DzRaty.DzRaty', array(
	'name' => 'my_rating_field',
	'value' => 3,
));

View / Read-only mode

Just adding readOnly option - Model attributte

$this->widget('ext.DzRaty.DzRaty', array(
	'model' => $model,
	'attribute' => 'weight',
	'options' => array(
		'readOnly' => TRUE,
	),
));

Just adding readOnly option - Input element

$this->widget('ext.DzRaty.DzRaty', array(
	'name' => 'my_rating_field',
	'value' => 3,
	'options' => array(
		'readOnly' => TRUE,
	),
));

Advanced Demos

Half values

Save float values and use half star icons.

$this->widget('ext.DzRaty.DzRaty', array(
	'name' => 'my_rating_field',
	'value' => 3.5,
	'options' => array(
		'half' => TRUE
	),
	'htmlOptions' => array(
		'class' => 'new-half-class'
	),
));

Cancel button

Add a button to cancel the score.

$this->widget('ext.DzRaty.DzRaty', array(
	'name' => 'my_rating_field',
	'value' => 2,
	'options' => array(
		'cancel' => TRUE,
		'cancelPlace' => 'right',
	),
));

Custom data values

Add custom data to your input field using data option

$this->widget('ext.DzRaty.DzRaty', array(
	'name' => 'my_rating_field',
	'value' => 4,
	'data' => array('Awful', 'Bad', 'Poor', 'Regular', 'Decent', 'Interesting', 'Good', 'Very good', 'Great', 'Excellent'),
));

Single value

Turn on just one star with single option

$this->widget('ext.DzRaty.DzRaty', array(
	'name' => 'my_rating_field',
	'value' => 1,
	'options' => array(
		'single' => TRUE,
	),
));

Javascript events handling

Available event callbacks: Read Only, Click, Mouseover and Mouseout

Click a star! Current score: 3
$this->widget('ext.DzRaty.DzRaty', array(
	'name' => 'my_rating_field',
	'value' => 3,
	'options' => array(
		'click' => "js:function(score, evt){ alert('Click event: score is ' + score); }",
		'mouseover' => "js:function(score, evt){ $('#score-info').html('Click a star! Current score: '+score); }",
	),
));

Custom path and icon images

Change images path and all off and on icons: cancel, star, starHalf.

$this->widget('ext.DzRaty.DzRaty', array(
	'name' => 'my_rating_field',
	'value' => 2,
	'options' => array(
		'path' => Yii::app()->request->baseUrl. '/images/raty',
		'cancel' => TRUE,
		'cancelPlace' => 'right',
	  	'half' => TRUE,
		'width' => 200,
		'starOff' => 'raty-dezero-off.png',
		'starOn' => 'raty-dezero-on.png',
		'starHalf' => 'raty-dezero-half.png',
	  	'cancelOff' => 'raty-cancel-off.png',
	  	'cancelOn' => 'raty-cancel-on.png',
	),
));

Icon range

Choose an icon image for each position and name

$this->widget('ext.DzRaty.DzRaty', array(
	'name' => 'my_rating_field',
	'value' => 3,
	'options' => array(
		'path' => Yii::app()->request->baseUrl. '/images/raty',
		'iconRange' => array(
		  array(
			'range' => 2,
			'on' => 'face-a-on.png',
			'off' => 'face-a-off.png'
		  ),
		  array(
			'range' => 3,
			'on' => 'face-b-on.png',
			'off' => 'face-b-off.png'
		  ),
		  array(
			'range' => 4,
			'on' => 'face-c-on.png',
			'off' => 'face-c-off.png'
		  ),
		  array(
			'range' => 5,
			'on' => 'face-d-on.png',
			'off' => 'face-d-off.png'
		  ),
	)),
));

CGridView Integration

Use DzRaty in your CGridView widget.
The extension provides a filter and a data column for CGridView widget with jQuery Raty plugin support.

Displaying 1-5 of 5 results.
TitleDirectorScore
 
The Golden CompassChris Weitz
The Day After TomorrowRoland Emmerich
The AvengersJoss Whedon
SunshineDanny Boyle
InceptionChristopher Nolan
$this->widget('zii.widgets.grid.CGridView', array(
	'filter' => $model,
	'dataProvider'	=> $model->search(),
	'afterAjaxUpdate' => 'js:function() { dzRatyUpdate(); }',	// #1 - Let widget works after AJAX update
	'columns' => array(
		'image',
		'title',
		'director',
		array(
			'name' => 'score',
			'class' => 'ext.DzRaty.DzRatyDataColumn',	// #2 - Add a jQuery Raty data column
			'options' => array(				//      Custom options for jQuery Raty data column
				'space' => FALSE
			),
			'filter' => array('ext.DzRaty.DzRaty', array(	// #3 - Add a jQuery Raty filter column
				'model' => $model,
				'attribute' => 'score',
				'options' => array(			//      Custom options for jQuery Raty filter column
					'cancel' => TRUE,
					'cancelPlace' => 'right'
				),
			))
		)
	)
));

Options

Default options

DzRaty extension includes the following default options.

Options Description Default Value
path Images file path $assets_url .'/img'
targetKeep If the last rating value will be keeped after mouseout. true
targetType Option to choose if target will receive hint o 'score' type. "number"

Translatable options

DzRaty offers multilanguage support. You can place your own translation file under DzRaty/messages.

Options Description Default Value
cancelHint The cancel's button hint. "Cancel this rating!"
noRatedMsg Hint for no rated elements when it's readOnly. "Not rated yet!"
hints Hints used on each star. "bad", "poor", "regular", "good", "gorgeous"

Full documentation

You can find all available functions and options on jQuery Raty website.