jquery.selectBoxIt.js: A JavaScript repository from sionqi

jquery.selectBoxIt.js - jQuery Select Box Plugin

A jQuery plugin that progressively enhances an HTML Select Box into a single option dropdown list. The dropdown list can be optionally styled with Twitter Bootstrap, jQueryUI ThemeRoller, or jQuery Mobile, optionally animated with jQueryUI show/hide effects, and works on Desktop, Tablet, and Mobile browsers.

Homepage

Annotated Source Code

Notable Features

Styleable with Twitter Bootstrap, jQueryUI Themeroller, and jQuery Mobile
Supports Desktop, Tablet, and Mobile browsers
Supports all jQuery and jQueryUI show/hide effects (optional)
Supports all Twitter Bootstrap (Glyphicons) and jQueryUI/custom icons
Includes ARIA (Accessible Rich Internet Applications) support
Full keyboard search and navigation support
An event API triggered on the original select box element that calls the plugin
A method API providing methods to interact with the dropdown list (i.e. Search, Open, Disable, Set Options).
Passes jsHint with no errors
Selected, Disabled, and Optgroup Support
Easily extendable to allow developers to create new widgets

##Requirements jQuery 1.8.3+ (It is always recommended to use the latest version of jQuery)

jQueryUI Widget Factory 1.10.0+ (It is always recommended to use the latest version of the jQueryUI Widget Factory)

##Desktop Browser Support IE8+, Firefox 4+, Chrome, Safari 4+, Opera 11+ (Other browsers may work, but I did not test on them)

Note: The CSS3 background-size property is used for the icon images, which is only supported in IE9+

##Mobile/Tablet Browser Support iOs 3+, Android 2.1+ (Other browsers may work, but I did not test on them)

##Unit Tests All unit tests are written using the Jasmine Framework

##Contributing Take care to maintain the existing coding style. Add Jasmine unit tests for any new or changed functionality. Lint and test your code using grunt.

If you plan to contribute to SelectBoxIt in the future, keep in mind that you should make sure your code passes the Grunt checks.

To set up the SelectBoxIt grunt/node.js dependencies, first make sure you have PhantomJS installed, which is a headless browser. Unfortunately PhantomJS cannot be installed automatically.

