Giva Labs

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
       , 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="http://ajax.googleapis.com/ajax/libs/jquery/1.3.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.

Support

This source code is provided as-is. At this time Giva is not offering direct support for this product. If you are in need of assistance, post your question to one of the jQuery Mailing Lists. Members of the Giva development team actively participate on the jQuery Mailing lists, so if we see your question we will try our best to respond.

License

Copyright 2010 Giva, Inc. (http://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 
	http://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.

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 (26 KB)

Revisions

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