├── .gitignore ├── AUTHORS ├── gentleSelect ├── img │ └── expand.png ├── jquery-gentleSelect.css ├── jquery-gentleSelect-min.js └── jquery-gentleSelect.js ├── LICENSE ├── README.md └── index.html /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | *.pyc 3 | -------------------------------------------------------------------------------- /AUTHORS: -------------------------------------------------------------------------------- 1 | Shawn Chin 2 | -------------------------------------------------------------------------------- /gentleSelect/img/expand.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/shawnchin/jquery-gentleSelect/HEAD/gentleSelect/img/expand.png -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2010 Shawn Chin 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining 4 | a copy of this software and associated documentation files (the 5 | "Software"), to deal in the Software without restriction, including 6 | without limitation the rights to use, copy, modify, merge, publish, 7 | distribute, sublicense, and/or sell copies of the Software, and to 8 | permit persons to whom the Software is furnished to do so, subject to 9 | the following conditions: 10 | 11 | The above copyright notice and this permission notice shall be 12 | included in all copies or substantial portions of the Software. 13 | 14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 15 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 16 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 17 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 18 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 19 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 20 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # jQuery plugin: gentleSelect 2 | 3 | gentleSelect is a jQuery plugin for transfoming select boxes into 4 | a skinnable alternative. The selection list can be rendered with 5 | multiple columns/rows to present larger datasets in a more 6 | manageable format. 7 | 8 | 9 | There is much to be done on the flexibility and robustness front, 10 | and we welcome contributions and bug fixes. Feel free to fork 11 | and send us pull requests! 12 | 13 | 14 | ## Usage 15 | 16 | To use this plugin, one simply needs to load jQuery and the 17 | JS/CSS scripts for gentleSelect, then attach it to your 18 | select boxes on DOM ready: 19 | 20 | 21 | 22 | 23 | 28 | 29 | For more options, see the [gentleSelect website]. 30 | 31 | 32 | ## Others 33 | 34 | Copyright (c) 2010, Shawn Chin. 35 | 36 | This project is licensed under the [MIT license]. 37 | 38 | 39 | [gentleSelect website]: http://shawnchin.github.com/jquery-gentleSelect "gentleSelect Website" 40 | [MIT License]: http://www.opensource.org/licenses/mit-license.php "MIT License" 41 | -------------------------------------------------------------------------------- /gentleSelect/jquery-gentleSelect.css: -------------------------------------------------------------------------------- 1 | .gentleselect-data { display: none; } 2 | 3 | .gentleselect-label { 4 | padding: 1px 20px 1px 20px; 5 | background-color: #eee; 6 | 7 | border: 2px solid #ddd; 8 | -moz-border-radius: 5px; 9 | -webkit-border-radius: 5px; 10 | border-radius: 5px; 11 | 12 | background-repeat: no-repeat; 13 | background-position: center right; 14 | 15 | cursor: pointer; 16 | color: #555; 17 | 18 | white-space: nowrap; 19 | } 20 | 21 | .gentleselect-label-highlight { 22 | border: 2px solid #aaa; 23 | background-image: url('img/expand.png'); 24 | } 25 | 26 | .gentleselect-dialog { 27 | position: absolute; 28 | z-index: 500; 29 | display: none; 30 | 31 | background-color: #fff; 32 | border: 2px solid #999; 33 | 34 | -moz-box-shadow: 0px 0px 12px #555; 35 | -webkit-box-shadow: 0px 0px 12px #555; 36 | box-shadow: 0px 0px 12px #555; 37 | 38 | margin: 0; padding: 0; 39 | } 40 | 41 | .gentleselect-dialog > ul { padding: 0; margin: 0; list-style: none; } 42 | .gentleselect-dialog > ul > li { 43 | margin: 0; 44 | padding: 3px 20px 3px 25px; 45 | cursor: pointer; 46 | -webkit-touch-callout: none; 47 | -webkit-user-select: none; 48 | -khtml-user-select: none; 49 | -moz-user-select: none; 50 | -ms-user-select: none; 51 | user-select: none; 52 | } 53 | .gentleselect-dialog > ul > li.selected { 54 | font-weight: bold; 55 | color: #369; 56 | background-color: #eee; 57 | } 58 | 59 | .gentleselect-dialog > ul > li.gentleselect-dummy:hover { background-color: #fff; } 60 | .gentleselect-dialog > ul > li:hover { 61 | background-color: #69c; 62 | color: #fff; 63 | } 64 | 65 | /* override CSS for lone selected item when disallowEmpty=true */ 66 | .gentleselect-dialog > ul > li.sole-selected { 67 | cursor: default; 68 | } 69 | .gentleselect-dialog > ul > li.sole-selected:hover { 70 | color: #369; 71 | background-color: #eee; 72 | } 73 | 74 | 75 | .gentleselect-dialog > .gentleselect-title { 76 | display: block; 77 | text-align: center; 78 | margin: 0; 79 | padding: 2px; 80 | background-color: #ddd; 81 | font-size: 0.8em; 82 | color: #666; 83 | overflow: hidden; 84 | } 85 | -------------------------------------------------------------------------------- /gentleSelect/jquery-gentleSelect-min.js: -------------------------------------------------------------------------------- 1 | (function(d){var c={minWidth:100,itemWidth:undefined,columns:undefined,rows:undefined,title:undefined,prompt:"Make A Selection",maxDisplay:0,openSpeed:400,closeSpeed:400,openEffect:"slide",closeEffect:"slide",disallowEmpty:false,hideOnMouseOut:true};function b(j){if(typeof j=="undefined"){return false}else{return true}}function g(k,j){if(b(j.columns)&&b(j.rows)){d.error("gentleSelect: You cannot supply both 'rows' and 'columns'");return true}if(b(j.columns)&&!b(j.itemWidth)){d.error("gentleSelect: itemWidth must be supplied if 'columns' is specified");return true}if(b(j.rows)&&!b(j.itemWidth)){d.error("gentleSelect: itemWidth must be supplied if 'rows' is specified");return true}if(!b(j.openSpeed)||typeof j.openSpeed!="number"&&(typeof j.openSpeed=="string"&&(j.openSpeed!="slow"&&j.openSpeed!="fast"))){d.error('gentleSelect: openSpeed must be an integer or "slow" or "fast"');return true}if(!b(j.closeSpeed)||typeof j.closeSpeed!="number"&&(typeof j.closeSpeed=="string"&&(j.closeSpeed!="slow"&&j.closeSpeed!="fast"))){d.error('gentleSelect: closeSpeed must be an integer or "slow" or "fast"');return true}if(!b(j.openEffect)||(j.openEffect!="fade"&&j.openEffect!="slide")){d.error("gentleSelect: openEffect must be either 'fade' or 'slide'!");return true}if(!b(j.closeEffect)||(j.closeEffect!="fade"&&j.closeEffect!="slide")){d.error("gentleSelect: closeEffect must be either 'fade' or 'slide'!");return true}if(!b(j.hideOnMouseOut)||(typeof j.hideOnMouseOut!="boolean")){d.error('gentleSelect: hideOnMouseOut must be supplied and either "true" or "false"!');return true}return false}function h(k,j){if(k.attr("multiple")){j.hideOnMouseOut=true}}function f(k,l){if(k.length<1){return l.prompt}if(l.maxDisplay!=0&&k.length>l.maxDisplay){var j=k.slice(0,l.maxDisplay).map(function(){return d(this).text()});j.push("...")}else{var j=k.map(function(){return d(this).text()})}return j.get().join(", ")}function i(m,l){var m=d(m);if(m.attr("multiple")&&l.disallowEmpty){var k=m.data("dialog").find("li"),j=k.filter(".selected");k.removeClass("sole-selected");if(j.length==1){j.addClass("sole-selected")}}}var a={init:function(x){var l=d.extend({},c,x),n=this.find("option");if(g(this,l)){return this}h(this,l);this.hide();if(this.attr("multiple")&&l.disallowEmpty){if(n.length==0){d.error("gentleSelect: disallowEmpty conflicts with empty .... 20 | * 21 | */ 22 | (function($) { 23 | 24 | var defaults = { 25 | minWidth : 100, // only applies if columns and itemWidth not set 26 | itemWidth : undefined, 27 | columns : undefined, 28 | rows : undefined, 29 | title : undefined, 30 | prompt : "Make A Selection", 31 | maxDisplay: 0, // set to 0 for unlimited 32 | openSpeed : 400, 33 | closeSpeed : 400, 34 | openEffect : "slide", 35 | closeEffect : "slide", 36 | disallowEmpty : false, 37 | hideOnMouseOut : true 38 | } 39 | 40 | function defined(obj) { 41 | if (typeof obj == "undefined") { return false; } 42 | else { return true; } 43 | } 44 | 45 | function hasError(c, o) { 46 | if (defined(o.columns) && defined(o.rows)) { 47 | $.error("gentleSelect: You cannot supply both 'rows' and 'columns'"); 48 | return true; 49 | } 50 | if (defined(o.columns) && !defined(o.itemWidth)) { 51 | $.error("gentleSelect: itemWidth must be supplied if 'columns' is specified"); 52 | return true; 53 | } 54 | if (defined(o.rows) && !defined(o.itemWidth)) { 55 | $.error("gentleSelect: itemWidth must be supplied if 'rows' is specified"); 56 | return true; 57 | } 58 | if (!defined(o.openSpeed) || typeof o.openSpeed != "number" && 59 | (typeof o.openSpeed == "string" && (o.openSpeed != "slow" && o.openSpeed != "fast"))) { 60 | $.error("gentleSelect: openSpeed must be an integer or \"slow\" or \"fast\""); 61 | return true; 62 | } 63 | if (!defined(o.closeSpeed) || typeof o.closeSpeed != "number" && 64 | (typeof o.closeSpeed == "string" && (o.closeSpeed != "slow" && o.closeSpeed != "fast"))) { 65 | $.error("gentleSelect: closeSpeed must be an integer or \"slow\" or \"fast\""); 66 | return true; 67 | } 68 | if (!defined(o.openEffect) || (o.openEffect != "fade" && o.openEffect != "slide")) { 69 | $.error("gentleSelect: openEffect must be either 'fade' or 'slide'!"); 70 | return true; 71 | } 72 | if (!defined(o.closeEffect)|| (o.closeEffect != "fade" && o.closeEffect != "slide")) { 73 | $.error("gentleSelect: closeEffect must be either 'fade' or 'slide'!"); 74 | return true; 75 | } 76 | if (!defined(o.hideOnMouseOut) || (typeof o.hideOnMouseOut != "boolean")) { 77 | $.error("gentleSelect: hideOnMouseOut must be supplied and either \"true\" or \"false\"!"); 78 | return true; 79 | } 80 | return false; 81 | } 82 | 83 | function optionOverrides(c, o) { 84 | if (c.attr("multiple")) { 85 | o.hideOnMouseOut = true; // must be true or dialog will never hide 86 | } 87 | } 88 | 89 | function getSelectedAsText(elemList, opts) { 90 | // If no items selected, return prompt 91 | if (elemList.length < 1) { return opts.prompt; } 92 | 93 | // Truncate if exceed maxDisplay 94 | if (opts.maxDisplay != 0 && elemList.length > opts.maxDisplay) { 95 | var arr = elemList.slice(0, opts.maxDisplay).map(function(){return $(this).text();}); 96 | arr.push("..."); 97 | } else { 98 | var arr = elemList.map(function(){return $(this).text();}); 99 | } 100 | return arr.get().join(", "); 101 | } 102 | 103 | function updateState(c, o) { 104 | var c = $(c); 105 | if (c.attr("multiple") && o.disallowEmpty) { 106 | var all_items = c.data("dialog").find("li"), 107 | selected_items = all_items.filter(".selected"); 108 | 109 | // mark element if only one selected 110 | all_items.removeClass("sole-selected"); 111 | if (selected_items.length == 1) { 112 | selected_items.addClass("sole-selected"); 113 | } 114 | } 115 | } 116 | 117 | var methods = { 118 | init : function(options) { 119 | var o = $.extend({}, defaults, options), 120 | select_items = this.find("option"); 121 | 122 | if (hasError(this, o)) { return this; }; // check for errors 123 | optionOverrides(this, o); // 124 | this.hide(); // hide original select box 125 | 126 | if (this.attr("multiple") && o.disallowEmpty) 127 | { 128 | if (select_items.length == 0) { 129 | $.error("gentleSelect: disallowEmpty conflicts with empty 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | compared to a standard select box 106 | 120 |