Next, navigate to within the jquery.selectBoxIt.js folder and type `npm install' (this should install grunt and a few other node.js libraries).

Next, type grunt

Note: If you are on Windows, remember you need to run the grunt command using grunt.cmd. Also, if you have trouble getting the Jasmine Unit Tests to work with PhantomJS 1.5 (the current release), install PhantomJS 1.3.

After you have verified your code, send a pull request to the SelectBoxIt dev branch. After you send a pull request, you will hear back from me shortly after I review your code.

You'll find source code in the "src" subdirectory!

##Forking If you find that you need a feature that SelectBoxIt does not currently support, either let me know via the SelectBoxIt issue tracker, or fork SelectBoxIt on Github and easily extend SelectBoxIt to create your own widget!

##Change Log

3.8.0 - October 4, 2013

Bug Fixes

Fixed mobile hidden select box with bug: #209
Prevent disabled Selects from being clickable on iOS devices: #203
Fixed defaultText mobile bug: #205

Improvements

Improved performance by not removing option icons #207
Allow passing in a custom theme object #204

3.7.0 - August 13, 2013

Bug Fixes

Fixed a focus bug that prevented a drop down option to be selected if the drop down menu was open and the page was then scrolled.
Fixed scroll list not closing bug #196 #191
Fixed incorrect Microsoft CSS prefix: #195
Fixed max-width rendering for select boxes that are initially hidden: #192
Fixed Native select box and accesibility bug: #189

Improvements

ARIA support #197

3.6.0 - June 23, 2013

BREAKING CHANGES

jQuery v1.8.3 or greater is now required. The reason for the bump is a jQuery bug associated with passing an array of jQuery objects to the append() method. #175
The size attribute is no longer supported. You must now use the data-size attribute to specify size. The reason for the change is because when an HTML select box has a size attribute, you cannot retrieve the value of the select box (terrible) #170

New Options

hideCurrent - Hides the currently selected drop down option from the list. #172

Bug Fixes

Prevent the destroy event from propagating to parent elements #181
Fixed an irritating bug that did not allow an option to be selected after the drop down was open and the page was scrolled

Improvements

Deferred objects/promises are now supported within the populate option and add() method. This change makes it much easier to use the jQuery ajax() method to dynamically add options. #171
When using the showFirstOption option with mobile/tablet browsers, the first drop down option will now be disabled. Since hiding a select box option is not in the W3C specification, it will not yet be supported. #179
On mobile/tablet browsers, the option-click event is now triggered along with the change event. #184
Improved the setOption() and setOptions() methods to handle all option updates. #185

3.5.0 - May 10, 2013

New Options

dynamicPositioning - Determines whether or not the drop down list should fit inside it's viewport.

Bug Fixes

Fixed Firefox Keyboard Navigation Bug #160
Fixed dynamic positioning bug: #166
Fixed enable/disable bug: #163
Fixed default text and selected bug: #165

3.4.0 - April 26, 2013

BREAKING CHANGES jQuery 1.7+ is now required jQueryUI Widget Factory 1.10.0+ is now required

New Options

populate - Convenience option that accepts JSON data, an array, a single object, or valid HTML string to add options to the drop down list
selectedtext - Allows the ability to change what is displayed in the collapsed dropdown when an item is selected. Issue #151 **Special thanks to freakingawesome for this new option.
size - Support the size attribute to determine the maximum number of visible drop down list options that should be shown. Possible values include auto or a number > 1
Added the data-preventclose HTML5 data attribute to allow you to specify which option selections should not close the drop down

New Methods

add(data, callback) - Adds drop down options using JSON data, an array, a single object, or valid HTML string
remove(indexes, callback) - Removes drop down list options using an index or array of indexes

Bug Fixes

Fixed hidden auto width bug #149
Fixed the destroy() method logic and am correctly reapplying the original select box style attribute
Optgroup class names are now properly carried over to the new drop down
Fixed the dynamically changing images bug #157
Fixed enabled/disabled refresh() bug #144
Fixed the jQueryUI Dark Themes bug #148

Improvements

Improved event handling performance by switching to the jQuery on() method and adding event delegation instead of direct binding in a few places
Now triggering the change event when using the defaultText option #146
Improved the dynamic positioning logic to not set a max-height in unneccessary places
Improved the wait() logic to internally use the jQueryUI delay() method
Each SelectBoxIt event handler now passes back the correct select box, select box option, drop down, and drop down option in the callback function second parameter
Removed the unneccessary focus and hover CSS pseudo classes being applied in the default theme
Removed the unneccessary tagNames from the CSS default theme
Added silk to the UA detection to help detect Amazon Kindle Fire devices
Updated to Grunt v0.4

3.3.0 - March 19, 2013

New Options

autoWidth - Makes sure the width of the drop down is wide enough to fit all of the drop down options. BREAKING CHANGE - This is now the default. #129
html - Determines whether or not option text is rendered as html or as text. #136

Bug Fixes

Fixed mobile positioning bug #135
Fixed focusout bug #133
Chopped text (the new autoWidth option is a fix for this) #126

Improvements

Hide the original select box faster #132

3.2.0 - February 28, 2013

New Options

Added copyClasses option which allows the user to specify if native classes should be copied to the button, the container element, or neither. For backwards compatibility, defaults to "button". #124
Added a nativeMousdown option to allow the drop down to be opened programmatically using the mousedown event. Currently, the open event logic needs to be updated to allow this. #89
Add a customShowHideEvent option to which prevents a drop down from opening on click or mousedown, which allows a user to open/close the drop down with a custom event handler. #89

Bug Fixes

Fixed a dynamic positioning bug
Fixed a bootstrap theme box-shadow bug
Fixed a mobile webkit bug
Made the refresh() method compatible with the native option #125
Prevented the open(), and close() methods from opening the desktop drop down list with mobile devices

3.1.0 - February 20, 2013

IMPORTANT - Only pixel widths for the drop down are guaranteed to work. Do not use percentage based widths or width:auto;

Added back the dynamic max-width CSS attribute for the drop down text to make sure even small select boxes would look correctly.

3.0.0 - February 20, 2013

IMPORTANT - Make sure to update the jQueryUI Widget Factory to v1.0.0+: The Widget Factory now requires you to access the plugin instance using $("select").data("selectBox-selectBoxIt");
Refactored the code and saved ~2kb
Improved search algorithm accuracy for long lists #110
Removed JavaScript dynamic CSS style declarations (all styles are now set in the CSS)
Fix mobile positioning bug #90
Added a new copyAttributes option to allow a user to specify which HTML attributes they would like copied over to the new drop down.
Added a new viewport option to constrain the dropdown list to the dimensions of an element other than the window
Added a new similarSearch option to optimize for lists with similar values (i.e. State list)
Built out a brand new custom CSS theme and use it as the default theme. This theme models the Twitter Bootstrap theme, but does not require the Twitter Bootstrap CSS file.
Removed the nostyle option
Upgraded the custom web build process to provide users with minified and unminified versions of SelectBoxIt.
Wrote more Jasmine tests
Officially dropped IE7 support
Added a CSS class for when the drop down is opened
Fixed the bug when there are no options #117
Added vertical-align:middle; to help with vertical label alignment #115
Hopefully fixed the eclipse error #108

2.9.9 - January 20, 2013

Fixed #98
Fixed keyboard search with disabled options bug and keyboard search accuracy
Refactored attribute copy logic
Added the selectWhenHidden option to allow drop down options to be selected with the keyboard when the drop down is hidden
Added back IE 7 support in this release after numerous requests
Fixed #102
Fixed optgroup mouse cursor
Upgrade CSS styles to support select boxes with options without text

2.9.0 - January 15, 2013

Removed outline from appearing around the drop down
Fixed non select box bug #94
Fixed IE 8 bug from copying over all select box attributes to the new drop down #95

2.8.0 - January 12, 2013

IMPORTANT: Dropped IE7 support - This does not mean new features will not work in IE7, but instead that they will not be tested in IE7.

All attributes on the original select box and select box options are now being copied over to the new drop down.

2.7.0 - January 11, 2013

Refactored internal drop down DOM element property names.

2.6.0 - January 8, 2013

Added support for styling the currently selected drop down option via the selectboxit-selected CSS class #86
Fixed refresh() method mobile bug #68
Refactored and fixed bugs for SelectBoxIt internal event triggering: All custom events now return an object containing both the currently selected select box and drop down options

2.5.0 - January 6, 2013

Default Behavior Change

SelectBoxIt will no longer select a drop down option (and trigger the change event on the original select box) when a user navigates to an option using the up and down arrow keys via the keyboard, or searches for an option using the keyboard. An option will only be selected when a user clicks an option or presses the enter key when an option is actively "focused". #85
Added a new option, aggressiveChange, which will select a drop down option (and trigger the change event on the original select box) when a user navigates to an option using the up and down arrow keys via the keyboard, or searchs for an option using the keyboard.
There is now always an "active" class when drop down options are moused over. #84

2.4.0 - January 2, 2013

Added the data-iconurl HTML5 data attribute to support relative and absolute image url's

2.3.0 - December 18, 2012

Added the disableOption() and enableOption() methods
Fixed disabled state CSS class bug. Now allows all supported themes (Twitter Bootstrap, jQueryUI, and jQuery Mobile) CSS class's are able to take effect
Improved custom event handling. The moveDown, moveUp, search, option-click, disable-option, and enable-option custom events now pass an object back in the second argument of the callback function event handler. Within the object.elem property, is the single select box option that was interacted with.
Added Travis CI testing support

Note: If you are using Twitter Bootstrap as your theme, then it is recommended to upgrade to Twitter Bootstrap v2.2.0 or greater ()

2.2.0 - December 15, 2012

Added jQuery Mobile data-theme supporting

2.2.0 RC1 - December 13, 2012

Added jQuery Mobile CSS Theming Support
Added the selectOption() method

2.1.0 - December 3, 2012

Multiple bug fixes: #53, #54, #55, and #56.
Added the native option: Allows you to trigger the native select box element when a user is interacting with the drop down

2.0.0 - November 9th, 2012

Greatly improved dynamic positioning. SelectBoxIt now makes sure that the drop down list never runs off of the page (no matter how small the viewport is)
Improved support for enclosing a drop down arrow inside of a box (by setting a border)
Simplified mobile device checking for iOs, Android, Blackberry, Opera Mini, and Windows mobile devices (Removed the long regex supplied by detectmobilebrowsers.com)

1.9.0 - October 31, 2012

Added nostyle option
Updated the CSS to remove tag names, remove IE7 hack, and improve CSS specificity
Thanks to @gavacho for the contributions

1.8.0 - October 27, 2012

**Multiple Bug Fixes and Features Added:

Fixed IE7 focus bug
Removed all CSS attributes from the JS (to allow for maximum flexibility when changing styles) #34
SelectBoxIt now copies over all classes and inline styles from the original select box to the new drop down #34
Refresh method bug fix #32

1.7.0 - October 12, 2012

**Multiple Bug Fixes**

Allow users to programmatically change the value of the select element #28
Removed unique id attributes from select boxes that do not originally include an id attribute #27
Applied HTML attribute encoding for quotes inside of option values #8
Fixed jQuery 1.8.2 keyboard compatibility bug #26

1.6.0 - September 28, 2012

Improved the CSS flexibility (can now more easily use auto widths)

1.5.0 - September 26, 2012

Improved the search algorithm

1.4.0 - September 23, 2012

BIG NEWS: Added Mobile and Tablet Support
Added the isMobile option

1.3.0 - September 9, 2012

Added the changed custom event

1.2.0 - September 6, 2012

Fixed IE8 keyboard navigation and search bug
Added a keydownOpen option to allow the dropdown list to be visible if the user presses the up or down arrow key

1.1.0 - September 5, 2012

Added Twitter Bootstrap Theming Support
Added a refresh public method
Added the destroy method into the SelectBoxIt core

1.0.0 - August 8, 2012 Stable 1.0 release

Upgraded Homepage/Documentation
The plugin was split into modules (multiple files) and a custom build process was created
Big fixes/code clean up

0.9.0 - May 21, 2012 Approaching a stable 1.0 release

IE7 and IE8 bug fix: A special thanks to lhwparis

0.8.0 - May 15, 2012 Approaching a stable 1.0 release

Bug fixes for the disabled use cases

0.7.0 - May 10, 2012 Documentation

Added optgroup support to allow dropdown list options to be put in subgroups.
Bug fixes to the change and focus Event API handlers

0.6.0 - May 3, 2012 Documentation

Added jQueryUI and custom icon support to allow icons to be used for the dropdown list and also alongside individual dropdown options. You can specify the class names that you want to use to show the appropriate icon (set the background-image property inside of your CSS). There are two ways to do this (HTML5 data attributes or SelectBoxIt options)
- Added support for three new HTML5 data attributes to be used with the original select box element. Use cases for each are described below.
  - data-icon - Specifies the custom or jQueryUI CSS classes you want to use to show icon images for the dropdown list and/or dropdown list individual options
  - data-downarrow - Specifies the custom or jQueryUI CSS classes you want to use to replace the default down arrow icon image
  - data-text - Specifies the custom text that you want to use for the dropdown list
- Added support for two new options. Use cases for each are described below.
  - defaultIcon - An alternative to the data-icon HTML5 data attribute
  - downArrowIcon - An alternative to the data-downarrow HTML5 data attribute

0.5.0 - April 29, 2012 MAJOR REWRITE

SelectBoxIt has been rewritten using the jQueryUI Widget Factory! This means that SelectBoxIt depends on both jQuery and the jQueryUI Widget Factory. This also means that there are a few API changes that are not backwards compatible...
- getOption(), getOptions(), and create() were all removed from the Method API
- To use the custom pseudo selector, you must now use $(":selectBox-selectBoxIt")
Grunt Integration. SelectBoxIt now uses grunt to run jsHint for code quality checking, Jasmine for unit testing, and UglifyJS for minification.
Removed AMD Support

0.4.0 - April 28, 2012

AMD Support. If AMD support is found, SelectBoxIt is wrapped in a define module. UMD Patterns
Bug fixes for supporting the disabled HTML property for individual select box options

0.3.0 - April 25, 2012

A new option, defaultText, was added to allow users to specify the default text of the dropdown list that is not linked to a specific select box option
The disabled HTML property is now supported for individual select box options
When a user presses the esc keyboard key, the dropdown options list will now close (become hidden)

0.2.0 - April 24, 2012

This release requires you to use jQuery 1.6.1+.
You are no longer required to have select box option values be the same as the select box option text.
IE bug fix to prevent default dropdown text from being selectable

0.1.0 - April 14, 2012

Initial SelectBoxIt release. Added annotated source code, unit tests, and documentation

Contributors

Greg Franko - @gfranko

Thomas von Deyen - @tvdeyen

Ron 'coyote' Lussier - @lenscraft

sionqi/jquery.selectBoxIt.js

jquery.selectBoxIt.js - jQuery Select Box Plugin

License