autocomplete-base.js revision 2c8eaddac21fee4fadf7f19ae7acb064a353a4d9
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * Provides automatic input completion or suggestions for text input fields and
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * textareas.
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @module autocomplete
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @since 3.3.0
a89ad754cce3cfc8aee71760e10217b54020360dTripp * <code>Y.Base</code> extension that provides core autocomplete logic (but no
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * UI implementation) for a text input field or textarea. Must be mixed into a
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * <code>Y.Base</code>-derived class to be useful.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @module autocomplete
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @submodule autocomplete-base
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * Extension that provides core autocomplete logic (but no UI implementation)
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * for a text input field or textarea.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * The <code>AutoCompleteBase</code> class provides events and attributes that
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * abstract away core autocomplete logic and configuration, but does not provide
c093c1aed867e18aa4778708592e1ceb45d18cffTripp * a widget implementation or suggestion UI. For a prepackaged autocomplete
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * widget, see <code>AutoCompleteList</code>.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * This extension cannot be instantiated directly, since it doesn't provide an
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * actual implementation. It's intended to be mixed into a
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <code>Y.Base</code>-based class or widget.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <code>Y.Widget</code>-based example:
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * YUI().use('autocomplete-base', 'widget', function (Y) {
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * var MyAC = Y.Base.create('myAC', Y.Widget, [Y.AutoCompleteBase], {
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * // Custom prototype methods and properties.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * }, {
a89ad754cce3cfc8aee71760e10217b54020360dTripp * // Custom static methods and properties.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * });
a89ad754cce3cfc8aee71760e10217b54020360dTripp * // Custom implementation code.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * <code>Y.Base</code>-based example:
a89ad754cce3cfc8aee71760e10217b54020360dTripp * YUI().use('autocomplete-base', function (Y) {
a89ad754cce3cfc8aee71760e10217b54020360dTripp * var MyAC = Y.Base.create('myAC', Y.Base, [Y.AutoCompleteBase], {
a89ad754cce3cfc8aee71760e10217b54020360dTripp * initializer: function () {
a89ad754cce3cfc8aee71760e10217b54020360dTripp * this._bindUIACBase();
a89ad754cce3cfc8aee71760e10217b54020360dTripp * this._syncUIACBase();
a89ad754cce3cfc8aee71760e10217b54020360dTripp * },
a89ad754cce3cfc8aee71760e10217b54020360dTripp * // Custom prototype methods and properties.
c093c1aed867e18aa4778708592e1ceb45d18cffTripp * }, {
a89ad754cce3cfc8aee71760e10217b54020360dTripp * // Custom static methods and properties.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * });
7947db4b7d8682ea81598e3a4283e659a8103be6Tripp * // Custom implementation code.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @class AutoCompleteBase
a89ad754cce3cfc8aee71760e10217b54020360dTripp YObject = Y.Object,
a89ad754cce3cfc8aee71760e10217b54020360dTripp // AOP bindings.
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp // -- Public Events --------------------------------------------------------
c093c1aed867e18aa4778708592e1ceb45d18cffTripp * Fires after the query has been completely cleared or no longer meets the
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * minimum query length requirement.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @event clear
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @param {EventFacade} e Event facade with the following additional
a89ad754cce3cfc8aee71760e10217b54020360dTripp * properties:
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>prevVal (String)</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Value of the query before it was cleared.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @preventable _defClearFn
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Fires when the contents of the input field have changed and the input
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * value meets the criteria necessary to generate an autocomplete query.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @event query
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @param {EventFacade} e Event facade with the following additional
bf801d6851ecf7ed14742ef3639a077daecb5cf8Tripp * properties:
c093c1aed867e18aa4778708592e1ceb45d18cffTripp * <dt>inputValue (String)</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Full contents of the text input field or textarea that generated
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * the query.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>query (String)</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Autocomplete query. This is the string that will be used to
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * request completion results. It may or may not be the same as
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <code>inputValue</code>.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @preventable _defQueryFn
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Fires after query results are received from the <code>source</code>. If
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * source has been set, this event will not fire.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @event results
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @param {EventFacade} e Event facade with the following additional
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * properties:
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>data (Array|Object)</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Raw, unfiltered result data (if available).
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>query (String)</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Query that generated these results.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>results (Array)</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Array of filtered, formatted, and highlighted results. Each item in
c093c1aed867e18aa4778708592e1ceb45d18cffTripp * the array is an object with the following properties:
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>display (Node|HTMLElement|String)</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Formatted result HTML suitable for display to the user.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>raw (mixed)</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Raw, unformatted result in whatever form it was provided by the
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <code>source</code>.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>text (String)</dt>
a89ad754cce3cfc8aee71760e10217b54020360dTripp * Plain text version of the result, suitable for being inserted
a89ad754cce3cfc8aee71760e10217b54020360dTripp * into the value of a text input field or textarea when the result
7947db4b7d8682ea81598e3a4283e659a8103be6Tripp * is selected by a user.
c093c1aed867e18aa4778708592e1ceb45d18cffTripp * @preventable _defResultsFn
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp// -- Public Static Properties -------------------------------------------------
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * Whether or not to enable the browser's built-in autocomplete
c093c1aed867e18aa4778708592e1ceb45d18cffTripp * functionality for input fields.
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * @attribute allowBrowserAutocomplete
7947db4b7d8682ea81598e3a4283e659a8103be6Tripp * @type Boolean
7947db4b7d8682ea81598e3a4283e659a8103be6Tripp * @default false
a89ad754cce3cfc8aee71760e10217b54020360dTripp * Node to monitor for changes, which will generate <code>query</code>
a89ad754cce3cfc8aee71760e10217b54020360dTripp * events when appropriate. May be either an input field or a textarea.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @attribute inputNode
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @type Node|HTMLElement|String
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * @writeonce
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Maximum number of results to return. A value of <code>0</code> or less
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * will allow an unlimited number of results.
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * @attribute maxResults
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * @type Number
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @default 0
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * Minimum number of characters that must be entered before a
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * <code>query</code> event will be fired. A value of <code>0</code>
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * allows empty queries; a negative value will effectively disable all
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * <code>query</code> events.
c790ee5b4dcc7d98b68c124495c76d7d515bdc8dTripp * @attribute minQueryLength
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @type Number
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @default 1
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * Current query, or <code>null</code> if there is no current query.
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * The query might not be the same as the current value of the input
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * node, both for timing reasons (due to <code>queryDelay</code>) and
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * because when one or more <code>queryDelimiter</code> separators are
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * in use, only the last portion of the delimited input string will be
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * used as the query value.
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @attribute query
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * @type String|null
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @default null
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @readonly
a89ad754cce3cfc8aee71760e10217b54020360dTripp * Number of milliseconds to delay after input before triggering a
a89ad754cce3cfc8aee71760e10217b54020360dTripp * <code>query</code> event. If new input occurs before this delay is
a89ad754cce3cfc8aee71760e10217b54020360dTripp * over, the previous input event will be ignored and a new delay will
a89ad754cce3cfc8aee71760e10217b54020360dTripp * This can be useful both to throttle queries to a remote data source
a89ad754cce3cfc8aee71760e10217b54020360dTripp * and to avoid distracting the user by showing them less relevant
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * results before they've paused their typing.
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @attribute queryDelay
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @type Number
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @default 100
a89ad754cce3cfc8aee71760e10217b54020360dTripp * Query delimiter string. When a delimiter is configured, the input value
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * will be split on the delimiter, and only the last portion will be used in
a89ad754cce3cfc8aee71760e10217b54020360dTripp * autocomplete queries and updated when the <code>query</code> attribute is
a89ad754cce3cfc8aee71760e10217b54020360dTripp * modified.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @attribute queryDelimiter
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @type String|null
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @default null
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * Source request template. This can be a function that accepts a query as a
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * parameter and returns a request string, or it can be a string containing
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * the placeholder "{query}", which will be replaced with the actual
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * URI-encoded query.
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * While <code>requestTemplate</code> may be set to either a function or
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * a string, it will always be returned as a function that accepts a
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * query argument and returns a string.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @attribute requestTemplate
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @type Function|String|null
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * @default null
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * Array of local result filter functions. If provided, each filter
b57ff76ab2ce5f3017d61855f13ed04ab46a965cTripp * will be called with two arguments when results are received: the query
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * and an array of results (as returned by the <code>resultLocator</code>,
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * if one is set).
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * Each filter is expected to return a filtered or modified version of the
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * results, which will then be passed on to subsequent filters, then the
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * <code>resultHighlighter</code> function (if set), then the
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <code>resultFormatter</code> function (if set), and finally to
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * subscribers to the <code>results</code> event.
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * If no <code>source</code> is set, result filters will not be called.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @attribute resultFilters
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @type Array
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @default []
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Function which will be used to format results. If provided, this function
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * will be called with four arguments after results have been received and
a89ad754cce3cfc8aee71760e10217b54020360dTripp * filtered: the query, an array of raw results, an array of highlighted
a89ad754cce3cfc8aee71760e10217b54020360dTripp * results, and an array of plain text results. The formatter is expected to
a89ad754cce3cfc8aee71760e10217b54020360dTripp * return a modified copy of the results array with any desired custom
a89ad754cce3cfc8aee71760e10217b54020360dTripp * formatting applied.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * If no <code>source</code> is set, the formatter will not be called.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @attribute resultFormatter
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @type Function|null
a89ad754cce3cfc8aee71760e10217b54020360dTripp * Function which will be used to highlight results. If provided, this
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * function will be called with two arguments after results have been
a89ad754cce3cfc8aee71760e10217b54020360dTripp * received and filtered: the query and an array of filtered results. The
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * highlighter is expected to return a modified version of the results
a89ad754cce3cfc8aee71760e10217b54020360dTripp * array with the query highlighted in some form.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * If no <code>source</code> is set, the highlighter will not be called.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @attribute resultHighlighter
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @type Function|null
a89ad754cce3cfc8aee71760e10217b54020360dTripp * Locator that should be used to extract an array of results from a
a89ad754cce3cfc8aee71760e10217b54020360dTripp * non-array response.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * By default, no locator is applied, and all responses are assumed to be
a89ad754cce3cfc8aee71760e10217b54020360dTripp * arrays by default. If all responses are already arrays, you don't need to
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * define a locator.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * The locator may be either a function (which will receive the raw response
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * as an argument and must return an array) or a string representing an
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * object path, such as "foo.bar.baz" (which would return the value of
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <code>result.foo.bar.baz</code> if the response is an object).
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * While <code>resultListLocator</code> may be set to either a function or a
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * string, it will always be returned as a function that accepts a response
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * argument and returns an array.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @attribute resultListLocator
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @type Function|String|null
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Current results, or an empty array if there are no results.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @attribute results
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @type Array
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @default []
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @readonly
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * Locator that should be used to extract a plain text string from a
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * non-string result item. The resulting text value will be fed to any
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * defined filters, and will typically also be the value that ends up being
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * inserted into an input field or textarea when the user of an autocomplete
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * implementation selects a result.
6c4ec9d420df654d019b936fd06bef6f769db4cbTripp * By default, no locator is applied, and all results are assumed to be
b57ff76ab2ce5f3017d61855f13ed04ab46a965cTripp * plain text strings. If all results are already plain text strings, you
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * don't need to define a locator.
6c4ec9d420df654d019b936fd06bef6f769db4cbTripp * The locator may be either a function (which will receive the raw result
6c4ec9d420df654d019b936fd06bef6f769db4cbTripp * as an argument and must return a string) or a string representing an
6c4ec9d420df654d019b936fd06bef6f769db4cbTripp * object path, such as "foo.bar.baz" (which would return the value of
6c4ec9d420df654d019b936fd06bef6f769db4cbTripp * <code>result.foo.bar.baz</code> if the result is an object).
6c4ec9d420df654d019b936fd06bef6f769db4cbTripp * While <code>resultTextLocator</code> may be set to either a function or a
6c4ec9d420df654d019b936fd06bef6f769db4cbTripp * string, it will always be returned as a function that accepts a result
6c4ec9d420df654d019b936fd06bef6f769db4cbTripp * argument and returns a string.
b57ff76ab2ce5f3017d61855f13ed04ab46a965cTripp * @attribute resultTextLocator
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * @type Function|String|null
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * Source for autocomplete results. The following source types are
bbd1285cbb2183b7f89010412ad97ae1680b4b5eTripp * supported:
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>Array</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <i>Example:</i> <code>['first result', 'second result', 'etc']</code>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * The full array will be provided to any configured filters for each
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * query. This is an easy way to create a fully client-side autocomplete
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * implementation.
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * <dt>DataSource</dt>
9eaaa502227248d304ac9170902697d02158c1d9Tripp * A <code>DataSource</code> instance or other object that provides a
9eaaa502227248d304ac9170902697d02158c1d9Tripp * DataSource-like <code>sendRequest</code> method. See the
9eaaa502227248d304ac9170902697d02158c1d9Tripp * <code>DataSource</code> documentation for details.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>Object</dt>
4ef2f7e4cb7c7d255be077c47d542199f7bf8607Tripp * <i>Example:</i> <code>{foo: ['foo result 1', 'foo result 2'], bar: ['bar result']}</code>
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * An object will be treated as a query hashmap. If a property on the
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * object matches the current query, the value of that property will be
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * used as the response.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * The response is assumed to be an array of results by default. If the
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * response is not an array, provide a <code>resultListLocator</code> to
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * process the response and return an array.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>String (JSONP URL)</dt>
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * <i>Example:</i> <code>'http://example.com/search?q={query}&callback={callback}'</code>
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * If a URL is provided, it will be used to make a JSONP request. The
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * <code>{query}</code> placeholder will be replaced with the current
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * query, and the <code>{callback}</code> placeholder will be replaced with
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * an internally-generated JSONP callback name. Both placeholders must
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * appear in the URL, or the request will fail.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * The response is assumed to be an array of results by default. If the
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * response is not an array, provide a <code>resultListLocator</code> to
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * process the response and return an array.
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * <strong>The <code>jsonp</code> module must be loaded in order for URL
a89ad754cce3cfc8aee71760e10217b54020360dTripp * sources to work.</strong> If the <code>jsonp</code> module is not
a89ad754cce3cfc8aee71760e10217b54020360dTripp * already loaded, it will be loaded on demand if possible.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <dt>String (YQL query)</dt>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <i>Example:</i> <code>'select * from search.suggest where query="{query}"'</code>
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * If a YQL query is provided, it will be used to make a YQL request.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * The <code>{query}</code> placeholder will be replaced with the
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * current autocomplete query. This placeholder must appear in the YQL
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * query, or the request will fail.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <strong>The <code>yql</code> module must be loaded in order for YQL
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * sources to work.</strong> If the <code>yql</code> module is not
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * already loaded, it will be loaded on demand if possible.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * As an alternative to providing a source, you could also simply listen for
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * <code>query</code> events and handle them any way you see fit. Providing
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * a source is optional, but will usually be simpler.
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * @attribute source
66ca16dd76367c074fe4df1dcf7b555489a9bf85Tripp * @type Array|DataSource|Object|String|null
a89ad754cce3cfc8aee71760e10217b54020360dTripp * If the <code>inputNode</code> specified at instantiation time has a
a89ad754cce3cfc8aee71760e10217b54020360dTripp * <code>node-tokeninput</code> plugin attached to it, this attribute will
a89ad754cce3cfc8aee71760e10217b54020360dTripp * be a reference to the <code>Y.Plugin.TokenInput</code> instance.
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @attribute tokenInput
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @type Plugin.TokenInput
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @readonly
a89ad754cce3cfc8aee71760e10217b54020360dTripp * Current value of the input node.
a89ad754cce3cfc8aee71760e10217b54020360dTripp * @attribute value
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @type String
c7ba96d16d58075a9ab8d5c1e46c6c83ce11cb4eTripp * @default ''
a89ad754cce3cfc8aee71760e10217b54020360dTripp // Why duplicate this._inputNode.get('value')? Because we need a
a89ad754cce3cfc8aee71760e10217b54020360dTripp // reliable way to track the source of value changes. We want to perform
a89ad754cce3cfc8aee71760e10217b54020360dTripp // completion when the user changes the value, but not when we change
a89ad754cce3cfc8aee71760e10217b54020360dTripp // the value.
09688ec5ffb8b9cf9883a770e2f9ebd60b28888dTripp * URL protocol to use when the <code>source</code> is set to a YQL query.
yqlProtocol: {
var request,
if (source) {
if (!requestTemplate) {
callback: {
_bindUIACBase: function () {
if (tokenInput) {
if (!inputNode) {
this._acBaseEvents = [
_destructorACBase: function () {
_syncUIACBase: function () {
this._syncBrowserAutocomplete();
var that = this;
var cache = {},
jsonpSource = {},
that = this,
if (!loading) {
loading = true;
return jsonpSource;
that = this;
var cache = {},
yqlSource = {},
that = this,
var yqlRequest,
if (yqlRequest) {
if (!loading) {
loading = true;
return yqlSource;
results = [];
return results;
if (!obj) {
return obj;
if (requestTemplate) {
var facade = {
results: []
results = [],
len,
if (unfiltered) {
if (textLocator) {
if (textLocator) {
raw = [];
if (formatter) {
results[i] = {
if (delim) {
return locator;
var that = this;
return function (result) {
return template;
return function (query) {
if (filters === null) {
return filter;
var acHighlighters;
return highlighter;
return INVALID_VALUE;
return source;
return INVALID_VALUE;
_syncBrowserAutocomplete: function () {
len,
if (delim) {
_afterValueChange: function (e) {
var delay,
fire,
that;
that = this;
fire = function () {
if (delay) {
fire();
_onInputValueChange: function (e) {
_defClearFn: function () {
_defQueryFn: function (e) {
_defResultsFn: function (e) {