121 |

122 | And here's select box with multiple selection enabled, processed using gentleSelect with maxDisplay option set to 3 (try selecting more than 3 items): 123 |

124 |

125 | 139 |

140 |

141 | Note that unlike a standard select box, one does not need to use Ctrl-Click (Cmd-Click on macs) to select multiple items. 142 |

143 |

144 | There is much to be done on the flexibility and robustness front, and we welcome contributions 145 | and bug fixes. Feel free to fork the project 146 | and send us pull requests! 147 |

148 |

Download

149 | 153 |

TODO

154 | 159 |

Usage

160 | 161 |

162 | To use this plugin, one simply needs to load jQuery and the JS/CSS scripts for gentleSelect, 163 | then attach it to your select boxes on DOM ready: 164 |

165 | 166 | 
167 | <script type="text/javascript" 
168 |         src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
169 | <script type="text/javascript" src="gentleSelect/jquery-gentleSelect.js"></script>
170 | 
171 | <link type="text/css" href="gentleSelect/jquery-gentleSelect.css" rel="stylesheet" />
172 | 
173 | <script type="text/javascript">
174 |     $(document).ready(function() {
175 |         $('#selector').gentleSelect(); // apply gentleSelect with default options
176 |     });
177 | </script>
178 |
179 | 180 |

