├── LICENSE.txt ├── README.md ├── images ├── select_arrow.gif ├── select_arrow_bg.gif └── select_arrow_bg_hover.gif ├── index.html ├── jquery.sb.css ├── jquery.sb.js ├── jquery.sb.min.js └── lib └── jquerytie ├── LICENSE.txt ├── README.md ├── index.html ├── jquery.tie.js └── jquery.tie.min.js /LICENSE.txt: -------------------------------------------------------------------------------- 1 | Copyright (c) 2010 RevSystems, Inc 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy 4 | of this software and associated documentation files (the "Software"), to deal 5 | in the Software without restriction, including without limitation the rights 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 | copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in 11 | all copies or substantial portions of the Software. 12 | 13 | The end-user documentation included with the redistribution, if any, must 14 | include the following acknowledgment: "This product includes software developed 15 | by RevSystems, Inc (http://www.revsystems.com/) and its contributors", in the 16 | same place and form as other third-party acknowledgments. Alternately, this 17 | acknowledgment may appear in the software itself, in the same form and location 18 | as other such third-party acknowledgments. 19 | 20 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 21 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 22 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 23 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 24 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 25 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 26 | THE SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # jQuery-SelectBox 2 | 3 | Traditional select elements are very difficult to style by themselves, 4 | but they are also very usable and feature rich. This plugin attempts to 5 | recreate all selectbox functionality and appearance while adding 6 | animation and stylability. 7 | 8 | Please feel free to rate this plugin on [plugins.jquery.com](http://plugins.jquery.com/project/jquery-sb). 9 | 10 | # Demo 11 | 12 | You can view the selectboxes in action [here](http://dl.dropbox.com/u/124192/websites/selectbox/index.html). 13 | 14 | # TODO 15 | 16 | * Test ARIA markup 17 | * Create optional skins 18 | 19 | # Features 20 | 21 | * Recreates and extends all functionality of the browser's built-in `` still work 26 | * Keyboard Accessible: Manages tab focus, supports up/down/home/end hotkeys and automatic matching of typed strings 27 | * Javascript animations on close/open 28 | * Intelligent collision avoidance (the selectbox tries to fit on the screen) 29 | * Deals effectively with cross-browser z-index issues 30 | * Handles optgroups 31 | * Handles disabled selects 32 | * Handles disabled optgroups 33 | * Handles disabled options 34 | * Can be refreshed arbitrarily, i.e. when you dynamically add/remove options from the original select 35 | * Options for a specific `` changes 37 | * Allows custom markup formatting for visible elements 38 | 39 | The css in this plugin also includes an example custom style called "round_sb". 40 | Its purposes are (a) to give you an example of how to override the default style, 41 | and (b) to give you a familiar but slightly more modern version of the selectbox 42 | that you can integrate with minimal or no css modification. 43 | 44 | # Compatibility 45 | 46 | jQuery-SelectBox has been tested and confirmed working in the following browsers: 47 | 48 | * Firefox 3.6.12 49 | * Google Chrome 7.0.517.44 50 | * Opera 11.00 build 1156 51 | * IE9 beta 52 | * IE8 (via IE9 beta) 53 | * IE7 (via IE9 beta) 54 | 55 | It requires [jQuery version 1.3.x](http://jquery.com) and up. 56 | 57 | IE6 and below are ignored by jQuery-SelectBox. 58 | 59 | # Usage 60 | 61 | Requires [jQuery](http://jquery.com) and this plugin. 62 | 63 | 64 | 65 | 66 | If you want to use dynamic selects with [jquery.tie](https://github.com/revsystems/jQuery-Tie), you need to include it before jquery.sb: 67 | 68 | 69 | 70 | 71 | 72 | There is also css. You can feel free to copy this css to your master file or include it separately. 73 | 74 | 75 | 76 | To apply the plugin to select elements: 77 | 78 | $(document).ready(function() { 79 | $("select").sb(); 80 | }); 81 | 82 | To apply with options set: 83 | 84 | $(document).ready(function() { 85 | $("select").sb({ 86 | animDuration: 1000, 87 | fixedWidth: true, 88 | etc... 89 | }); 90 | }); 91 | 92 | If you've used javascript to modify the contents of the original select, and you want the changes to appear in the replacement, calling "refresh" should match them: 93 | 94 | $(document).ready(function() { 95 | $("select").sb(); 96 | $("select").append(""); 97 | $("select").sb("refresh"); 98 | }); 99 | 100 | Alternatively, if you don't have control over the function that triggers the reload--for example, if you're using an AJAX framework--you can use 101 | [jquery.tie](https://github.com/revsystems/jQuery-Tie) to monitor the contents of the original select and update when necessary: 102 | 103 | $(document).ready(function() { 104 | $("select").sb({ useTie: true }); 105 | $("select").append(""); 106 | }); 107 | 108 | Refreshing can be done at any time, even while the SelectBox is open. 109 | 110 | You can also change the options for a SelectBox on the fly: 111 | 112 | // this initializes all s 113 | $("select").sb() 114 | 115 | // and this sets a specific set to use fixedWidth styling: 116 | $("select.fixed_width").sb("options", { fixedWidth: true }); 117 | 118 | # Custom Styling 119 | 120 | ## Making a fixed width selectbox 121 | 122 | Say you want to make your selectboxes a fixed width so they line up with the rest of your inputs. Try something like this. 123 | 124 | When you initialize jQuery-sb, use the fixedWidth flag: 125 | 126 | $(document).ready(function() { 127 | $("select.fixed_width").sb({ fixedWidth: true }); 128 | }); 129 | 130 | In your css, you can add the following to make a selectbox with visual width = 100px: 131 | 132 | .selectbox.fixed_width .display{ 133 | width:73px; 134 | padding:0 24px 0 3px; /* remember padding contributes to the overall width. padding-right is large enough here for the arrow graphic. */ 135 | } 136 | .selectbox.fixed_width.items{ 137 | width:100px; /* width of display text plus the padding (73 + 27) = 100, so they line up */ 138 | } 139 | 140 | # Options 141 | 142 | View defaults and short descriptions for options in jquery.sb.js. This list is meant to be more 143 | informative than the js comments. 144 | 145 | **acTimeout** (duration) 146 | 147 | Short for "Autocomplete Timeout". When a selectbox is highlighted, you can type to select a 148 | matching option. This timeout specifies how long the user has after each keystroke to concatenate 149 | another letter onto the search string. If there is no keystroke before the timeout is completed, 150 | the search string is reset. 151 | 152 | **animDuration** (duration) 153 | 154 | Short for "Animation Duration". The time it takes for the closing/opening dropdown animation to play. 155 | 156 | **arrowMarkup** (string) 157 | 158 | The HTML that is appended to the display. Usually it's an arrow, but it could be whatever you want. 159 | 160 | **optionFormat** (function) 161 | 162 | Given an option as the context, returns a string or DOM/jQuery object that will be displayed in the dropdown. 163 | The default is simply to use the option's text. 164 | 165 | **displayFormat** (function) 166 | 167 | Given an option as the context, returns a string or DOM/jQuery object that will be displayed in 168 | the "display"--the portion of the selectbox that is always visible. If not specified, it will default to 169 | the value of optionFormat. 170 | 171 | **optgroupFormat** (function) 172 | 173 | Given an optgroup as the context, returns a string that will be displayed in the dropdown. The 174 | default displays the optgroup's label attribute. 175 | 176 | **ddCtx** (selector / DOM Element / function that returns a selector) 177 | 178 | Short for "Dropdown Context". When the dropdown is displayed, its markup is appended to the bottom 179 | of this context. This helps take care of any z-index issues that IE might have. If you are using 180 | popups or overlays on your page, the default of "body" might not be appropriate and you can set 181 | something more specific. When not using the default, the ddCtx element should have position:relative 182 | or position:absolute in its CSS. Otherwise, the dropdown will not appear in the right place. 183 | 184 | **dropupThreshold** (integer) 185 | 186 | When determining whether to display a dropdown or a dropup, this value is used to weight the comparison. 187 | The space above is compared to the space below the selectbox. If the dropupThreshold is positive, then 188 | the space above must be that many more pixels than the space below to show above. If the dropupThreshold 189 | is negative, then the space below must be that many more pixels than the space above to show below. 190 | 191 | **fixedWidth** (boolean) 192 | 193 | False by default. 194 | If set to FALSE, the width of the select will be variable, conforming to the longest dropdown value. 195 | If set to TRUE, the width should be specified from the site's css. 196 | 197 | **maxHeight** (false / positive integer) 198 | 199 | Allows you to set the maximum pixel height of the dropdown. By default, the maximum height varies 200 | based on the position of the dropdown relative to the window. 201 | 202 | **maxWidth** (false / positive integer) 203 | 204 | Allows you to set the maximum pixel width of the selectbox. By default, the width varies based on the 205 | widest dropdown element. If white-space:nowrap is set on dropdown elements, then they will be clipped 206 | past the maxWidth. 207 | 208 | **selectboxClass** (string) 209 | 210 | The class used to identify selectboxes. This is used to kill inactive dropdowns when one is selected. 211 | 212 | **useTie** (boolean) 213 | 214 | Default is false. When set to true and jquery.tie is 215 | included on the page, this will automatically monitor changes in the underlying select and update 216 | jquery-sb accordingly. 217 | 218 | 219 | # Troubleshooting 220 | 221 | ## jQuery-SelectBox in div with z-index 222 | 223 | If you call $("select").sb() (no special options) on a select in a z-index'ed element, the dropdown 224 | may appear UNDERNEATH the element. 225 | 226 | You have two options in dealing with this scenario. The first is setting ddCtx to the absolutely 227 | positioned element. This will make sure that it always appears on top of it. Or you can modify the 228 | css for .items to have a z-index greater than the parent div. 229 | 230 | For newer versions, I set the default z-index of .items to 99999, so you probably won't see this issue 231 | unless you're using huge z-index values. 232 | 233 | 234 | ## margin:auto on body 235 | 236 | Across different browsers and jQuery versions, it is very difficult to get a stanard margin value for the 237 | body when it is set to "auto". 238 | 239 | If you have margin-left set to auto for your body element, jQuery-SelectBox will completely break in IE7. 240 | In other browsers, it may or may not position incorrectly. 241 | 242 | If you need to center your page, I highly recommend not doing it with the `body` tag. The implementation 243 | is too finicky. Instead, I often use the following pattern. 244 | 245 | In your css file: 246 | 247 | body{margin:0;} 248 | .outer_container{ 249 | text-align:center; /* text-align centers the child div in old versions of IE */ 250 | } 251 | .inner_container{ 252 | margin:0 auto; /* margin:auto centers in newer browsers */ 253 | text-align:left; /* text-align:left resets the sub-elements */ 254 | width:960px; /* the width of your page */ 255 | } 256 | 257 | In your HTML: 258 | 259 |
260 |
261 | Everything in here will be centered 262 |
263 |
264 | 265 | If you use this pattern, you should have no issues with margin:auto on `body`. 266 | 267 | 268 | ## I need to keep margin:auto on my body tag. How do I get jQuery-SelectBox to behave? 269 | 270 | If you're stuck with margin:auto on the `body` element, then I suggest specifying the ddCtx option. 271 | The ddCtx (dropdown context) option lets you change which element the dropdown is appended to, thereby 272 | avoiding dependence on the body tag's margin. 273 | 274 | For example, you might have this fragment in your markup: 275 | 276 | 277 |
278 | 281 |
282 | 283 | 284 | In which case, you'd want the following CSS: 285 | 286 | #an_arbitrary_container{position:relative;} 287 | 288 | And to specify ddCtx when you initialize jQuery-SelectBox: 289 | 290 | $("select").sb({ ddCtx: "#an_arbitrary_container" }); 291 | 292 | The downside to this method is that, if z-index comes into play, the dropdown might appear BEHIND siblings of 293 | `#an_arbitrary_container`--due to the buggy z-index handling in IE7. Consider yourself warned. You can manipulate 294 | the z-indexes in CSS so it works, but it's advanced. 295 | 296 | 297 | ## IE7/IE8: Javascript error is thrown when clicking to open the selectbox 298 | 299 | See "margin:auto on body" above. If that is not the problem, please let me know on the 300 | [Issues Page](https://github.com/revsystems/jQuery-SelectBox/issues). 301 | 302 | 303 | # Bug Reports 304 | 305 | Before you report a bug, I highly suggest making sure you have the most up-to-date version of 306 | jQuery-SelectBox. I update the code very frequently and may introduce/squash bugs in rapid succession. This 307 | will continue until an official release is announced, at which point a stable download will be created and a new 308 | development branch will be started. 309 | 310 | If you spot a bug that's lingering, please let me know on the 311 | [jQuery-SelectBox Github Issues page](https://github.com/revsystems/jQuery-SelectBox/issues). -------------------------------------------------------------------------------- /images/select_arrow.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/revsystems/jQuery-SelectBox/2a7b208f5bbda93d386e856f98a5bf330a687cca/images/select_arrow.gif -------------------------------------------------------------------------------- /images/select_arrow_bg.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/revsystems/jQuery-SelectBox/2a7b208f5bbda93d386e856f98a5bf330a687cca/images/select_arrow_bg.gif -------------------------------------------------------------------------------- /images/select_arrow_bg_hover.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/revsystems/jQuery-SelectBox/2a7b208f5bbda93d386e856f98a5bf330a687cca/images/select_arrow_bg_hover.gif -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | Selectbox Replacment Demo 7 | 8 | 13 | 14 | 15 | 16 | 55 | 56 | 57 | 58 |
59 |
60 |
61 |
62 |
63 |
64 |
65 |
66 |
67 |
68 |
69 |
70 |
71 |
72 |
73 |
74 |
75 |
76 |
77 |
78 |

