autocomplete-debug.js revision c1fa7383daa25ffc775ef46e12aedd49d03d3ed7
696N/A * Provides automatic input completion or suggestions for text input fields and 696N/A * <code>Y.Base</code> extension that provides core autocomplete logic (but no 696N/A * UI implementation) for a text input field or textarea. Must be mixed into a 696N/A * <code>Y.Base</code>-derived class to be useful. 696N/A * @submodule autocomplete-base 696N/A * Extension that provides core autocomplete logic (but no UI implementation) 696N/A * for a text input field or textarea. 696N/A * The <code>AutoCompleteBase</code> class provides events and attributes that 696N/A * abstract away core autocomplete logic and configuration, but does not provide 696N/A * a widget implementation or suggestion UI. For a prepackaged autocomplete 696N/A * widget, see <code>AutoCompleteList</code>. 696N/A * This extension cannot be instantiated directly, since it doesn't provide an 696N/A * actual implementation. It's intended to be mixed into a 696N/A * <code>Base</code>-based class or widget, as illustrated in the following 696N/A * YUI().use('autocomplete-base', 'base', function (Y) { 696N/A * var MyAutoComplete = Y.Base.create('myAutocomplete', Y.Base, [Y.AutoComplete], { 696N/A * initializer: function () { 696N/A * this.bindInput(); 696N/A * this.syncInput(); 696N/A * }, 696N/A * destructor: function () { 696N/A * this.unbindInput(); 696N/A * } 696N/A * // ... custom implementation code ... * @class AutoCompleteBase * Fires after the contents of the input field have been completely cleared. * @param {EventFacade} e Event facade with the following additional * <dt>prevVal (String)</dt> * Value of the input node before it was cleared. * @preventable _defClearFn * Fires when the contents of the input field have changed and the input * value meets the criteria necessary to generate an autocomplete query. * @param {EventFacade} e Event facade with the following additional * <dt>inputValue (String)</dt> * Full contents of the text input field or textarea that generated * <dt>query (String)</dt> * Autocomplete query. This is the string that will be used to * request completion results. It may or may not be the same as * <code>inputValue</code>. * @preventable _defQueryFn * Fires after query results are received from the DataSource. If no * DataSource has been set, this event will not fire. * @param {EventFacade} e Event facade with the following additional * <dt>data (Array|Object)</dt> * Raw, unfiltered result data (if available). * <dt>query (String)</dt> * Query that generated these results. * <dt>results (Array)</dt> * Array of filtered, formatted, and highlighted results. Each item in * the array is an object with the following properties: * <dt>display (Node|HTMLElement|String)</dt> * Formatted result HTML suitable for display to the user. * Raw, unformatted result in whatever form it was provided by the * Plain text version of the result, suitable for being inserted * into the value of a text input field or textarea when the result * @preventable _defResultsFn * Fires after the input node's value changes, and before the * <code>query</code> event. * @param {EventFacade} e Event facade with the following additional * <dt>newVal (String)</dt> * Value of the input node after the change. * <dt>prevVal (String)</dt> * Value of the input node prior to the change. // -- Public Static Properties ------------------------------------------------- * Whether or not to enable the browser's built-in autocomplete * functionality for input fields. * @attribute allowBrowserAutocomplete * DataSource object which will be used to make queries. This can be * an actual DataSource instance or any other object with a * sendRequest() method that has the same signature as DataSource's * As an alternative to providing a DataSource, you could listen for * <code>query</code> events and handle them any way you see fit. * Providing a DataSource or DataSource-like object is optional, but * @type DataSource|Object|null * Node to monitor for changes, which will generate <code>query</code> * events when appropriate. May be either an input field or a textarea. * @type Node|HTMLElement|String * Minimum number of characters that must be entered before a * <code>query</code> event will be fired. A value of <code>0</code> * allows empty queries; a negative value will effectively disable all * <code>query</code> events. * @attribute minQueryLength * Current query, or <code>null</code> if there is no current query. * The query might not be the same as the current value of the input * node, both for timing reasons (due to <code>queryDelay</code>) and * because when one or more <code>queryDelimiter</code> separators are * in use, only the last portion of the delimited input string will be * used as the query value. * Number of milliseconds to delay after input before triggering a * <code>query</code> event. If new input occurs before this delay is * over, the previous input event will be ignored and a new delay will * This can be useful both to throttle queries to a remote data source * and to avoid distracting the user by showing them less relevant * results before they've paused their typing. * DataSource request template. This can be a function that accepts a * query as a parameter and returns a request string, or it can be a * string containing the placeholder "{query}", which will be replaced * with the actual URI-encoded query. * When using a string template, if it's necessary for the literal * string "{query}" to appear in the request, escape it with a slash: * While <code>requestTemplate</code> may be set to either a function or * a string, it will always be returned as a function that accepts a * query argument and returns a string. * @attribute requestTemplate * @default encodeURIComponent return function (
query) {
// Replace {query} with the URI-encoded query, but turn // \{query} into the literal string "{query}" to allow that // string to appear in the request if necessary. * Array of local result filter functions. If provided, each filter * will be called with two arguments when results are received: the query * and an array of results (as returned by the <code>resultLocator</code>, * Each filter is expected to return a filtered or modified version of the * results, which will then be passed on to subsequent filters, then the * <code>resultHighlighter</code> function (if set), then the * <code>resultFormatter</code> function (if set), and finally to * subscribers to the <code>results</code> event. * If no DataSource is set, result filters will not be called. * @attribute resultFilters * Function which will be used to format results. If provided, this function * will be called with four arguments after results have been received and * filtered: the query, an array of raw results, an array of highlighted * results, and an array of plain text results. The formatter is expected to * return a modified copy of the results array with any desired custom * If no DataSource is set, the formatter will not be called. * @attribute resultFormatter * Function which will be used to highlight results. If provided, this * function will be called with two arguments after results have been * received and filtered: the query and an array of filtered results. The * highlighter is expected to return a modified version of the results * array with the query highlighted in some form. * If no DataSource is set, the highlighter will not be called. * @attribute resultHighlighter * Locator that should be used to extract a plain text string from a * non-string result item. This value will be fed to any defined filters, * and will typically also be the value that ends up being inserted into a * text input field or textarea when the user of an autocomplete widget * implementation selects a result. * By default, no locator is applied, and all results are assumed to be * plain text strings. If all results are already plain text strings, you * don't need to define a locator. * The locator may be either a function (which will receive the raw result * as an argument and must return a string) or a string representing an * object path, such as "foo.bar.baz" (which would return the value of * <code>result.foo.bar.baz</code> if the result is an object). * While <code>resultLocator</code> may be set to either a function or a * string, it will always be returned as a function that accepts a result * argument and returns a string. * @attribute resultLocator * @type Function|String|null * Current results, or an empty array if there are no results. // Because nobody wants to type ".yui3-autocomplete-blah" a hundred times. // -- Public Lifecycle Methods --------------------------------------------- * Attaches <code>inputNode</code> event listeners. Y.
error(
'No inputNode specified.');
// Unbind first, just in case. // We're listening to the valueChange event from the // event-valuechange module here, not our own valueChange event // (which just wraps this one for convenience). * Synchronizes the UI state of the <code>inputNode</code>. * Detaches <code>inputNode</code> event listeners. // -- Protected Prototype Methods ------------------------------------------ * Returns <code>true</code> if <i>value</i> is either a function or * @method _functionValidator * @param {Function|null} value Value to validate. * Parses result responses, performs filtering and highlighting, and fires * the <code>results</code> event. * @param {String} query Query that generated these results. * @param {Object} response Response containing results. * @param {Object} data Raw response data. // Filtered result arrays representing different formats. These will // be unrolled into the final array of result objects as properties. raw,
// whatever format came back in the response // Unfiltered raw results, fresh from the response. // Final array of result objects. // In order to allow filtering based on locator queries, we have // to create a mapping of "located" results to original results // so we can sync up the original results later without // requiring the filters to do extra work. // Run the raw results through all configured result filters. // Sync up the original results with the filtered, "located" // Run the unformatted results through the configured highlighter // (if any) to produce the first stage of formatted results. // Run the highlighted results through the configured formatter (if // any) to produce the final formatted results. // Finally, unroll all the result arrays into a single array of * Returns the query portion of the specified input value, or * <code>null</code> if there is no suitable query within the input value. * In <code>autocomplete-base</code> this just returns the input value * itself, but it can be overridden to implement more complex logic, such as * adding support for query delimiters (see the * <code>autocomplete-delim</code> module). * @param {String} value input value from which to extract the query * @return {String|null} query // -- Protected Event Handlers --------------------------------------------- * Handles DataSource responses and fires the <code>results</code> event. // Ignore stale responses that aren't for the current query. * Handles <code>valueChange</code> events on the input node and fires a * <code>query</code> event when the input value meets the configured Y.
log(
'valueChange: new: "' +
value +
'"; old: "' + e.
prevVal +
'"',
'info',
'autocomplete-base');
// -- Protected Default Event Handlers ------------------------------------- * Default <code>clear</code> event handler. Sets the <code>results</code> * property to an empty array. * Default <code>query</code> event handler. Sets the <code>query</code> * property and sends a request to the DataSource if one is configured. Y.
log(
'query: "' +
query +
'"; inputValue: "' + e.
inputValue +
'"',
'info',
'autocomplete-base');
* Default <code>results</code> event handler. Sets the <code>results</code> * and <code>resultsRaw</code> properties to the latest results. },
'@VERSION@' ,{
requires:[
'array-extras',
'event-valuechange',
'node-base']});
YUI.
add(
'autocomplete-list',
function(Y) {
* Traditional autocomplete dropdown list widget, just like Mom used to make. * @submodule autocomplete-list * @class AutoCompleteList * @uses WidgetPositionAlign * @param {Object} config Configuration object. // -- Prototype Properties ------------------------------------------------- // -- Lifecycle Prototype Methods ------------------------------------------ * Fires when an autocomplete suggestion is selected from the list by * a keyboard action or mouse click. * @param {EventFacade} e Event facade with the following additional * <dt>result (Object)</dt> * AutoComplete result object. * @preventable _defResultsFn // Cache commonly used classnames and selectors for performance. Y.
error(
'No inputNode specified.');
if (!
this.
get(
'align.node')) {
'aria-autocomplete':
'list',
// -- Public Prototype Methods --------------------------------------------- * Selects the specified <i>itemNode</i>, or the current * <code>activeItem</code> if <i>itemNode</i> is not specified. * @param {Node} itemNode (optional) Item node to select. // -- Protected Prototype Methods ------------------------------------------ * Activates the next item after the currently active item. If there is no * next item and the <code>circular</code> attribute is <code>true</code>, * the first item in the list will be activated. * @method _activateNextItem // Get the next item. If there isn't a next item, circle back around // and get the first item. * Activates the item previous to the currently active item. If there is no * previous item and the <code>circular</code> attribute is * <code>true</code>, the last item in the list will be activated. * @method _activatePrevItem // Get the previous item. If there isn't a previous item, circle // back around and get the last item. * Appends the specified result <i>items</i> to the list inside a new item * @param {Array|Node|HTMLElement|String} items Result item or array of * @returns {NodeList} Added nodes. * Binds <code>inputNode</code> events, in addition to those already bound * by <code>AutoCompleteBase</code>'s public <code>bindInput()</code> // Call AutoCompleteBase's bind method first. * Clears the contents of the tray. * Creates an item node with the specified <i>content</i>. * @method _createItemNode * @param {Node|HTMLElement|String} content * @returns {Node} Item node. * Synchronizes the results displayed in the list with those in the * <i>results</i> argument, or with the <code>results</code> attribute if an * argument is not provided. * @param {Array} results (optional) Results. * Synchronizes the visibility of the tray with the <i>visible</i> argument, * or with the <code>visible</code> attribute if an argument is not * @method _syncVisibility * @param {Boolean} visible (optional) Visibility. // -- Protected Event Handlers --------------------------------------------- * Handles <code>activeItemChange</code> events. * @method _afterActiveItemChange * Handles <code>hoveredItemChange</code> events. * @method _afterHoveredItemChange * Handles <code>mouseover</code> events. * @method _afterMouseOver * Handles <code>mouseout</code> events. * Handles <code>resultsChange</code> events. * @method _afterResultsChange * Handles <code>visibleChange</code> events. * @method _afterVisibleChange * Handles <code>inputNode</code> <code>blur</code> events. // Hide the list on inputNode blur events, unless the mouse is currently // over the list (which indicates that the user is probably interacting // with it) or the tab key was pressed. * Handles <code>inputNode</code> key events. * Delegated event handler for item <code>click</code> events. // -- Protected Default Event Handlers ------------------------------------- * Default <code>select</code> event handler. // TODO: support query delimiters, typeahead completion, etc. * Item that's currently active, if any. When the user presses enter, * this is the item that will be selected. // The "align" attribute is documented in WidgetPositionAlign. * If <code>true</code>, keyboard navigation will wrap around to the * opposite end of the list when navigating past the first or last item. * Item currently being hovered over by the mouse, if any. // The "visible" attribute is documented in Widget. * See that class for API docs. },
'@VERSION@' ,{
requires:[
'autocomplete-base',
'widget',
'widget-position',
'widget-position-align',
'widget-stack'],
skinnable:
true});
YUI.
add(
'autocomplete',
function(Y){},
'@VERSION@' ,{
use:[
'autocomplete-base',
'autocomplete-list']});