181 | This produces a standard single-column select box as such 195 |

196 |

Options

197 | 198 |

title

199 |

200 | You can specify a heading for the selection box using the title option. 201 |

202 | 203 |

204 | For example, 209 | 

210 |     $('#selector').gentleSelect({
211 |         title: "Select a colour"
212 |     });
213 |

214 |

columns & itemWidth

215 |

216 | Specifies the number of columns used to display the selection. The number of rows is 217 | calculated accordingly. When specifying columns, the itemWidth option must also be set. This value must be large enough 218 | to fit the longest option. 219 |

220 | 221 |

222 | For example, can be implemented using: 236 |

237 | 
238 |     $('#selector').gentleSelect({
239 |         columns: 3,
240 |         itemWidth: 100,
241 |     });
242 | 243 |

rows & itemWidth

244 |

245 | There may be situations where one might think it would be more suitable to fix the 246 | number of rows instead, allowing the columns to spread out as required. 247 |

248 | 249 |

250 | This can be achieved by specifying the rows and itemWidth options. 251 |

252 | 253 |

254 | For example, can be implemented using: 287 |

288 | 
289 |     $('#selector').gentleSelect({
290 |         rows: 5,
291 |         itemWidth: 30,
292 |     });
293 | 294 |

openEffect & closeEffect