jquery.sb.js Selectbox Replacement

79 | 80 |

Demos

81 |
82 | 90 | 148 | 149 |
150 |
157 |
167 | 168 | 181 |
182 | 186 |
187 | 191 |
192 | 194 |
195 | 200 | 205 |
206 |
207 |
208 | 214 |
215 |
216 |
217 |
218 |
219 |
220 |
221 |
222 |
223 |
224 |
225 |
226 |
227 |
228 |
229 |
230 |
231 |
232 |
233 |
234 |
235 |
236 |
237 |
238 |
239 |
240 |
241 | 242 | 243 | -------------------------------------------------------------------------------- /jquery.sb.css: -------------------------------------------------------------------------------- 1 | /* applied to original 591 | $orig.find("option").each(function() { this.selected = false; }); 592 | $($item.data("orig")).each(function() { this.selected = true; }); 593 | 594 | // change the selection to this item 595 | $items.removeClass("selected"); 596 | $item.addClass("selected"); 597 | $sb.attr("aria-active-descendant", $item.attr("id")); 598 | 599 | // update the title attr and the display markup 600 | $display.find(".text").attr("title", $item.find(".text").html()); 601 | $display.find(".text").html(o.displayFormat.call($item.data("orig"))); 602 | 603 | // trigger change on the old will be displayed for old browsers 806 | if($.browser.msie && $.browser.version < 7) { 807 | return; 808 | } 809 | 810 | // get the original