2 * This plugin provides a generic way to add suggestions to a text box.
7 * $( '#textbox' ).suggestions( { option1: value1, option2: value2 } );
8 * $( '#textbox' ).suggestions( option, value );
10 * value = $( '#textbox' ).suggestions( option );
12 * $( '#textbox' ).suggestions();
16 * fetch(query): Callback that should fetch suggestions and set the suggestions property. Executed in the context of the
19 * cancel: Callback function to call when any pending asynchronous suggestions fetches should be canceled.
20 * Executed in the context of the textbox
22 * special: Set of callbacks for rendering and selecting
23 * Type: Object of Functions 'render' and 'select'
24 * result: Set of callbacks for rendering and selecting
25 * Type: Object of Functions 'render' and 'select'
26 * $region: jQuery selection of element to place the suggestions below and match width of
27 * Type: jQuery Object, Default: $(this)
28 * suggestions: Suggestions to display
29 * Type: Array of strings
30 * maxRows: Maximum number of suggestions to display at one time
31 * Type: Number, Range: 1 - 100, Default: 7
32 * delay: Number of ms to wait for the user to stop typing
33 * Type: Number, Range: 0 - 1200, Default: 120
34 * submitOnClick: Whether to submit the form containing the textbox when a suggestion is clicked
35 * Type: Boolean, Default: false
36 * maxExpandFactor: Maximum suggestions box width relative to the textbox width. If set to e.g. 2, the suggestions box
37 * will never be grown beyond 2 times the width of the textbox.
38 * Type: Number, Range: 1 - infinity, Default: 3
39 * positionFromLeft: Whether to position the suggestion box with the left attribute or the right
40 * Type: Boolean, Default: true
41 * highlightInput: Whether to hightlight matched portions of the input or not
42 * Type: Boolean, Default: false
48 * Cancel any delayed updateSuggestions() call and inform the user so
49 * they can cancel their result fetching if they use AJAX or something
51 cancel: function ( context
) {
52 if ( context
.data
.timerID
!== null ) {
53 clearTimeout( context
.data
.timerID
);
55 if ( $.isFunction( context
.config
.cancel
) ) {
56 context
.config
.cancel
.call( context
.data
.$textbox
);
60 * Restore the text the user originally typed in the textbox, before it was overwritten by highlight(). This
61 * restores the value the currently displayed suggestions are based on, rather than the value just before
62 * highlight() overwrote it; the former is arguably slightly more sensible.
64 restore: function ( context
) {
65 context
.data
.$textbox
.val( context
.data
.prevText
);
68 * Ask the user-specified callback for new suggestions. Any previous delayed call to this function still pending
69 * will be canceled. If the value in the textbox is empty or hasn't changed since the last time suggestions were fetched, this
70 * function does nothing.
71 * @param {Boolean} delayed Whether or not to delay this by the currently configured amount of time
73 update: function ( context
, delayed
) {
74 // Only fetch if the value in the textbox changed and is not empty
75 // if the textbox is empty then clear the result div, but leave other settings intouched
76 function maybeFetch() {
77 if ( context
.data
.$textbox
.val().length
=== 0 ) {
78 context
.data
.$container
.hide();
79 context
.data
.prevText
= '';
80 } else if ( context
.data
.$textbox
.val() !== context
.data
.prevText
) {
81 if ( typeof context
.config
.fetch
=== 'function' ) {
82 context
.data
.prevText
= context
.data
.$textbox
.val();
83 context
.config
.fetch
.call( context
.data
.$textbox
, context
.data
.$textbox
.val() );
88 // Cancel previous call
89 if ( context
.data
.timerID
!== null ) {
90 clearTimeout( context
.data
.timerID
);
93 // Start a new asynchronous call
94 context
.data
.timerID
= setTimeout( maybeFetch
, context
.config
.delay
);
98 $.suggestions
.special( context
);
100 special: function ( context
) {
101 // Allow custom rendering - but otherwise don't do any rendering
102 if ( typeof context
.config
.special
.render
=== 'function' ) {
103 // Wait for the browser to update the value
104 setTimeout( function () {
106 var $special
= context
.data
.$container
.find( '.suggestions-special' );
107 context
.config
.special
.render
.call( $special
, context
.data
.$textbox
.val() );
112 * Sets the value of a property, and updates the widget accordingly
113 * @param property String Name of property
114 * @param value Mixed Value to set property with
116 configure: function ( context
, property
, value
) {
117 // Validate creation using fallback values
124 context
.config
[property
] = value
;
127 context
.config
[property
] = value
;
128 // Update suggestions
129 if ( context
.data
!== undefined ) {
130 if ( context
.data
.$textbox
.val().length
=== 0 ) {
131 // Hide the div when no suggestion exist
132 context
.data
.$container
.hide();
134 // Rebuild the suggestions list
135 context
.data
.$container
.show();
136 // Update the size and position of the list
138 top
: context
.config
.$region
.offset().top
+ context
.config
.$region
.outerHeight(),
140 width
: context
.config
.$region
.outerWidth(),
143 if ( context
.config
.positionFromLeft
) {
144 newCSS
.left
= context
.config
.$region
.offset().left
;
145 newCSS
.right
= 'auto';
147 newCSS
.left
= 'auto';
148 newCSS
.right
= $( 'body' ).width() - ( context
.config
.$region
.offset().left
+ context
.config
.$region
.outerWidth() );
150 context
.data
.$container
.css( newCSS
);
151 var $results
= context
.data
.$container
.children( '.suggestions-results' );
154 var $autoEllipseMe
= $( [] );
155 var matchedText
= null;
156 for ( var i
= 0; i
< context
.config
.suggestions
.length
; i
++ ) {
157 /*jshint loopfunc:true */
158 var text
= context
.config
.suggestions
[i
];
159 var $result
= $( '<div>' )
160 .addClass( 'suggestions-result' )
162 .data( 'text', context
.config
.suggestions
[i
] )
163 .mousemove( function ( e
) {
164 context
.data
.selectedWithMouse
= true;
165 $.suggestions
.highlight(
166 context
, $(this).closest( '.suggestions-results div' ), false
169 .appendTo( $results
);
170 // Allow custom rendering
171 if ( typeof context
.config
.result
.render
=== 'function' ) {
172 context
.config
.result
.render
.call( $result
, context
.config
.suggestions
[i
] );
174 // Add <span> with text
175 if( context
.config
.highlightInput
) {
176 matchedText
= context
.data
.prevText
;
178 $result
.append( $( '<span>' )
179 .css( 'whiteSpace', 'nowrap' )
183 // Widen results box if needed
184 // New width is only calculated here, applied later
185 var $span
= $result
.children( 'span' );
186 if ( $span
.outerWidth() > $result
.width() && $span
.outerWidth() > expWidth
) {
187 // factor in any padding, margin, or border space on the parent
188 expWidth
= $span
.outerWidth() + ( context
.data
.$container
.width() - $span
.parent().width());
190 $autoEllipseMe
= $autoEllipseMe
.add( $result
);
193 // Apply new width for results box, if any
194 if ( expWidth
> context
.data
.$container
.width() ) {
195 var maxWidth
= context
.config
.maxExpandFactor
*context
.data
.$textbox
.width();
196 context
.data
.$container
.width( Math
.min( expWidth
, maxWidth
) );
198 // autoEllipse the results. Has to be done after changing the width
199 $autoEllipseMe
.autoEllipsis( { hasSpan
: true, tooltip
: true, matchText
: matchedText
} );
204 context
.config
[property
] = Math
.max( 1, Math
.min( 100, value
) );
207 context
.config
[property
] = Math
.max( 0, Math
.min( 1200, value
) );
209 case 'maxExpandFactor':
210 context
.config
[property
] = Math
.max( 1, value
);
212 case 'submitOnClick':
213 case 'positionFromLeft':
214 case 'highlightInput':
215 context
.config
[property
] = value
? true : false;
220 * Highlight a result in the results table
221 * @param result <tr> to highlight: jQuery object, or 'prev' or 'next'
222 * @param updateTextbox If true, put the suggestion in the textbox
224 highlight: function ( context
, result
, updateTextbox
) {
225 var selected
= context
.data
.$container
.find( '.suggestions-result-current' );
226 if ( !result
.get || selected
.get( 0 ) !== result
.get( 0 ) ) {
227 if ( result
=== 'prev' ) {
228 if( selected
.is( '.suggestions-special' ) ) {
229 result
= context
.data
.$container
.find( '.suggestions-result:last' );
231 result
= selected
.prev();
232 if ( selected
.length
=== 0 ) {
233 // we are at the beginning, so lets jump to the last item
234 if ( context
.data
.$container
.find( '.suggestions-special' ).html() !== '' ) {
235 result
= context
.data
.$container
.find( '.suggestions-special' );
237 result
= context
.data
.$container
.find( '.suggestions-results div:last' );
241 } else if ( result
=== 'next' ) {
242 if ( selected
.length
=== 0 ) {
243 // No item selected, go to the first one
244 result
= context
.data
.$container
.find( '.suggestions-results div:first' );
245 if ( result
.length
=== 0 && context
.data
.$container
.find( '.suggestions-special' ).html() !== '' ) {
246 // No suggestion exists, go to the special one directly
247 result
= context
.data
.$container
.find( '.suggestions-special' );
250 result
= selected
.next();
251 if ( selected
.is( '.suggestions-special' ) ) {
254 result
.length
=== 0 &&
255 context
.data
.$container
.find( '.suggestions-special' ).html() !== ''
257 // We were at the last item, jump to the specials!
258 result
= context
.data
.$container
.find( '.suggestions-special' );
262 selected
.removeClass( 'suggestions-result-current' );
263 result
.addClass( 'suggestions-result-current' );
265 if ( updateTextbox
) {
266 if ( result
.length
=== 0 || result
.is( '.suggestions-special' ) ) {
267 $.suggestions
.restore( context
);
269 context
.data
.$textbox
.val( result
.data( 'text' ) );
270 // .val() doesn't call any event handlers, so
271 // let the world know what happened
272 context
.data
.$textbox
.change();
274 context
.data
.$textbox
.trigger( 'change' );
278 * Respond to keypress event
279 * @param key Integer Code of key pressed
281 keypress: function ( e
, context
, key
) {
282 var wasVisible
= context
.data
.$container
.is( ':visible' ),
283 preventDefault
= false;
288 $.suggestions
.highlight( context
, 'next', true );
289 context
.data
.selectedWithMouse
= false;
291 $.suggestions
.update( context
, false );
293 preventDefault
= true;
298 $.suggestions
.highlight( context
, 'prev', true );
299 context
.data
.selectedWithMouse
= false;
301 preventDefault
= wasVisible
;
305 context
.data
.$container
.hide();
306 $.suggestions
.restore( context
);
307 $.suggestions
.cancel( context
);
308 context
.data
.$textbox
.trigger( 'change' );
309 preventDefault
= wasVisible
;
313 context
.data
.$container
.hide();
314 preventDefault
= wasVisible
;
315 var selected
= context
.data
.$container
.find( '.suggestions-result-current' );
316 if ( selected
.length
=== 0 || context
.data
.selectedWithMouse
) {
317 // if nothing is selected OR if something was selected with the mouse,
318 // cancel any current requests and submit the form
319 $.suggestions
.cancel( context
);
320 context
.config
.$region
.closest( 'form' ).submit();
321 } else if ( selected
.is( '.suggestions-special' ) ) {
322 if ( typeof context
.config
.special
.select
=== 'function' ) {
323 context
.config
.special
.select
.call( selected
, context
.data
.$textbox
);
326 if ( typeof context
.config
.result
.select
=== 'function' ) {
327 $.suggestions
.highlight( context
, selected
, true );
328 context
.config
.result
.select
.call( selected
, context
.data
.$textbox
);
330 $.suggestions
.highlight( context
, selected
, true );
335 $.suggestions
.update( context
, true );
338 if ( preventDefault
) {
340 e
.stopImmediatePropagation();
344 $.fn
.suggestions = function () {
346 // Multi-context fields
348 var args
= arguments
;
350 $(this).each( function () {
352 /* Construction / Loading */
354 var context
= $(this).data( 'suggestions-context' );
355 if ( context
=== undefined || context
=== null ) {
358 'fetch' : function () {},
359 'cancel': function () {},
366 'submitOnClick': false,
367 'maxExpandFactor': 3,
368 'positionFromLeft': true,
369 'highlightInput': false
376 // Handle various calling styles
377 if ( args
.length
> 0 ) {
378 if ( typeof args
[0] === 'object' ) {
379 // Apply set of properties
380 for ( var key
in args
[0] ) {
381 $.suggestions
.configure( context
, key
, args
[0][key
] );
383 } else if ( typeof args
[0] === 'string' ) {
384 if ( args
.length
> 1 ) {
385 // Set property values
386 $.suggestions
.configure( context
, args
[0], args
[1] );
387 } else if ( returnValue
=== null || returnValue
=== undefined ) {
388 // Get property values, but don't give access to internal data - returns only the first
389 returnValue
= ( args
[0] in context
.config
? undefined : context
.config
[args
[0]] );
396 if ( context
.data
=== undefined ) {
398 // ID of running timer
401 // Text in textbox when suggestions were last fetched
404 // Number of results visible without scrolling
407 // Suggestion the last mousedown event occured on
408 mouseDownOn
: $( [] ),
410 selectedWithMouse
: false
412 // Setup the css for positioning the results box
414 top
: Math
.round( context
.data
.$textbox
.offset().top
+ context
.data
.$textbox
.outerHeight() ),
415 width
: context
.data
.$textbox
.outerWidth(),
418 if ( context
.config
.positionFromLeft
) {
419 newCSS
.left
= context
.config
.$region
.offset().left
;
420 newCSS
.right
= 'auto';
422 newCSS
.left
= 'auto';
423 newCSS
.right
= $( 'body' ).width() - ( context
.config
.$region
.offset().left
+ context
.config
.$region
.outerWidth() );
426 context
.data
.$container
= $( '<div>' )
428 .addClass( 'suggestions' )
430 $( '<div>' ).addClass( 'suggestions-results' )
431 // Can't use click() because the container div is hidden when the textbox loses focus. Instead,
432 // listen for a mousedown followed by a mouseup on the same div
433 .mousedown( function ( e
) {
434 context
.data
.mouseDownOn
= $( e
.target
).closest( '.suggestions-results div' );
436 .mouseup( function ( e
) {
437 var $result
= $( e
.target
).closest( '.suggestions-results div' );
438 var $other
= context
.data
.mouseDownOn
;
439 context
.data
.mouseDownOn
= $( [] );
440 if ( $result
.get( 0 ) !== $other
.get( 0 ) ) {
443 $.suggestions
.highlight( context
, $result
, true );
444 context
.data
.$container
.hide();
445 if ( typeof context
.config
.result
.select
=== 'function' ) {
446 context
.config
.result
.select
.call( $result
, context
.data
.$textbox
);
448 context
.data
.$textbox
.focus();
452 $( '<div>' ).addClass( 'suggestions-special' )
453 // Can't use click() because the container div is hidden when the textbox loses focus. Instead,
454 // listen for a mousedown followed by a mouseup on the same div
455 .mousedown( function ( e
) {
456 context
.data
.mouseDownOn
= $( e
.target
).closest( '.suggestions-special' );
458 .mouseup( function ( e
) {
459 var $special
= $( e
.target
).closest( '.suggestions-special' );
460 var $other
= context
.data
.mouseDownOn
;
461 context
.data
.mouseDownOn
= $( [] );
462 if ( $special
.get( 0 ) !== $other
.get( 0 ) ) {
465 context
.data
.$container
.hide();
466 if ( typeof context
.config
.special
.select
=== 'function' ) {
467 context
.config
.special
.select
.call( $special
, context
.data
.$textbox
);
469 context
.data
.$textbox
.focus();
471 .mousemove( function ( e
) {
472 context
.data
.selectedWithMouse
= true;
473 $.suggestions
.highlight(
474 context
, $( e
.target
).closest( '.suggestions-special' ), false
478 .appendTo( $( 'body' ) );
480 // Stop browser autocomplete from interfering
481 .attr( 'autocomplete', 'off')
482 .keydown( function ( e
) {
483 // Store key pressed to handle later
484 context
.data
.keypressed
= e
.which
;
485 context
.data
.keypressedCount
= 0;
487 switch ( context
.data
.keypressed
) {
488 // This preventDefault logic is duplicated from
489 // $.suggestions.keypress(), which sucks
492 e
.stopImmediatePropagation();
497 if ( context
.data
.$container
.is( ':visible' ) ) {
499 e
.stopImmediatePropagation();
503 .keypress( function ( e
) {
504 context
.data
.keypressedCount
++;
505 $.suggestions
.keypress( e
, context
, context
.data
.keypressed
);
507 .keyup( function ( e
) {
508 // Some browsers won't throw keypress() for arrow keys. If we got a keydown and a keyup without a
509 // keypress in between, solve it
510 if ( context
.data
.keypressedCount
=== 0 ) {
511 $.suggestions
.keypress( e
, context
, context
.data
.keypressed
);
515 // When losing focus because of a mousedown
516 // on a suggestion, don't hide the suggestions
517 if ( context
.data
.mouseDownOn
.length
> 0 ) {
520 context
.data
.$container
.hide();
521 $.suggestions
.cancel( context
);
524 // Store the context for next time
525 $(this).data( 'suggestions-context', context
);
527 return returnValue
!== undefined ? returnValue
: $(this);