1. Requirements
2. Usage
3. Options
4. Resources
5. Changelog

IButton implements the Giva Labs jQuery iButton plugin. More info at: http://www.givainc.com/labs/ibutton_jquery_plugin.htm

IButton accepts CSS selectors, so it is easy to give any checkbox or radio button the effect. It was also added support for model/attribute pairs, so that you can easily integrate into your Yii's forms.

Features ¶

Works with checkboxes or radio elements
Full keyboard support — use the [TAB] key to move from field to field and use the spacebar to toggle the status of the iButton (or use the arrow keys for radio buttons)
Custom event handlers
Detach iButton behavior from the element
Metadata support — when used with the jQuery Metadata Plug-in, you can define the properties for your button completely within the class attribute of your input elements
Enable/disable drag support — while the dragging behavior is intuitive on touch-based devices, it's not always be the best or expected UI behavior and may cause some mouse users problems (NOTE: In order to help differentiate between an intended mouse click or an actual drag event, we're developed the clickOffset option. If the time (in milliseconds) is under this value (120ms by default) it's assumed the user was attempting to click the button and not drag the handle.)
Enable/disable animation
Single sprite image — easily change the look of your button by just replacing the image sprite
Customizable labels — use any labels you want for your buttons
Support for disabled buttons
Easing support for animations
iPhone support

Requirements ¶

Tested on Yii 1.1.9

Usage ¶

Extracted the zip file under protected/extensions

Sample 1 - turn all checkboxes in the page into iButtons:

<?php $this->widget('ext.ibutton.IButton', array(
 			'selector'=>':checkbox',
 			'options' =>array(
 				'duration' => 250,
 				'change'=>'js:function(){alert("ooohay! it has been changed!");}'
 			)
 	));?>

Sample 2 - turn the model/attribute pair into an iButton:

<?php $this->widget('ext.ibutton.IButton', array(
 			'model'     => $model,
 			'attribute' => 'is_master',
 			'options' =>array(
 				'labelOn'=>Yii::t('app','Yes'),
 				'labelOff'=>Yii::t('app','No'),
 				'change'=>'js:function($choice){
 					$choice.is(":checked")?alert("Hey, master!"):alert("Sorry, you are not my master!");
 				}'
 			)
 	));?>

Sample 3 - turn both all radio buttons and a model/attribute pair into iButtons:

<?php $this->widget('ext.ibutton.IButton', array(
 			'selector'  => ':radio',
 			'model'     => $model,
 			'attribute' => 'is_master',
 			'options' =>array(
 				'labelOn'=>Yii::t('app','Yes'),
 				'labelOff'=>Yii::t('app','No'),
 				'change'=>'js:function($choice){
 					$choice.is(":checked")?alert("Check on"):alert("Check off");
 				}'
 			)
 	));?>

Sample 4 - converts all checkboxes and radios in a form into iButtons using form selector:

<?php $this->widget('ext.ibutton.IButton', array(
 			'selector'  => 'form',
 			'options' =>array(
 				'labelOn'=>Yii::t('app','Yes'),
 				'labelOff'=>Yii::t('app','No')
 			)
 	));?>

Options ¶

All plugin's options should be passed through the $options array, in the widget instantiation (as seen above). Some options are only suitable to the widget itself.

//the javascript id will be registered as ibutton_$id
	public $id;
	
	//in debug mode publishes normal version of js and css files, if debug is false, publishes minified versions
	public $debug = false;
	
	//which css selector should be converted to iButton
	public $selector  = null;
	
	//model/attribute pair to convert to iButton
	public $model     = null;
	public $attribute = null;
	
	//plugin options
	public $options;
	
	//controls the published javascript
	public $useJqueryMetadata = true; //The use of the Metadata plug-in allows you to define the options for your buttons within the class attribute of the form element. 
	public $useJqueryEasing   = true; //The Easing Plug-in expands the options for easing in the animation of the sliding button. 
	
	//default plugin options - change it overriding $options array parameter
	private $defaultOptions = array(
		'duration'          => 200,      // the speed of the animation 
		'easing'            => 'swing',  // the easing animation to use 
		'labelOn'           => 'ON',     // the text to show when toggled on 
		'labelOff'          => 'OFF',    // the text to show when toggled off 
		'resizeHandle'      => 'auto',   // determines if handle should be resized 
		'resizeContainer'   => 'auto',   // determines if container should be resized 
		'enableDrag'        => true,     // determines if we allow dragging 
		'enableFx'          => true,     // determines if we show animation 
		'allowRadioUncheck' => false,    // determine if a radio button should be able to be unchecked 
		'clickOffset'       => 120,      // if millseconds between a mousedown & mouseup event this value, then considered a mouse click
 
		// define the class statements 
		'className'         => "", // an additional class name to attach to the main container 
		'classContainer'    => "ibutton-container" ,
		'classDisabled'     => "ibutton-disabled" ,
		'classFocus'        => "ibutton-focus" ,
		'classLabelOn'      => "ibutton-label-on" ,
		'classLabelOff'     => "ibutton-label-off" ,
		'classHandle'	    => "ibutton-handle" ,
		'classHandleMiddle' => "ibutton-handle-middle" ,
		'classHandleRight'  => "ibutton-handle-right" ,
		'classHandleActive' => "ibutton-active-handle" ,
		'classPaddingLeft'  => "ibutton-padding-left" ,
		'classPaddingRight' => "ibutton-padding-right" ,
 
		// event handlers 
		'init'    => null,  // callback that occurs when a iButton is initialized 
		'change'  => null,  // callback that occurs when the button state is changed 
		'click'	  => null,  // callback that occurs when the button is clicked 
		'disable' => null,  // callback that occurs when the button is disabled/enabled 
		'destroy' => null,  // callback that occurs when the button is destroyed
	);
	
	//code that will be generated
	private $jsCode;

Full documentation at plugin's website (resources)

Resources ¶

• Plugin's website
• Try out a demo

Changelog ¶

• v 1.2 - Fixed bug when publishing resources for Windows platform. Changed CHtml::getActiveId() to CHtml::activeId() for using with Yii 1.1.9 (thanks to @stummp for reporting) (2012-01-30 08:01)

• Fixed a bug when no options were set, CMap::mergeArray produced CException (2012-01-28 17:00)