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.
In order to use the iButton plug-in, you need the following:
Optionally, you may also want to use:
* 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.)
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]);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.
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.)
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.
Destroys the iButton widget. This restores the original checkbox/radio element in the DOM.
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.
Returns a reference to the internal $.iButton object. This is for advanced usage only. Examine the source code for uses of the $.iButton object.
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
}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.
To change the checked status of the button you can:
For more examples, see the Giva Labs - iButton Example Page page.
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.
Copyright 2011 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.