295 |

296 | Effects to use for displaying and hiding the selection menu. 297 | Possible options are 'fade' and 'slide' (default). 298 |

299 | 300 |

openSpeed & closeSpeed

301 |

302 | Specifies the speed of the open/close animation. 303 | This value is specified in milliseconds; higher values indicate slower animations, not faster ones. 304 | The strings 'slow' and 'fast' can be supplied to indicate an animation duration of 305 | 600 and 200 milliseconds. 306 |

307 | 308 |

The default value is 400.

309 | 310 |

311 | For example, can be implemented using: 325 |

326 | 
327 |     $('#selector').gentleSelect({
328 |         columns: 3,
329 |         itemWidth: 100,
330 |         openEffect: "fade",
331 |         openSpeed: "slow"
332 |     });
333 | 334 |

hideOnMouseOut

335 |

336 | Specifies whether the selection menu should be hidden when the mouse leaves the selection box. 337 | This is true by default. Set to false to disable this behaviour. 338 |

339 | 340 |

341 | For example, (menu only disappears when something is selected) 355 |

356 | 
357 |     $('#selector').gentleSelect({
358 |         columns: 3,
359 |         itemWidth: 100,
360 |         hideOnMouseOut: false
361 |     });
362 |

363 | This option has no effect if multiple is enabled on the selection box. 364 |

365 | 366 |

disallowEmpty

367 |

368 | Specifies that at least one item must be selected at all times. This 369 | applies mainly when multiple selection is enabled. When this is 370 | enable users will not be able to deselect a sole selected item.This is 371 | false by default. Set to true to apply this rule. 372 |

373 | 374 |

375 | Upon initialisation, the first element in the list of options will 376 | be selected if none were previously selected. 377 |

378 | 379 |

380 | For example, (the sole selected item cannot be deselected). 394 |

395 | 
396 |     $('#selector').gentleSelect({
397 |         columns: 3,
398 |         itemWidth: 100,
399 |         disallowEmpty: true
400 |     });
401 | 402 |

403 | Applying disallowEmpty on a select box with no options will 404 | result in an error being raised. 405 |

406 | 407 |

maxDisplay

408 |

409 | Specifies the maximum number of items to display when multiple selection is enabled. When 410 | the number of selected items exceed a specified value. say 5, then only the first 411 | 5 items are displayed (delimited by comma) followed by "..." to indicate 412 | that some selected items are hidden. 413 | 414 | The default value is 0 (no limit). 415 | 416 |

417 |

Methods

418 |

update

419 |

420 | If you update the value of the select box using an external script, 421 | you can update the display by calling the update function. 422 |

423 | 424 | 425 | 
426 |     // assssuming gentleSelect() previously initialised
427 |     $('#selector').val(3).gentleSelect("update");
428 | 429 |

clear

430 |

431 | Clears all selections. For example: 432 | 446 | 447 |

448 | 449 | 
450 |     // assssuming gentleSelect() previously initialised
451 |     $('#selector').gentleSelect("clear");
452 | 453 |

454 | Note that this method is disabled when 455 | disallowEmpty 456 | is set true. 457 |

458 | 459 | 460 | 466 | Fork me on GitHub 467 | 468 | 469 | 470 | --------------------------------------------------------------------------------