/**
* This plugin provides a generic way to add suggestions to a text box.
*
- * Usage:
- *
* Set options:
+ *
* $( '#textbox' ).suggestions( { option1: value1, option2: value2 } );
* $( '#textbox' ).suggestions( option, value );
+ *
* Get option:
+ *
* value = $( '#textbox' ).suggestions( option );
+ *
* Initialize:
+ *
* $( '#textbox' ).suggestions();
*
- * Options:
+ * Uses jQuery.suggestions singleteon internally.
*
- * fetch(query): Callback that should fetch suggestions and set the suggestions property.
- * Executed in the context of the textbox
- * Type: Function
- * cancel: Callback function to call when any pending asynchronous suggestions fetches
- * should be canceled. Executed in the context of the textbox
- * Type: Function
- * special: Set of callbacks for rendering and selecting
- * Type: Object of Functions 'render' and 'select'
- * result: Set of callbacks for rendering and selecting
- * Type: Object of Functions 'render' and 'select'
- * $region: jQuery selection of element to place the suggestions below and match width of
- * Type: jQuery Object, Default: $( this )
- * suggestions: Suggestions to display
- * Type: Array of strings
- * maxRows: Maximum number of suggestions to display at one time
- * Type: Number, Range: 1 - 100, Default: 10
- * delay: Number of ms to wait for the user to stop typing
- * Type: Number, Range: 0 - 1200, Default: 120
- * cache: Whether to cache results from a fetch
- * Type: Boolean, Default: false
- * cacheMaxAge: Number of ms to cache results from a fetch
- * Type: Number, Range: 1 - Infinity, Default: 60000 (1 minute)
- * submitOnClick: Whether to submit the form containing the textbox when a suggestion is clicked
- * Type: Boolean, Default: false
- * maxExpandFactor: Maximum suggestions box width relative to the textbox width. If set
- * to e.g. 2, the suggestions box will never be grown beyond 2 times the width of the textbox.
- * Type: Number, Range: 1 - infinity, Default: 3
- * expandFrom: Which direction to offset the suggestion box from.
- * Values 'start' and 'end' translate to left and right respectively depending on the
- * directionality of the current document, according to $( 'html' ).css( 'direction' ).
- * Type: String, default: 'auto', options: 'left', 'right', 'start', 'end', 'auto'.
- * positionFromLeft: Sets expandFrom=left, for backwards compatibility
- * Type: Boolean, Default: true
- * highlightInput: Whether to hightlight matched portions of the input or not
- * Type: Boolean, Default: false
+ * @class jQuery.plugin.suggestions
+ */
+/**
+ * @method suggestions
+ * @return {jQuery}
+ * @chainable
+ *
+ * @param {Object} options
+ *
+ * @param {Function} [options.fetch] Callback that should fetch suggestions and set the suggestions
+ * property. Called in context of the text box.
+ * @param {string} options.fetch.query
+ * @param {Function} options.fetch.response Callback to receive the suggestions with
+ * @param {Array} options.fetch.response.suggestions
+ * @param {number} options.fetch.maxRows
+ *
+ * @param {Function} [options.cancel] Callback function to call when any pending asynchronous
+ * suggestions fetches. Called in context of the text box.
+ *
+ * @param {Object} [options.special] Set of callbacks for rendering and selecting.
+ *
+ * @param {Function} options.special.render Called in context of the suggestions-special element.
+ * @param {string} options.special.render.query
+ * @param {Object} options.special.render.context
+ *
+ * @param {Function} options.special.select Called in context of the suggestions-result-current element.
+ * @param {jQuery} options.special.select.$textbox
+ *
+ * @param {Object} [options.result] Set of callbacks for rendering and selecting
+ *
+ * @param {Function} options.result.render Called in context of the suggestions-result element.
+ * @param {string} options.result.render.suggestion
+ * @param {Object} options.result.render.context
+ *
+ * @param {Function} options.result.select Called in context of the suggestions-result-current element.
+ * @param {jQuery} options.result.select.$textbox
+ *
+ * @param {Object} [options.update] Set of callbacks for listening to a change in the text input.
+ *
+ * @param {Function} options.update.before Called right after the user changes the textbox text.
+ * @param {Function} options.update.after Called after results are updated either from the cache or
+ * the API as a result of the user input.
+ *
+ * @param {jQuery} [options.$region=this] The element to place the suggestions below and match width of.
+ *
+ * @param {string[]} [options.suggestions] Array of suggestions to display.
+ *
+ * @param {number} [options.maxRows=10] Maximum number of suggestions to display at one time.
+ * Must be between 1 and 100.
+ *
+ * @param {number} [options.delay=120] Number of milliseconds to wait for the user to stop typing.
+ * Must be between 0 and 1200.
+ *
+ * @param {boolean} [options.cache=false] Whether to cache results from a fetch.
+ *
+ * @param {number} [options.cacheMaxAge=60000] Number of milliseconds to cache results from a fetch.
+ * Must be higher than 1. Defaults to 1 minute.
+ *
+ * @param {boolean} [options.submitOnClick=false] Whether to submit the form containing the textbox
+ * when a suggestion is clicked.
+ *
+ * @param {number} [options.maxExpandFactor=3] Maximum suggestions box width relative to the textbox
+ * width. If set to e.g. 2, the suggestions box will never be grown beyond 2 times the width of
+ * the textbox. Must be higher than 1.
+ *
+ * @param {string} [options.expandFrom=auto] Which direction to offset the suggestion box from.
+ * Values 'start' and 'end' translate to left and right respectively depending on the directionality
+ * of the current document, according to `$( 'html' ).css( 'direction' )`.
+ * Valid values: "left", "right", "start", "end", and "auto".
+ *
+ * @param {boolean} [options.positionFromLeft] Sets `expandFrom=left`, for backwards
+ * compatibility.
+ *
+ * @param {boolean} [options.highlightInput=false] Whether to highlight matched portions of the
+ * input or not.
*/
( function ( $ ) {
var hasOwn = Object.hasOwnProperty;
+/**
+ * Used by jQuery.plugin.suggestions.
+ *
+ * @class jQuery.suggestions
+ * @singleton
+ * @private
+ */
$.suggestions = {
/**
* Cancel any delayed maybeFetch() call and callback the context so
* call to this function still pending will be canceled. If the value in the
* textbox is empty or hasn't changed since the last time suggestions were fetched,
* this function does nothing.
- * @param {Boolean} delayed Whether or not to delay this by the currently configured amount of time
+ * @param {boolean} delayed Whether or not to delay this by the currently configured amount of time
*/
update: function ( context, delayed ) {
function maybeFetch() {
cache = context.data.cache,
cacheHit;
+ if ( typeof context.config.update.before === 'function' ) {
+ context.config.update.before.call( context.data.$textbox );
+ }
+
// Only fetch if the value in the textbox changed and is not empty, or if the results were hidden
// if the textbox is empty then clear the result div, but leave other settings intouched
if ( val.length === 0 ) {
if ( context.config.cache && hasOwn.call( cache, val ) ) {
if ( +new Date() - cache[ val ].timestamp < context.config.cacheMaxAge ) {
context.data.$textbox.suggestions( 'suggestions', cache[ val ].suggestions );
+ if ( typeof context.config.update.after === 'function' ) {
+ context.config.update.after.call( context.data.$textbox );
+ }
cacheHit = true;
} else {
// Cache expired
function ( suggestions ) {
suggestions = suggestions.slice( 0, context.config.maxRows );
context.data.$textbox.suggestions( 'suggestions', suggestions );
+ if ( typeof context.config.update.after === 'function' ) {
+ context.config.update.after.call( context.data.$textbox );
+ }
if ( context.config.cache ) {
cache[ val ] = {
suggestions: suggestions,
/**
* Sets the value of a property, and updates the widget accordingly
- * @param property String Name of property
- * @param value Mixed Value to set property with
+ * @param {string} property Name of property
+ * @param {Mixed} value Value to set property with
*/
configure: function ( context, property, value ) {
var newCSS,
case 'cancel':
case 'special':
case 'result':
+ case 'update':
case '$region':
case 'expandFrom':
- context.config[property] = value;
+ context.config[ property ] = value;
break;
case 'suggestions':
- context.config[property] = value;
+ context.config[ property ] = value;
// Update suggestions
if ( context.data !== undefined ) {
if ( context.data.$textbox.val().length === 0 ) {
expandFrom = 'left';
// Catch invalid values, default to 'auto'
- } else if ( $.inArray( expandFrom, ['left', 'right', 'start', 'end', 'auto'] ) === -1 ) {
+ } else if ( $.inArray( expandFrom, [ 'left', 'right', 'start', 'end', 'auto' ] ) === -1 ) {
expandFrom = 'auto';
}
expWidth = -1;
for ( i = 0; i < context.config.suggestions.length; i++ ) {
/*jshint loopfunc:true */
- text = context.config.suggestions[i];
+ text = context.config.suggestions[ i ];
$result = $( '<div>' )
.addClass( 'suggestions-result' )
.attr( 'rel', i )
- .data( 'text', context.config.suggestions[i] )
+ .data( 'text', context.config.suggestions[ i ] )
.mousemove( function () {
context.data.selectedWithMouse = true;
$.suggestions.highlight(
.appendTo( $results );
// Allow custom rendering
if ( typeof context.config.result.render === 'function' ) {
- context.config.result.render.call( $result, context.config.suggestions[i], context );
+ context.config.result.render.call( $result, context.config.suggestions[ i ], context );
} else {
$result.text( text );
}
}
break;
case 'maxRows':
- context.config[property] = Math.max( 1, Math.min( 100, value ) );
+ context.config[ property ] = Math.max( 1, Math.min( 100, value ) );
break;
case 'delay':
- context.config[property] = Math.max( 0, Math.min( 1200, value ) );
+ context.config[ property ] = Math.max( 0, Math.min( 1200, value ) );
break;
case 'cacheMaxAge':
- context.config[property] = Math.max( 1, value );
+ context.config[ property ] = Math.max( 1, value );
break;
case 'maxExpandFactor':
- context.config[property] = Math.max( 1, value );
+ context.config[ property ] = Math.max( 1, value );
break;
case 'cache':
case 'submitOnClick':
case 'positionFromLeft':
case 'highlightInput':
- context.config[property] = !!value;
+ context.config[ property ] = !!value;
break;
}
},
/**
* Highlight a result in the results table
- * @param result <tr> to highlight: jQuery object, or 'prev' or 'next'
- * @param updateTextbox If true, put the suggestion in the textbox
+ * @param {jQuery|string} result `<tr>` to highlight, or 'prev' or 'next'
+ * @param {boolean} updateTextbox If true, put the suggestion in the textbox
*/
highlight: function ( context, result, updateTextbox ) {
var selected = context.data.$container.find( '.suggestions-result-current' );
/**
* Respond to keypress event
- * @param key Integer Code of key pressed
+ * @param {number} key Code of key pressed
*/
keypress: function ( e, context, key ) {
var selected,
}
}
};
+
+// See file header for method documentation
$.fn.suggestions = function () {
// Multi-context fields
$( this ).each( function () {
var context, key;
- /* Construction / Loading */
+ /* Construction and Loading */
context = $( this ).data( 'suggestions-context' );
if ( context === undefined || context === null ) {
cancel: function () {},
special: {},
result: {},
+ update: {},
$region: $( this ),
suggestions: [],
maxRows: 10,
// Handle various calling styles
if ( args.length > 0 ) {
- if ( typeof args[0] === 'object' ) {
+ if ( typeof args[ 0 ] === 'object' ) {
// Apply set of properties
- for ( key in args[0] ) {
- $.suggestions.configure( context, key, args[0][key] );
+ for ( key in args[ 0 ] ) {
+ $.suggestions.configure( context, key, args[ 0 ][ key ] );
}
- } else if ( typeof args[0] === 'string' ) {
+ } else if ( typeof args[ 0 ] === 'string' ) {
if ( args.length > 1 ) {
// Set property values
- $.suggestions.configure( context, args[0], args[1] );
+ $.suggestions.configure( context, args[ 0 ], args[ 1 ] );
} else if ( returnValue === null || returnValue === undefined ) {
// Get property values, but don't give access to internal data - returns only the first
- returnValue = ( args[0] in context.config ? undefined : context.config[args[0]] );
+ returnValue = ( args[ 0 ] in context.config ? undefined : context.config[ args[ 0 ] ] );
}
}
}
return returnValue !== undefined ? returnValue : $( this );
};
+/**
+ * @class jQuery
+ * @mixins jQuery.plugin.suggestions
+ */
+
}( jQuery ) );
dépôts / lhc / web / wiklou.git / blobdiff