iButton jQuery Plug-in

Overview

The iButton jQuery plug-in emulates the checkbox functionality found on the iPhone. This plug-in was inspired by several other plug-ins—such as Thomas Reynolds' iphone-style-checkboxes. However, this plug-in attempts to combine the best features of all of the various iPhone checkbox-style plug-ins and then add the functionality that we felt was still missing.

Requirements

In order to use the iButton plug-in, you need the following:

jQuery v1.2.6 (or higher)*
jquery.ibutton.js Plug-in

Optionally, you may also want to use:

jQuery Metadata Plug-in — The use of the Metadata plug-in allows you to define the options for your buttons within the class attribute of the form element.
jQuery Easing Plug-in — The Easing Plug-in expands the options for easing in the animation of the sliding button.

* This plug-in may work with older versions of jQuery in the 1.2 family. If you try using this with an older version of jQuery, you will need to include the jquery.dimensions.js plug-in (as of jQuery v1.2.6 the jquery.dimensions.js plug-in is included in the jQuery core.)

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

Usage

To convert your checkbox (or radio) elements into iButton widgets, just invoke the jQuery plug-in using the following syntax:

$(":checkbox").iButton([options]);

You can use any selector that will target checkboxes or radio elements on your page.

Optionally, you can target a form object (or any non-input element) to convert all checkbox and radio elements contained in the element to an iButton:

$("form").iButton([options]);

Arguments

options: This argument is optional and allows you to customize the settings used for each instance of the plug-in. For a list of all available options, see the Options section.

Now that we have a reference to the widget, we can invoke any of the public API calls.

Public API

$("#id").iButton("toggle", value): Use the toggle() method to set the checked status of your input element. The value argument is an optional boolean value that allows you to set the checked status to either true or false. If the value argument is not supplied, the checked attribute of your input element will be toggled from true to false (or vice versa.)
$("#id").iButton("disable"): Use the disable() method to disable your button. This prevents the user being able to interactive with the button. It allows disables the actual checkbox/radio element, and disabled values are not submitted to the server on a form POST/GET operation.
$("#id").iButton("destroy"): Destroys the iButton widget. This restores the original checkbox/radio element in the DOM.
$("#id").iButton("repaint"): This will repaint the button to match it's current checked status. This should only be called if the checked attribute of the element has changed in some way out of your control to synchronize the skin's state with the actual checkbox value. The correct method of synchronizing the skin w/the element is to trigger the input's "change" event after any manual update to it's value.
$("#id").iButton("object"): Returns a reference to the internal $.iButton object. This is for advanced usage only. Examine the source code for uses of the $.iButton object.

Options

There are a number of options available for customizing the look and feel of the iButton widget.

{
     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
}

Getting Started

The first thing we need to do is to load the required JavaScript libraries and the CSS stylesheet used by the widget:

<!---// load jQuery and the jQuery iButton Plug-in //--->
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
<script type="text/javascript" src="./lib/jquery.ibutton.js"></script>

<!---// load the iButton CSS stylesheet //--->
<link type="text/css" href="./css/jquery.ibutton.css" rel="stylesheet" media="all" />

Before you can invoke an instance of the iButton widget, you must have one or more checkbox or radio elements on your page.

<p>
  <label for="iButton">
    E-mail notifications
  </label>
  <input type="checkbox" id="iButton" value="true" />
</p>

The next step is to actually create an instance of the iButton widget. You want to make sure to initialize the widget after all the necessary DOM elements are available, which makes the document.ready event a great place to initialize the widget.

<script type="text/javascript">
$(document).ready(function (){
  $("#iButton").iButton();
});
</script>

Now let us take a look at what the code above produced.

Example

E-mail notifications

To change the checked status of the button you can:

Click on the button
Drag the button handle to the left/right (releasing the handle after the midway point will snap the button to the on/off state.)
Click on the element's label tag (example: click on the "E-mail notification" text)
Use the keyboard (example: click on the word "Example" [to set the focus above the button] then use the [TAB] to place the button in focus and last press the [SPACEBAR] to toggle the status.)

For more examples, see the Giva Labs - iButton Example Page page.

License

Copyright 2011 Giva (https://www.givainc.com/labs/) 

Licensed under the Apache License, Version 2.0 (the "License"); 
you may not use this file except in compliance with the License. 
You may obtain a copy of the License at 
    https://www.apache.org/licenses/LICENSE-2.0 

Unless required by applicable law or agreed to in writing, software 
distributed under the License is distributed on an "AS IS" BASIS, 
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
See the License for the specific language governing permissions and 
limitations under the License.

Revisions

v1.0.04 (2015-08-19)

Fixed issue in Firefox 40 which prevented selecting option elements with the mouse.

v1.0.03 (2011-07-26)

Fixed compatibility issues with jQuery v1.6.2
Added className option for adding an additional class name to the main container—which is useful for adding alternative styles to the button
Revised image sprite to be better organized (handles are now grouped together)
Updated CSS to reflect changes to image sprite
Fixed bug where iButton behavior could be attached multiple times if code attempts to re-initialize on the same element

v1.0.01 (2009-09-04)

Fixed mouseup event handler so change event is only fired if the value is actually changed (it no longer fires if the handle isn't dragged past halfway)

v1.0.00 (2009-09-02)

Initial release

Download

The following download includes both uncompressed and minified versions of the plug-in and all the CSS and image files required to get you started. See the gettingstarted.htm file for usage instructions and a working example.

jquery.ibutton.zip (35 KB)